---
source_url: https://www.pubnub.com/docs/general/resources/migration-guides/256-bit-encryption-migration
title: 256-bit AES-CBC Encryption Migration Guide
updated_at: 2026-06-19T11:36:04.858Z
---

> 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


# 256-bit AES-CBC Encryption Migration Guide

Upgrading to the recommended 256‑bit AES‑CBC (Advanced Encryption Standard in Cipher Block Chaining mode) encryption is a two‑step process:

1. [Upgrade to the latest SDK](#upgrade-to-the-latest-sdk)
2. [Activate 256-bit encryption](#activate-256-bit-encryption)

### Upgrade to the latest SDK

Access to the 256‑bit algorithm is available in the PubNub SDK. Upgrade your client SDK to a supported version.

Check your SDK changelog for “Add crypto module” to find the minimum version. Prefer the latest SDK.

:::warning Older SDK versions
SDKs released before October 2023 don’t include 256‑bit AES‑CBC, so they can’t decrypt AES‑CBC data. The `CryptoModule` can decrypt data encrypted with both the legacy cipher and the recommended ciphers.
:::

#### If cipherKey is present in PubNub config

The PubNub configuration now accepts a `CryptoModule`, replacing the existing `cipherKey` and `useRandomIVs` parameters (names vary between SDKs). `CryptoModule` configures data encryption and decryption when you send and receive messages and files.

To allow all your clients to decrypt messages while you roll out SDK updates:

```javascript
const pn = new PubNub({
  cryptoModule: PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubcipherkey', useRandomIVs: true});
)};
```

:::note Deprecated parameters
`cipherKey` and `useRandomIVs` are deprecated settings in the PubNub configuration object that utilized the legacy key. Future SDK versions may remove these settings.
:::

#### If cipherKey isn't present in PubNub config

Replace calls to the older PubNub `encrypt` and `decrypt` methods with the corresponding calls on the `CryptoModule` object.

```javascript
const cryptoModule = PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubcipherkey', useRandomIVs: true});
var encrypted_new = cryptoModule.encrypt(JSON.stringify('hello'))

var decrypted_new = cryptoModule.decrypt(encrypted_new)
```

Also replace the legacy `encryptFile` and `decryptFile` calls with their `CryptoModule` equivalents.

Adding `CryptoModule` is non‑breaking. A major‑version upgrade may include unrelated breaking changes.

### Activate 256-bit encryption

Once all user devices are updated with the new SDK, enable 256‑bit AES‑CBC.

:::warning Update first
Activate the 256‑bit AES‑CBC cipher only after all devices are updated, due to its incompatibility with older SDK versions.
:::

#### If cipherKey is present in PubNub config

To enable 256‑bit encryption, specify the updated `CryptoModule` when you configure PubNub:

```javascript
const pn = new PubNub({
  cryptoModule: PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubcipherkey'});
)};
```

#### If cipherKey isn't present in PubNub config

Update the `CryptoModule` from legacy to AES‑CBC:

```javascript
const cryptoModule = PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubcipherkey'}
```

Also update the `encryptFile` and `decryptFile` variants of these APIs.

“Legacy” refers to the cipher used before October 2023 (128‑bit encryption). While still considered secure, the updates further strengthen security.

### Client upgrades

Upgrade clients so they can decrypt messages encrypted with 256‑bit AES‑CBC. Staying current also helps security scanners verify that your SDKs support the 256‑bit algorithm.

## Terms in this document

* **PubNub** - PubNub is a real-time messaging platform that provides APIs and SDKs for building scalable applications. It handles the complex infrastructure of real-time communication, including: Message delivery and persistence, Presence detection, Access control, Push notifications, File sharing, Serverless processing with Functions and Events & Actions, Analytics and monitoring with BizOps Workspace, AI-powered insights with Illuminate.