256-bit AES-CBC Encryption Migration Guide
Upgrading to the recommended 256-bit AES-CBC encryption is a two-step process:
Upgrade to the latest SDK
Access to the 256-bit encryption algorithm is provided at the PubNub SDK level. That's why, it is necessary to upgrade to the latest version of your client SDK.
The minimum version of your SDK can be determined by searching through the changelog of your SDK for Add crypto module. We recommend using the latest version of the SDK where possible.
Older SDK versions
SDK versions released before the inclusion of the 256-bit AES-CBC cipher (introduced in October 2023) will not be able to decrypt data encrypted with the recommended 256-bit AES-CBC cipher. The CryptoModule configuration 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 is used to configure PubNub data encryption and decryption upon sending and receiving messages and files.
To allow all your clients to decrypt messages while the new SDK updates are being rolled out:
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 the CryptoModule to the SDKs was a non-breaking change, but upgrading from a previous major version number may result in other unrelated breaking changes.
Activate the New Encryption Algorithm
Once all user devices are updated with the new SDK, you can enable the 256-bit encryption.
Update first
Only activate the 256-bit AES-CBC cipher after all devices were updated, due to its incompatibility with older SDK versions.
If cipherKey is present in PubNub config
To enable the 256-bit encryption, specify the updated crypto module when you configure PubNub:
const pn = new PubNub({
cryptoModule: PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubcipherkey'});
)};
If cipherKey isn't present in PubNub config
Update the crypto module from legacy to AES-CBC:
const cryptoModule = PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubcipherkey'}
You should also update the encryptFile and decryptFile variants of these APIs.
Legacy refers to the cipher method used before October 2023, equivalent to 128-bit encryption. While still considered secure, the updates enhance this security.
Client Upgrades
Clients not upgraded to the new 256-bit encryption algorithm will be unable to decrypt any messages encrypted with the 256-bit cipher. Also, security scanning software may identify vulnerabilities in our SDKs not supporting the 256-bit encryption algorithm.