Encryption API for C-Core SDK

PubNub C-Core SDK provides built-in message encryption to secure your real-time communications. This documentation covers configuration options specific to C-Core encryption behavior and detailed crypto module configuration.

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

Configuration options

These preprocessor definitions control encryption behavior and are configured in your pubnub_config.h header file.

PUBNUB_CRYPTO_API: enable automatic encryption/decryption

Set to true (!=0) to enable automatic encryption/decryption (publish, subscribe, message persistence) provided the pubnub_crypto_provider_t has been configured. Note that you must call the pubnub_set_crypto_module() function with the correct provider for your client to use the configured crypto module for automatic encryption/decryption. Otherwise, no encryption will be enabled.

Set to false (==0) to only return pubnub_crypto_provider_t but you will need to use it manually.

PUBNUB_RAND_INIT_VECTOR: use random initialization vector

When true (default) the initialization vector (IV) is random for all requests. When false the IV is hard-coded for all requests. This setting is true by default.

Disabling random initialization vector

Disable random initialization vector (IV) only for backward compatibility (<3.0.0) with existing applications. Never disable random IV on new applications.

Configuration

Crypto modules

These functions are used to configure the cryptography module used for encryption and decryption.

The crypto provider provides encrypt/decrypt functionality for messages. From the 4.4.0 release on, you can configure how the actual encryption/decryption algorithms work.

Each PubNub SDK is bundled with two ways of encryption: the legacy encryption with 128-bit cipher key entropy and the recommended 256-bit AES-CBC encryption. For more general information on how encryption works, refer to Message Encryption.

Legacy encryption with 128-bit cipher key entropy

You don't have to change your encryption configuration if you want to keep using the legacy encryption. If you want to use the recommended 256-bit AES-CBC encryption, you must explicitly set that in PubNub config.

Your client can decrypt content encrypted using either of the modules. This way, you can interact with historical messages or messages sent from older clients while encoding new messages using the more secure 256-bit AES-CBC cipher.

Older SDK versions

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

SDK Initialization required

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

Method(s)

To configure the cryptography module use following method(s) in the C-Core SDK:

Configure local legacy module

 struct pubnub_crypto_provider_t *legacy_crypto_module = pubnub_crypto_legacy_module_init( cipher_key);

Configure local AES CBC module

struct pubnub_crypto_provider_t *crypto_module = pubnub_crypto_aes_cbc_module_init(cipher_key);

Configure client legacy module

pubnub_set_crypto_module(pbp, pubnub_crypto_legacy_module_init(cipher_key));

Configure client AES CBC module

pubnub_set_crypto_module(pbp, pubnub_crypto_aes_cbc_module_init(cipher_key));

Sample code

int main()
{
    char const *msg = "Hello world";
    char const *cipher_key = "enigma";

    printf("message to be encrypted: %s\n\n", msg);

    pubnub_bymebl_t block;
    block.ptr = (uint8_t*)msg;
    block.size = strlen(msg);

    struct pubnub_crypto_provider_t *legacy_crypto_module = pubnub_crypto_legacy_module_init((uint8_t*) cipher_key);
    pubnub_bymebl_t legacy_encrypt_result = legacy_crypto_module->encrypt(legacy_crypto_module, block);

    pubnub_bymebl_t kekw = legacy_crypto_module->decrypt(legacy_crypto_module, (pubnub_bymebl_t){.ptr = "½Àî–îˆùE߇E®6uPÂ", .size = 30});

show all 51 lines

Configure AES CBC crypto module on the client for automatic encryption

// assuming the PUBNUB_CRYPTO_API is true

uint8_t* cipher_key = (uint8_t*) "enigma";

pubnub_set_crypto_module(pbp, pubnub_crypto_aes_cbc_module_init(cipher_key));