Secure Cell passphrase API: ObjCThemis

CHANGELOG.md

@@ -88,14 +88,38 @@ _Code:_
 
   - New function `TSGenerateSymmetricKey()` (available in Objective-C and Swift) can be used to generate symmetric keys for Secure Cell ([#561](https://github.com/cossacklabs/themis/pull/561)).
 
-  - Secure Cell API updates ([#606](https://github.com/cossacklabs/themis/pull/606)).
+  - Secure Cell API updates:
 
-    - New encryption/decryption API with consistent naming: `encrypt` and `decrypt`.
+    - New encryption/decryption API with consistent naming: `encrypt` and `decrypt` ([#606](https://github.com/cossacklabs/themis/pull/606)).
 
-    - Improved Token Protect API:
+    - Improved Token Protect API ([#606](https://github.com/cossacklabs/themis/pull/606)):
       - Encryption results use `NSData` now which bridges with Swift `Data` directly.
       - Decryption no longer requires an intermediate `TSCellTokenEncryptedData` object.
 
+    - ObjCThemis now supports _passphrase API_ of in Seal mode ([#609](https://github.com/cossacklabs/themis/pull/609)).
+
+      In Swift:
+
+      ```swift
+      let cell = TSCellSeal(passphrase: "secret")
+
+      let encrypted = try cell.encrypt("message".data(using: .utf8)!)
+      let decrypted = try cell.decrypt(encrypted)
+      ```
+
+      In Objective-C:
+
+      ```objective-c
+      TSCellSeal *cell = [[TSCellSeal alloc] initWithPassphrase:@"secret"];
+
+      NSData *encrypted = [cell encrypt:[@"message" dataUsingEncoding:NSUTF8StringEncoding]];
+      NSData *decrypted = [cell decrypt:encrypted];
+      ```
+
+      You can safely and securely use human-readable passphrases as strings with this new API.
+
+      Existing master key API (`TSCellSeal(key: ...)` or `initWithKey:...`) is not secure when used with passphrases. You should only use it with symmetric encryption keys, such as generated by `TSGenerateSymmetricKey()` ([#561](https://github.com/cossacklabs/themis/pull/561)).
+
   - **Deprecated API**
 
     - Secure Cell wrapData/unwrapData renamed into encrypt/decrypt ([#606](https://github.com/cossacklabs/themis/pull/606)).

src/wrappers/themis/Obj-C/objcthemis/scell_seal.h

@@ -66,7 +66,44 @@ NS_ASSUME_NONNULL_BEGIN
  *
  * @returns @c nil if key is empty.
  */
-- (nullable instancetype)initWithKey:(NSData *)key;
+- (nullable instancetype)initWithKey:(NSData *)key
+    NS_DESIGNATED_INITIALIZER;
+
+/**
+ * Initialise Secure Cell in Seal mode with a passphrase.
+ *
+ * @param [in] passphrase   non-empty passphrase to use
+ *
+ * The passphrase string will be encoded in UTF-8.
+ *
+ * @returns @c nil if passphrase is empty.
+ */
+- (nullable instancetype)initWithPassphrase:(NSString *)passphrase;
+
+/**
+ * Initialise Secure Cell in Seal mode with a passphrase.
+ *
+ * @param [in] passphrase   non-empty passphrase
+ * @param [in] encoding     passphrase encoding
+ *
+ * @returns @c nil if passphrase is empty or cannot be encoded without data loss.
+ */
+- (nullable instancetype)initWithPassphrase:(NSString *)passphrase
+                              usingEncoding:(NSStringEncoding)encoding
+    // NSStringEncoding translates into UInt in Swift which is not correct.
+    // We cannot use NS_REFINED_FOR_SWIFT because we cannot ship Swift code
+    // in our framework without ABI stability guarantees. Sorry, Swift users,
+    // but you'll have to encode your passphrases explicitly for now.
+    NS_SWIFT_UNAVAILABLE("cannot export for Swift directly");
+
+/**
+ * Initialise Secure Cell in Seal mode with raw passphrase data.
+ *
+ * @param [in] passphrase   non-empty passphrase to use
+ *
+ * @returns @c nil if passphrase is empty.
+ */
+- (nullable instancetype)initWithPassphraseData:(NSData *)passphrase;
 
 /**
  * Encrypt data.

src/wrappers/themis/Obj-C/objcthemis/scell_seal.m

@@ -18,13 +18,38 @@
 #import <objcthemis/serror.h>
 #import <themis/themis.h>
 
+@interface TSCellSealWithPassphrase : TSCellSeal
+@end
+
 @implementation TSCellSeal
 
 - (nullable instancetype)initWithKey:(NSData *)key {
     self = [super initWithKey:key];
     return self;
 }
 
+- (nullable instancetype)initWithPassphrase:(NSString *)passphrase
+{
+    return [self initWithPassphrase:passphrase usingEncoding:NSUTF8StringEncoding];
+}
+
+- (nullable instancetype)initWithPassphrase:(NSString *)passphrase
+                              usingEncoding:(NSStringEncoding)encoding
+{
+    NSData *encoded = [passphrase dataUsingEncoding:encoding];
+    if (!encoded) {
+        return nil;
+    }
+    return [self initWithPassphraseData:encoded];
+}
+
+- (nullable instancetype)initWithPassphraseData:(NSData *)passphrase
+{
+    self = [TSCellSealWithPassphrase alloc];
+    self = [self initWithPassphraseData:passphrase];
+    return self;
+}
+
 #pragma mark - Encryption
 
 - (nullable NSData *)encrypt:(NSData *)message
@@ -161,3 +186,100 @@ - (nullable NSData *)unwrapData:(NSData *)message error:(NSError **)error
 }
 
 @end
+
+@implementation TSCellSealWithPassphrase
+
+- (nullable instancetype)initWithPassphraseData:(NSData *)passphrase
+{
+    // Call grandparent TSCell initializer. We store the passphrase as a "key".
+    self = [super initWithKey:passphrase];
+    return self;
+}
+
+- (nullable NSData *)encrypt:(NSData *)data
+                     context:(nullable NSData *)context
+                       error:(NSError **)error
+{
+    themis_status_t res = THEMIS_FAIL;
+
+    size_t encryptedLengh = 0;
+    res = themis_secure_cell_encrypt_seal_with_passphrase(self.key.bytes,
+                                                          self.key.length,
+                                                          context.bytes,
+                                                          context.length,
+                                                          data.bytes,
+                                                          data.length,
+                                                          NULL,
+                                                          &encryptedLengh);
+    if (res != THEMIS_BUFFER_TOO_SMALL) {
+        if (error) {
+            *error = SCERROR(res, @"Secure Cell encryption failed");
+        }
+        return nil;
+    }
+
+    NSMutableData *encryptedData = [NSMutableData dataWithLength:encryptedLengh];
+
+    res = themis_secure_cell_encrypt_seal_with_passphrase(self.key.bytes,
+                                                          self.key.length,
+                                                          context.bytes,
+                                                          context.length,
+                                                          data.bytes,
+                                                          data.length,
+                                                          encryptedData.mutableBytes,
+                                                          &encryptedLengh);
+    if (res != THEMIS_SUCCESS) {
+        if (error) {
+            *error = SCERROR(res, @"Secure Cell encryption failed");
+        }
+        return nil;
+    }
+
+    [encryptedData setLength:encryptedLengh];
+    return encryptedData;
+}
+
+- (nullable NSData *)decrypt:(NSData *)data
+                     context:(nullable NSData *)context
+                       error:(NSError **)error
+{
+    themis_status_t res = THEMIS_FAIL;
+
+    size_t decryptedLengh = 0;
+    res = themis_secure_cell_decrypt_seal_with_passphrase(self.key.bytes,
+                                                          self.key.length,
+                                                          context.bytes,
+                                                          context.length,
+                                                          data.bytes,
+                                                          data.length,
+                                                          NULL,
+                                                          &decryptedLengh);
+    if (res != THEMIS_BUFFER_TOO_SMALL) {
+        if (error) {
+            *error = SCERROR(res, @"Secure Cell decryption failed");
+        }
+        return nil;
+    }
+
+    NSMutableData *decryptedData = [NSMutableData dataWithLength:decryptedLengh];
+
+    res = themis_secure_cell_decrypt_seal_with_passphrase(self.key.bytes,
+                                                          self.key.length,
+                                                          context.bytes,
+                                                          context.length,
+                                                          data.bytes,
+                                                          data.length,
+                                                          decryptedData.mutableBytes,
+                                                          &decryptedLengh);
+    if (res != THEMIS_SUCCESS) {
+        if (error) {
+            *error = SCERROR(res, @"Secure Cell decryption failed");
+        }
+        return nil;
+    }
+
+    [decryptedData setLength:decryptedLengh];
+    return decryptedData;
+}
+
+@end