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:
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.
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:
const pn = new PubNub({
cryptoModule: PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubcipherkey', useRandomIVs: true});
)};
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.
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.
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:
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:
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.