Encryption API for C-Core (legacy) SDK

New SDK available

C-Core (legacy) is still supported. If you are starting a new project, use the new C SDK.

PubNub C-Core (legacy) SDK provides built-in message encryption. This page covers configuration options specific to C-Core (legacy) encryption and 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 onward, you can configure the algorithms it uses.

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.

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 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 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.

Method(s)

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

Configure local legacy module

1 struct pubnub_crypto_provider_t *legacy_crypto_module = pubnub_crypto_legacy_module_init( cipher_key);

Configure local AES CBC module

1struct pubnub_crypto_provider_t *crypto_module = pubnub_crypto_aes_cbc_module_init(cipher_key);

Configure client legacy module

1pubnub_set_crypto_module(pbp, pubnub_crypto_legacy_module_init(cipher_key));

Configure client AES CBC module

1pubnub_set_crypto_module(pbp, pubnub_crypto_aes_cbc_module_init(cipher_key));

Sample code

1int main()
2{
3    char const *msg = "Hello world";
4    char const *cipher_key = "enigma";
5

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

8    pubnub_bymebl_t block;
9    block.ptr = (uint8_t*)msg;
10    block.size = strlen(msg);
11

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

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

17    if (NULL == legacy_encrypt_result.ptr) {
18        printf("encrypt with legacy AES-CBC failed\n");
19        return -1;
20    }
21

22    print_encrypted_message("encrypt with legacy AES-CBC result", legacy_encrypt_result);
23

24    struct pubnub_crypto_provider_t *crypto_module = pubnub_crypto_aes_cbc_module_init((uint8_t*)cipher_key);
25    pubnub_bymebl_t encrypt_result = crypto_module->encrypt(crypto_module, block);
26

27    if (NULL == encrypt_result.ptr) {
28        printf("encrypt with enhanced AES-CBC failed\n");
29        return -1;
30    }
31

32    print_encrypted_message("encrypt with enhanced AES-CBC result", encrypt_result);
33

34    pubnub_bymebl_t legacy_decrypt_result = crypto_module->decrypt(crypto_module, legacy_encrypt_result);
35

36    if (NULL == legacy_decrypt_result.ptr) {
37        printf("decrypt with legacy AES-CBC failed\n");
38        return -1;
39    }
40

41    printf("decrypt with legacy AES-CBC result: %s\n", legacy_decrypt_result.ptr);
42

43    pubnub_bymebl_t decrypt_result = legacy_crypto_module->decrypt(legacy_crypto_module, encrypt_result);
44

45    if (NULL == decrypt_result.ptr) {
46        printf("decrypt with enhanced AES-CBC failed\n");
47        return -1;
48    }
49

50    printf("decrypt with enhanced AES-CBC result: %s\n", decrypt_result.ptr);
51}

show all 51 lines

Configure AES CBC crypto module on the client for automatic encryption

1// assuming the PUBNUB_CRYPTO_API is true
2

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

5pubnub_set_crypto_module(pbp, pubnub_crypto_aes_cbc_module_init(cipher_key));