---
source_url: https://www.pubnub.com/docs/sdks/c-core/api-reference/encryption
title: Encryption API for C-Core SDK
updated_at: 2026-05-20T11:06:12.959Z
sdk_name: PubNub C/C++ Core SDK
sdk_version: 7.2.2
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Encryption API for C-Core SDK

PubNub C/C++ Core SDK, use the latest version: 7.2.2

PubNub C-Core SDK provides built-in message encryption. This page covers configuration options specific to C-Core encryption and crypto module configuration.

For general SDK configuration and initialization, refer to the [Configuration](https://www.pubnub.com/docs/sdks/c-core/api-reference/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.

:::warning 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](https://www.pubnub.com/docs/general/setup/data-security#message-encryption).

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

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

:::note 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](https://www.pubnub.com/docs/sdks/c-core/api-reference/configuration#initialization) for setup instructions.
:::

#### Method(s)

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

##### Configure local legacy module

```c
struct pubnub_crypto_provider_t *legacy_crypto_module = pubnub_crypto_legacy_module_init( cipher_key);
```

##### Configure local AES CBC module

```c
struct pubnub_crypto_provider_t *crypto_module = pubnub_crypto_aes_cbc_module_init(cipher_key);
```

##### Configure client legacy module

```c
pubnub_set_crypto_module(pbp, pubnub_crypto_legacy_module_init(cipher_key));
```

##### Configure client AES CBC module

```c
pubnub_set_crypto_module(pbp, pubnub_crypto_aes_cbc_module_init(cipher_key));
```

#### Sample code

```c
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});

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

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

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

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

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

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

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

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

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

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

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

##### Configure AES CBC crypto module on the client for automatic encryption

```c
// 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));
```

## Terms in this document

* **Subscribe Key** - A unique identifier that allows your application to receive messages from PubNub channels. It's part of your app's credentials and should be kept secure.
* **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username.
* **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.