ObjCThemis: Secure Cell API update

CHANGELOG.md

@@ -88,6 +88,88 @@ _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)).
+
+    - New encryption/decryption API with consistent naming: `encrypt` and `decrypt`.
+
+    - Improved Token Protect API:
+      - Encryption results use `NSData` now which bridges with Swift `Data` directly.
+      - Decryption no longer requires an intermediate `TSCellTokenEncryptedData` object.
+
+  - **Deprecated API**
+
+    - Secure Cell wrapData/unwrapData renamed into encrypt/decrypt ([#606](https://github.com/cossacklabs/themis/pull/606)).
+
+      As a result, the following methods are deprecated. There are no plans for their removal.
+
+      <details>
+      <summary>Swift</summary>
+      <table>
+        <tr><th>Mode</th><th>Deprecation</th><th>Replacement</th></tr>
+        <tr>
+          <td rowspan=2><code>TSCellSeal</code></td>
+          <td><code>wrap(_:, context:)</code><br/><code>wrap</code></td>
+          <td><code>encrypt(_:, context:)</code><br/><code>encrypt</code></td>
+        </tr>
+        <tr>
+          <td><code>unwrapData(_:, context:)</code><br/><code>unwrapData</code></td>
+          <td><code>decrypt(_:, context:)</code><br/><code>decrypt</code></td>
+        </tr>
+        <tr>
+          <td rowspan=2><code>TSCellToken</code></td>
+          <td><code>wrap(_:, context:)</code><br/><code>wrap</code></td>
+          <td><code>encrypt(_:, context:)</code><br/><code>encrypt</code></td>
+        </tr>
+        <tr>
+          <td><code>unwrapData(_:, context:)</code><br/><code>unwrapData</code></td>
+          <td><code>decrypt(_:, token:, context:)</code><br/><code>decrypt(_:, token:)</code></td>
+        </tr>
+        <tr>
+          <td rowspan=2><code>TSCellContextImprint</code></td>
+          <td><code>wrap(_:, context:)</code><br/><code>wrap</code></td>
+          <td><code>encrypt(_:, context:)</code><br/><code>encrypt</code></td>
+        </tr>
+        <tr>
+          <td><code>unwrapData(_:, context:)</code><br/><code>unwrapData</code></td>
+          <td><code>decrypt(_:, context:)</code><br/><code>decrypt</code></td>
+        </tr>
+      </table>
+      </details>
+
+      <details>
+      <summary>Objective-C</summary>
+      <table>
+        <tr><th>Mode</th><th>Deprecation</th><th>Replacement</th></tr>
+        <tr>
+          <td rowspan=2><code>TSCellSeal</code></td>
+          <td><code>wrapData:context:error:</code><br><code>wrapData:error:</code></td>
+          <td><code>encrypt:context:error:</code><br><code>encrypt:error:</code></td>
+        </tr>
+        <tr>
+          <td><code>unwrapData:context:error:</code><br><code>unwrapData:error:</code></td>
+          <td><code>decrypt:context:error:</code><br><code>decrypt:error:</code></td>
+        </tr>
+        <tr>
+          <td rowspan=2><code>TSCellToken</code></td>
+          <td><code>wrapData:context:error:</code><br><code>wrapData:error:</code></td>
+          <td><code>encrypt:context:error:</code><br><code>encrypt:error:</code></td>
+        </tr>
+        <tr>
+          <td><code>unwrapData:context:error:</code><br><code>unwrapData:error:</code></td>
+          <td><code>decrypt:token:context:error:</code><br><code>decrypt:token:error:</code></td>
+        </tr>
+        <tr>
+          <td rowspan=2><code>TSCellContextImprint</code></td>
+          <td><code>wrapData:context:error:</code><br><code>wrapData:error:</code></td>
+          <td><code>encrypt:context:error:</code><br><code>encrypt:error:</code></td>
+        </tr>
+        <tr>
+          <td><code>unwrapData:context:error:</code><br><code>unwrapData:error:</code></td>
+          <td><code>decrypt:context:error:</code><br><code>decrypt:error:</code></td>
+        </tr>
+      </table>
+      </details>
+
   - **Breaking changes**
 
     - <a id="0.13.0-objcthemis-rename">ObjCThemis framework built by Carthage is now called `objcthemis.framework`</a> ([#604](https://github.com/cossacklabs/themis/pull/604)).

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

@@ -29,46 +29,115 @@
  * @{
  */
 
-/** @brief Secure Cell Context Imprint mode interface
-*
-* This object mode is for environments where storage constraints do not allow the size of the data to grow and
-* there is no auxiliary storage available. Secure Cell context imprint relies on the user to provide the data context
-* along with the secret to protect the information. Also, no authentication tag is computed or verified.
-* This means the integrity of the data is not enforced, so the overall security level is slightly lower than preceding
-* two cases.
-*
-* @image html scell-context_imprint.png Secure Cell Context imprint mode
-* @note To ensure highest security level possible user has to supply different context for each encryption invocation
-* of the object for the same secret.
-*/
-
 NS_ASSUME_NONNULL_BEGIN
 
+/**
+ * Secure Cell in Context Imprint mode.
+ *
+ * Context Imprint mode is intended for environments where storage constraints
+ * do not allow the size of the data to grow and there is no auxiliary storage
+ * available. Context Imprint mode requires an additional "associated context"
+ * to be provided along with the secret in order to protect the data.
+ *
+ * In Context Imprint mode no authentication token is computed or verified.
+ * This means the integrity of the data is not enforced, so the overall
+ * security level is slightly lower than in Seal or Token Protect modes.
+ *
+ * @note To ensure highest security level possible, supply a different
+ * associated context for each encryption invocation with the same secret.
+ *
+ * Read more about Context Imprint mode:
+ *
+ * https://docs.cossacklabs.com/pages/secure-cell-cryptosystem/#context-imprint-mode
+ */
 @interface TSCellContextImprint : TSCell
 
 /**
-* @brief Initialize Secure cell object in context imprint mode
-* @param [in] key master key
-*/
+ * Initialise Secure Cell in Context Imprint mode with a master key.
+ *
+ * @param [in] key  non-empty master key
+ *
+ * @returns @c nil if key is empty.
+ */
 - (nullable instancetype)initWithKey:(NSData *)key;
 
 /**
-* @brief Wrap message with context
-* @param [in] message message to wrap
-* @param [in] context user context
-* @param [in] error pointer to Error on failure
-* @return Wrapped message as NSData object on success or nil on failure
-*/
-- (nullable NSData *)wrapData:(NSData *)message context:(NSData *)context error:(NSError **)error;
+ * Encrypt data.
+ *
+ * @param [in]  message data to encrypt, must not be empty
+ * @param [in]  context associated context, must not be empty
+ * @param [out] error   optional error output
+ *
+ * Data is encrypted and context is cryptographically mixed with the data, but not included
+ * into the resulting encrypted message. You will have to provide the same context again
+ * during decryption. Usually this is some plaintext data associated with encrypted data,
+ * such as database row number, protocol message ID, etc.
+ *
+ * @returns Encrypted data has the same length as input and cannot be authenticated.
+ *
+ * @returns @c nil will be returned on failure, such as if @c message or @c context is empty
+ * or in case of some internal failure in cryptographic backend.
+ *
+ * @returns If @c error is not @c nil, it will describe the reason of failure.
+ */
+- (nullable NSData *)encrypt:(NSData *)message
+                     context:(NSData *)context
+                       error:(NSError **)error;
 
 /**
-* @brief Unwrap message with context
-* @param [in] message message to unwrap
-* @param [in] context user context
-* @param [in] error pointer to Error on failure
-* @return Unwrapped message as NSData object on success or nil on failure
-*/
-- (nullable NSData *)unwrapData:(NSData *)message context:(NSData *)context error:(NSError **)error;
+ * Encrypt data.
+ * @see encrypt:context:error:
+ */
+- (nullable NSData *)encrypt:(NSData *)message context:(NSData *)context
+    NS_SWIFT_UNAVAILABLE("use throwing encrypt(_:,context:)");
+
+/**
+ * Encrypt data.
+ * @deprecated since Themis 0.13
+ * @see encrypt:context:error:
+ */
+- (nullable NSData *)wrapData:(NSData *)message context:(NSData *)context error:(NSError **)error
+    __deprecated_msg("use 'encrypt:context:error:' instead");
+
+/**
+ * Decrypt data.
+ *
+ * @param [in]  message data to decrypt, cannot be empty
+ * @param [in]  context associated context, cannot be empty
+ * @param [out] error   optional error output
+ *
+ * Secure Cell validates association with the context data and decrypts the message.
+ * You need to provide the same context as it was used during encryption.
+ *
+ * @returns Decrypted data is returned if everything goes well.
+ *
+ * @returns Note that data integrity is not verified by Context Imprint mode:
+ * garbage in — garbage out. If data has been corrupted or context is incorrect
+ * then Secure Cell will most likely successfully return corrupted output.
+ *
+ * @returns @c nil will be returned on failure, such as if @c message or @c context
+ * is empty, or in case of some internal failure in cryptographic backend.
+ *
+ * @returns If @c error is not @c nil, it will describe the reason of failure.
+ */
+- (nullable NSData *)decrypt:(NSData *)message
+                     context:(NSData *)context
+                       error:(NSError **)error;
+
+/**
+ * Decrypt data.
+ * @see decrypt:context:error:
+ */
+- (nullable NSData *)decrypt:(NSData *)message context:(NSData *)context
+    NS_SWIFT_UNAVAILABLE("use throwing decrypt(_:,context:)");
+
+/**
+ * Decrypt data.
+ * @deprecated since Themis 0.13
+ * @see decrypt:context:error:
+ */
+- (nullable NSData *)unwrapData:(NSData *)message context:(NSData *)context error:(NSError **)error
+    __deprecated_msg("use 'decrypt:context:error:' instead");
 
 @end
 

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

@@ -25,8 +25,12 @@ - (nullable instancetype)initWithKey:(NSData *)key {
     return self;
 }
 
+#pragma mark - Encryption
 
-- (nullable NSData *)wrapData:(NSData *)message context:(NSData *)context error:(NSError **)error {
+- (nullable NSData *)encrypt:(NSData *)message
+                     context:(NSData *)context
+                       error:(NSError **)error
+{
     size_t wrappedMessageLength = 0;
 
     TSErrorType encryptionResult = (TSErrorType) themis_secure_cell_encrypt_context_imprint([self.key bytes], [self.key length],
@@ -55,8 +59,22 @@ - (nullable NSData *)wrapData:(NSData *)message context:(NSData *)context error:
     return [NSData dataWithBytesNoCopy:wrappedMessage length:wrappedMessageLength];
 }
 
+- (nullable NSData *)encrypt:(NSData *)message context:(NSData *)context
+{
+    return [self encrypt:message context:context error:nil];
+}
+
+- (nullable NSData *)wrapData:(NSData *)message context:(NSData *)context error:(NSError **)error
+{
+    return [self encrypt:message context:context error:error];
+}
+
+#pragma mark - Decryption
 
-- (nullable NSData *)unwrapData:(NSData *)message context:(NSData *)context error:(NSError **)error {
+- (nullable NSData *)decrypt:(NSData *)message
+                     context:(NSData *)context
+                       error:(NSError **)error
+{
     size_t unwrappedMessageLength = 0;
 
     int decryptionResult = themis_secure_cell_decrypt_context_imprint([self.key bytes], [self.key length],
@@ -85,4 +103,14 @@ - (nullable NSData *)unwrapData:(NSData *)message context:(NSData *)context erro
     return [NSData dataWithBytesNoCopy:unwrappedMessage length:unwrappedMessageLength];
 }
 
+- (nullable NSData *)decrypt:(NSData *)message context:(NSData *)context
+{
+    return [self decrypt:message context:context error:nil];
+}
+
+- (nullable NSData *)unwrapData:(NSData *)message context:(NSData *)context error:(NSError **)error
+{
+    return [self decrypt:message context:context error:error];
+}
+
 @end