How To: Upgrade your Message-Level Encryption to 256-bit Key Strength

At PubNub, we are committed to providing customers with the highest level of security for their data.

Our data security overview details how PubNub helps secure your application:

Connection security: Securing the traffic between your client and PubNub using TLS.
Message encryption: Encrypting the message payload in transit and at rest.
Access management: Only allowing users with the correct permissions to access your data.

This document concerns the second of these techniques, message encryption, specifically how to upgrade to the new 256-bit encryption method introduced to our SDKs starting in October 2023.

Message Encryption: A General Description

PubNub SDKs provide helper functions to encrypt and decrypt your message payload using a pre-bundled encryption package that provides symmetric encryption. This allows you to easily implement end-to-end encryption of your message data in transit and at rest.

Configuring message security is a two-step process within the SDK:

Select an alphanumeric cipher key. It is from this cipher key that the data encryption key is derived, so it should not be shared outside of the PubNub network.
Encrypt the messages; this can be done in one of two ways:

Specify the cipher key as part of the initial configuration of the PubNub object. This will encrypt all messages sent and received.
Do not specify the cipher key as part of the configuration, but instead, use the CryptoModule class exposed by the SDK to encrypt/decrypt specific message data as needed. There are situations where you would not want to encrypt the entire message, for example, when sending mobile push messages. This is referred to as partial message encryption.
- The SDKs also expose separate methods for encrypt and decrypt, but these only refer to the legacy encryption algorithm, as explained in the next paragraph.

The links provided above point to the JavaScript SDK-specific methods, but equivalent methods also exist for all of our other supported SDKs.

128-bit encryption vs. 256-bit encryption

Before October 2023, PubNub’s 256-bit message-level encryption had an implementation issue, resulting in the actual encryption strength being effectively equivalent to 128-bit. Full details of this issue are described in CVE-2023-26154; however, it is important to understand that 128-bit is still considered highly secure.

Developers now have two choices: retain your existing message-level encryption implementation, which has the equivalent of 128-bit encryption, or upgrade to 256-bit encryption. This document describes the process to upgrade to 256-bit encryption.

Why upgrade to 256-bit message-level encryption?

128-bit encryption provides a high level of security for sensitive data and is very difficult to crack, even using powerful computers and sophisticated software (a brute-force approach will take over a billion years to crack a 128-bit encrypted message). 256-bit encryption uses an encryption key that is twice as long, requiring 2^256 possible combinations to check by brute force. Though this is even more difficult to crack, it also requires additional processing power, which, in theory, will decrease your encryption/decryption performance, though any practical effects will not be noticeable.

Upgrading your client to 256-bit message-level encryption

PubNub has taken deliberate steps to make the transition to the new 256-bit encryption algorithms as seamless as possible, especially where some clients will retain the old algorithms until they are upgraded.

The upgrade process requires two stages:

Step 1: Upgrade to the latest PubNub SDK

Encryption is provided at the SDK level, so upgrading to the latest client SDK is necessary to gain access to the 256-bit encryption algorithm.

Please refer to the change log for your client SDK and look for ‘add crypto module’ to determine which is the minimum version of the SDK you need to upgrade to; for example, JavaScript was version 7.4, Kotlin was version 7.7, Swift was version 6., etc. It is always recommended to use the latest version of the SDK where possible.

Important to note:

‘Older’ versions of the SDK will not be able to decrypt data encrypted with the 256-bit AES-CBC cipher (i.e., the cipher introduced in October 2023)
The CryptoModule configuration will always be able to decrypt data encrypted with either the legacy (i.e., the cipher method used prior to October 2023) or the 256-bit AES-CPC ciphers.

If you are specifying the cipher key as part of your PubNub configuration (to affect all messages):

The PubNub configuration will now accept a CryptoModule, which is used to configure how PubNub encrypts/decrypts data when you send/receive messages. The CryptoModule config parameter replaces the existing configuration parameters ‘cipherKey’ and ‘useRandomIVs.’

To allow all your clients to be able to decrypt messages whilst you roll out the new SDK updates to everyone, configure the crytoModule call as follows:

Note: At the time of writing, ‘cipherKey’ and ‘useRandomIVs’ are deprecated parameters of the PubNub configuration object that used the ‘legacy’ key. These may be removed in a future version of the SDK, so they are not given here as an example.

If you are not specifying the cipher key as part of your PubNub configuration but encrypting messages as needed:

The CryptoModule can be used independently to encrypt or decrypt data. You will need to replace calls to the older PubNub methods encrypt and decrypt with the corresponding calls on the CryptoModule object.

Again, although the example provided uses the JavaScript SDK, equivalent methods also exist for all of our other supported SDKs.

Calls to the legacy encryptFile and decryptFile should also be replaced with their CryptoModule equivalents, taking care to use the legacyCryptoModule at this stage.

Bear in mind that while adding the CryptoModule to the SDKs was a non-breaking change, if you upgrade from a previous major version number, the upgrade step may involve other unrelated breaking changes. Please refer to your SDK’s changelog for further information.

Step 2: Activate the new encryption algorithm

Once all user devices are updated to the new SDK, you can enable 256-bit encryption. Note that ‘older’ versions of the SDK will not be able to decrypt data encrypted with the 256-bit AES-CBC cipher, so it is important only to do this step after all devices have been updated.

If you are specifying the cipher key as part of your PubNub configuration (to affect all messages):

Enable 256-bit encryption by specifying the updated crypto module when you configure PubNub:

If you are not specifying the cipher key as part of your PubNub configuration but encrypting messages as needed:

Wherever you replaced the legacy encrypt and decrypt methods with their CryptoModule equivalents, update the crypto module from legacy to AES CBC, as follows:

Ensure you also make the equivalent updates for the File variants of these APIs, encryptFile and decryptFile.

Again, for clarity, ‘legacy’ refers to the cipher method used prior to October 2023, which provided the equivalent of 128-bit encryption and is still considered very secure by the industry; these updates simply improve upon this security.

What if some of my clients do not upgrade?

If you activate the new 256-bit encryption algorithm (step 2) before clients have upgraded, they will be unable to decrypt any messages.

Also, note that security scanning software may identify our SDKs as having a vulnerability with older versions that do not support the new 256-bit encryption algorithm.

Client-side encryption conclusion

If you are only concerned with encrypting messages between PubNub clients, your upgrade to 256-bit encryption is now complete.

If you need additional help, please contact PubNub support, who will be able to assist you.

Upgrading your PubNub Function to 256-bit message-level encryption

Consider the case where you have upgraded the clientside SDK to send messages with 256-bit encryption, but you need to decrypt those messages within a PubNub function. This section will walk you through setting up a PubNub function capable of decrypting 256-bit encrypted messages.

Assuming you have a client configured to send messages with 256-bit message-level encryption enabled, as described previously, the message can then be decrypted within a PubNub function as follows:

Development interface with code editor and console output displaying encryption and debugging information.

Conclusion

It is recommended that all developers upgrade to the latest client SDKs, and if you are using message-level encryption, it is also recommended that you upgrade to the new 256-bit encryption algorithm by following the steps outlined in this document.

If you choose to, developers are free to remain with the ‘legacy’ encryption algorithm that provides the equivalent of 128-bit encryption and is still considered a highly secure encryption standard.