--- source_url: https://www.pubnub.com/docs/migration-guides/aes-cbc-encryption title: Migrate to 256-bit AES-CBC encryption updated_at: 2026-09-30T07:20:08.000Z --- # Migrate to 256-bit AES-CBC encryption ## Documentation index To discover more PubNub resources: 1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format. 2. Identify relevant URLs from that index. 3. Fetch the target pages. Do not assume a path exists, always check the index first. 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](https://www.pubnub.com/docs/security/encryption/overview.md) if you need the background on the CryptoModule and the two available algorithms. :::warning 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. ```text 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. ``` ## 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: ```javascript const pubnub = new PubNub({ // all necessary config options cryptoModule: PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubenigma'}) }); ``` 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](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration.md#cryptomodule) 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: ```javascript const cryptoModule = PubNub.CryptoModule.legacyCryptoModule({cipherKey: 'pubnubenigma'}); const encrypted = cryptoModule.encrypt(JSON.stringify(message)); const 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 ```javascript var pubnub = new PubNub({ subscribeKey: "mySubscribeKey", publishKey: "myPublishKey", userId: "myUniqueUserId", cryptoModule: PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubenigma'}) }); ``` ### Swift ```swift let pubnub = PubNub( configuration: PubNubConfiguration( publishKey: "demo", subscribeKey: "demo", userId: "myUniqueUserId", cryptorModule: CryptorModule.aesCbcCryptoModule(with: "pubnubenigma") ) ) ``` ### Objective-C ```objectivec // all necessary config options config.cryptoModule = [PNCryptoModule AESCBCCryptoModuleWithCipherKey:@"enigma" randomInitializationVector:YES]; ``` ### Java ```java PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey"); // publishKey from Admin Portal (only required if publishing) configBuilder.publishKey("PublishKey"); configBuilder.cryptoModule(CryptoModule.createAesCbcCryptoModule("pn-9F3kQ7zR2xV8mB1tD6wL4yH0sN5cJ", true)); // all necessary config options PubNub pubNub = PubNub.create(configBuilder.build()); ``` ### Go ```go config := pubnub.NewConfigWithUserId(UserId("myUniqueUserId")) // all necessary config options config.CryptoModule = crypto.NewAesCbcCryptoModule("cipherKey", true) pn := pubnub.NewPubNub(config) ``` ### Kotlin ```kotlin val config = com.pubnub.api.v2.PNConfiguration.builder(UserId("myUserId"), "demo").apply { publishKey = "demo" cryptoModule = CryptoModule.createAesCbcCryptoModule("pn-9F3kQ7zR2xV8mB1tD6wL4yH0sN5cJ") }.build() val pubnub = PubNub.create(config) ``` ### Rust ```rust let client = PubNubClientBuilder::with_transport(Transport) // all necessary config options .with_cryptor(CryptoModule::new_aes_cbc_module("enigma", true)?) .build()?; ``` ### Ruby ```ruby pubnub = Pubnub.new( # all necessary config options crypto_module: Crypto::CryptoModule.new_aes_cbc("enigma", true) ) ``` ### Dart ```dart final pubnub = PubNub( // all necessary config options crypto: CryptoModule.aescbcCryptoModule(CipherKey.fromUtf8('enigma')); ); ``` ### C#/Unity ```csharp PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId")); // all necessary config options pnConfiguration.CryptoModule = new CryptoModule(new AesCbcCryptor("enigma"), new List { new LegacyCryptor("enigma") }) new PubNub(pnConfiguration); ``` 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](https://www.pubnub.com/docs/security/encryption/encrypt-all-messages-and-files.md). ## Related tasks * [Encrypt and decrypt all messages and files](https://www.pubnub.com/docs/security/encryption/encrypt-all-messages-and-files.md). Configure the CryptoModule at initialization for a new integration. * [Data security and encryption](https://www.pubnub.com/docs/security/encryption/overview.md). How TLS and the CryptoModule secure PubNub data. * [Use custom encryption](https://www.pubnub.com/docs/security/encryption/use-custom-encryption.md). Register a custom cryptor instead of the built-in algorithms. * [Available migration guides](https://www.pubnub.com/docs/migration-guides/overview.md). Every migration guide in the current documentation. Last updated at: 2026-09-30T07:20:08.000Z