Encryption API for JavaScript SDK

PubNub JavaScript Software Development Kit (SDK) includes message and file encryption. This page explains how to configure the cryptoModule and how to encrypt and decrypt data. The SDK supports 128-bit Advanced Encryption Standard (AES) and 256-bit AES in Cipher Block Chaining (CBC) mode (AES-CBC).

For SDK configuration and initialization, see the Configuration page.

Configuration

cryptoModule configuration

Use these methods to configure the cryptoModule to encrypt all messages and files:

Your client can decrypt content produced by either cryptoModule or legacy cipherKey-based encryption. This allows the client to read historical messages and messages from older clients while you encrypt new messages with the stronger AES-256-CBC cipher.

Older SDK versions

Apps built using the SDK versions lower than 7.3.3 will not be able to decrypt data encrypted using the 256-bit AES-CBC cipher. Update your clients or encrypt data using the legacy algorithm.

SDK initialization required

Before you use encryption methods, ensure your PubNub client is configured with a publish key, a subscribe key, and a user ID. See the Configuration guide for setup instructions.

Relationship between cryptoModule and cipher keys

The cryptoModule supersedes cipher-key parameters. If you pass a customCipherKey (for encrypt/decrypt) or key (for encryptFile/decryptFile) to a method, that argument overrides the configured cryptoModule for that operation and uses legacy AES-128 encryption. For partial encryption, create a separate cryptoModule instance and use it only where needed.

Encryption methods

Encrypt

Use this function to encrypt data.

Deprecated parameter

The customCipherKey parameter is deprecated. Configure a separate instance of the cryptoModule and use it for partial encryption.

If you pass customCipherKey, it overrides the cryptoModule configuration and the legacy encryption with 128-bit cipher-key entropy is used.

Method(s)

Use the following method in the JavaScript SDK.

encrypt(
    data: string,
    customCipherKey?: string
)

* required

Parameter	Description
data * Type: string or bytes	The data to encrypt.
customCipherKey Type: string	If provided, the legacy encryption with 128-bit cipher-key entropy is used.

Sample code

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

Encrypt part of a message

Returns

Returns the encrypted data as a string.

Encrypt file

Use this function to encrypt file content.

Deprecated

The key parameter in this method is deprecated. Configure a separate instance of the cryptoModule and use it for partial encryption.

If you pass key, it overrides the cryptoModule configuration and the legacy encryption with 128-bit cipher-key entropy is used.

Method(s)

Use the following method in the JavaScript SDK.

pubnub.encryptFile(
    key: string,
    file: PubNubFile
): Promise<PubNubFile>;

* required

Parameter	Description
key Type: string	Cipher key used for encryption.
file * Type: PubNubFile	File to encrypt.

Sample code

Returns

Returns a promise that resolves to PubNubFile

Decryption methods

Decrypt

Use this function to decrypt data.

Deprecated parameter

The customCipherKey parameter is deprecated. Configure the cryptoModule on your PubNub instance instead.

If you pass customCipherKey, it overrides the cryptoModule configuration and the legacy encryption with 128-bit cipher-key entropy is used.

Method(s)

Use the following method in the JavaScript SDK.

decrypt(
    data: string,
    customCipherKey?: string

* required

Parameter	Description
data * Type: string	The data to decrypt.
customCipherKey Type: string	If provided, the legacy encryption with 128-bit cipher-key entropy is used. If not provided, the cryptoModule from PubNub config will be used. For more information, refer to Crypto module configuration.

Sample code

Returns

Returns the decrypted data as an object.

Error responses

If decrypt() fails, the method throws an error with a detailed reason.

Decrypt file

Use this function to decrypt file content.

Deprecated

This method uses the legacy encryption with 128-bit cipher-key entropy. For more information, refer to Crypto module configuration.

Method(s)

Use the following method in the JavaScript SDK.

pubnub.decryptFile(
    key: string,
    file: PubNubFile
): Promise<PubNubFile>;

* required

Parameter	Description
key * Type: String	Cipher key used for decryption.
file * Type: PubNubFile	File to decrypt.

Sample code

Returns

Returns a promise that resolves to PubNubFile.