Encryption API for Objective-C SDK

PubNub Objective-C SDK includes message encryption. This page explains how to configure the cryptoModule and how to encrypt and decrypt data. The SDK supports 128-bit Advanced Encryption Standard (AES) and 256-bit AES in Cipher Block Chaining (CBC) mode (AES-CBC).

For general SDK configuration and initialization, refer to the Configuration page.

Configuration

cryptoModule configuration

To configure the cryptoModule to encrypt all messages/files, you can use the following methods in the Objective-C SDK:

// encrypts using 256-bit AES-CBC cipher (recommended)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
config.cryptoModule = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma"
                                           randomInitializationVector:YES];

// encrypts with 128-bit cipher key entropy (legacy)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
config.cryptoModule = [PNCryptoModule legacyCryptoModuleWithCipherKey:@"enigma" 
                                           randomInitializationVector:YES];

The client can decrypt content from either module. You can read historical messages and messages from older clients, and you can encrypt new messages with 256-bit AES-CBC.

Older SDK versions

Apps built using the SDK versions lower than 5.1.3 will not be able to decrypt data encrypted using the 256-bit AES-CBC cipher. Update your clients or encrypt data using the legacy algorithm.

SDK initialization required

Before you use encryption methods, ensure your PubNub client is configured with a subscribe key and a user ID. See the Configuration guide for setup instructions.

Relationship between cryptoModule and cipher keys

The cryptoModule supersedes cipher-key parameters. Passing a direct cipher key to a method (where available) overrides the configured cryptoModule for that operation and uses legacy AES-128 encryption. For partial encryption, create a separate cryptoModule instance and use it only where needed.

Encryption methods

Encrypt

Use this function to encrypt data.

Deprecated

This method uses the legacy encryption with 128-bit cipher key entropy. For more information, refer to Crypto module configuration.

Method(s)

To encrypt the data you can use the following method(s) in Objective-C SDK.

+ (nullable NSString *)encrypt:(NSData *)data
                       withKey:(NSString *)key;

* required

Parameter	Description
data * Type: NSData	Reference on NSData object which should be encrypted.
key * Type: NSString	Reference on key which should be used to encrypt data basing on it.

+ (nullable NSString *)encrypt:(NSData *)data 
                       withKey:(NSString *)key 
                      andError:(NSError *__autoreleasing *)error;

* required

Parameter	Description
data * Type: NSData	Reference on NSData object which should be encrypted.
key * Type: NSString	Reference on key which should be used to encrypt data basing on it.
error Type: NSError	Reference on pointer into which encryption error will be stored in case of encryption failure. Error can be related to JSON string serialization and encryption itself.

Sample code

Encrypt part of message

PNCryptoModule *aesCBCCrypto = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma" randomInitializationVector:YES];

NSString *message = @"No one should see me as plain";
NSData *messageData = [message dataUsingEncoding:NSUTF8StringEncoding];
NSString *secretMessage = [aesCBCCrypto encrypt:messageData];

Returns

Encrypted Base64-encoded string received from Foundation object. nil will be returned in case of failure.

Decryption methods

Decrypt

Use this function to decrypt data.

Deprecated

This method uses the legacy encryption with 128-bit cipher key entropy. For more information, refer to Crypto module configuration.

Method(s)

To decrypt the data you can use the following method(s) in Objective-C SDK.

+ (nullable NSData *)decrypt:(NSString *)object 
                     withKey:(NSString *)key;

* required

Parameter	Description
object * Type: NSString	Reference on previously encrypted Base64-encoded string which should be decrypted.
key * Type: NSString	Reference on key which should be used to decrypt data.

+ (nullable NSData *)decrypt:(NSString *)object 
                     withKey:(NSString *)key 
                    andError:(NSError *__autoreleasing *)error;

* required

Parameter	Description
object * Type: NSString	Reference on previously encrypted Base64-encoded string which should be decrypted.
key * Type: NSString	Reference on key which should be used to decrypt data.
error Type: NSError	Reference on pointer into which decryption error will be stored in case of decryption failure. Error can be related to JSON string deserialization and decryption itself.

Sample code

Decrypt part of message

PNCryptoModule *aesCBCCrypto = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma" randomInitializationVector:YES];

NSString *encryptedMessage = messagePayload[@"secret"];
NSData *secureData = [[NSData alloc] initWithBase64EncodedString:encryptedMessage options:0];
NSData *messageData = [aesCBCCrypto decrypt:secureData];
NSString *decryptedMessage = [[NSString alloc] initWithData:messageData encoding:NSUTF8StringEncoding];

Returns

Initial NSData which has been encrypted earlier. nil will be returned in case of decryption error.