Migrate to 256-bit AES-CBC encryption

Showing JavaScript examples.

If your PubNub integration encrypts messages or files with the legacy 128-bit cipher, or has no CryptoModule configured at all, migrate it to the recommended AES-CBC 256-bit CryptoModule. The migration has two steps: upgrade every client's SDK first, then activate the new cipher. Completing the steps in this order keeps every client able to decrypt messages throughout the rollout.

Before you start

Confirm you have:

• An existing cipher key. Reuse the same cipher key through both steps of this migration. Only the CryptoModule configuration changes.
• Deploy access to every client build that encrypts or decrypts PubNub messages and files with this cipher key: each mobile app release, web bundle, and backend service.
• Read Data security and encryption if you need the background on the CryptoModule and the two available algorithms.

Upgrade everyone before you activate AES-CBC

Complete step 1 on every client before you start step 2. A client that hasn't upgraded to a CryptoModule-capable SDK can't decrypt AES-CBC 256-bit content. Activating the new cipher before every client upgrades locks those clients out of messages and files encrypted after the switch.

Migrate with an AI coding assistant

If you use an AI coding assistant, paste this prompt into it to run the migration. The prompt makes the assistant read this guide, list the affected code before it changes anything, and stop before it turns on AES-CBC 256-bit for any client.

Migrate this codebase from the legacy PubNub cipher to 256-bit AES-CBC encryption.


1. Read the migration guide first:
   https://www.pubnub.com/docs/migration-guides/aes-cbc-encryption.md
   If the PubNub MCP server is connected, you can call get_general_migration_guide
   instead. Where the guide and your own knowledge of PubNub SDKs disagree,
   follow the guide and tell me.
2. Before you edit anything, list every place that sets a PubNub cipherKey or
   cryptoModule, and every call to encrypt, decrypt, encryptFile, or decryptFile.
   Include each client's PubNub SDK version. Tell me which clients that use this
   cipher key are not in this repository. Then show me a plan and wait for my
   approval.
3. Do step 1 of the guide only. Upgrade each SDK to a version that supports
   CryptoModule and configure the legacy CryptoModule with the existing cipher key.
   Where the code calls encrypt or decrypt directly, move those calls to a
   CryptoModule instance that still uses the legacy cipher.
4. Keep the same cipher key for the whole migration. Change only the CryptoModule
   configuration.
5. If an SDK upgrade crosses a major version, check that SDK's changelog for
   unrelated breaking changes and tell me what you find.
6. STOP after step 1. Don't switch any client to the AES-CBC 256-bit CryptoModule
   until I confirm that step 1 is deployed to every client that uses this cipher
   key, including clients outside this repository. A client without the upgrade
   can't decrypt AES-CBC content, so an early switch locks it out.
7. After I confirm, do step 2 of the guide with the same cipher key.
8. Make one small change at a time. After each change, run the build and tests
   and show me the output.
9. Never put the PubNub secret key in client code, and never commit keys or
   credentials.
10. When you finish, list every file you changed and the steps left for me.

show all 30 lines

Step 1: Upgrade every client to a CryptoModule-capable SDK

Update each platform's PubNub SDK to a version that supports CryptoModule. Check your SDK's changelog for the entry that adds crypto module support, and use that version or later.

Adding a CryptoModule is not a breaking change by itself. A major-version SDK upgrade you take at the same time might carry unrelated breaking changes, so check that SDK's own changelog too.

If your configuration sets a cipherKey

Explicitly configure the legacy CryptoModule with your existing cipher key:

1const pubnub = new PubNub({
2  // all necessary config options
3  cryptoModule: PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubenigma'})
4});

This keeps the encrypted output identical to what your current clients already produce, so any client you haven't upgraded yet keeps working. It also makes the upgraded client able to decrypt AES-CBC 256-bit content once you activate it in step 2. The parameter and method names vary by SDK. Check the Crypto module section of your SDK's configuration reference for the exact syntax.

If your configuration doesn't set a cipherKey

Replace calls to the older encrypt, decrypt, encryptFile, and decryptFile methods with the equivalent calls on a CryptoModule instance, still configured with the legacy cipher for now:

1const cryptoModule = PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubenigma'});
2

3const encrypted = cryptoModule.encrypt(JSON.stringify(message));
4const decrypted = cryptoModule.decrypt(encrypted);

Deploy this upgrade to every client that publishes or subscribes using this cipher key before you continue to step 2.

Step 2: Activate 256-bit AES-CBC encryption

Once every client has the upgraded SDK, switch the CryptoModule configuration from legacy to AES-CBC 256-bit, using the same cipher key.

• JavaScript
• Swift
• Objective-C
• Java
• Go
• Kotlin
• Rust
• Ruby
• Dart
• C#/Unity

1var pubnub = new PubNub({
2  subscribeKey: "mySubscribeKey",
3  publishKey: "myPublishKey",
4  userId: "myUniqueUserId",
5  cryptoModule: PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubenigma'})
6});

After you deploy this change to a client, that client encrypts new messages and files with AES-CBC 256-bit, and can still decrypt older content encrypted with the legacy cipher. For the full initialization pattern, including keyset configuration, see Encrypt and decrypt all messages and files.

Related tasks

• Encrypt and decrypt all messages and files. Configure the CryptoModule at initialization for a new integration.
• Data security and encryption. How TLS and the CryptoModule secure PubNub data.
• Use custom encryption. Register a custom cryptor instead of the built-in algorithms.
• Available migration guides. Every migration guide in the current documentation.