Encryption API for JavaScript SDK

PubNub JavaScript SDK provides built-in message and file encryption to secure your real-time communications. This documentation covers crypto module configuration and utility methods for encrypting and decrypting messages and files using both legacy 128-bit and enhanced 256-bit AES-CBC encryption.

For general SDK configuration and initialization, refer to the Configuration page.

Configuration

cryptoModule configuration

To configure the cryptoModule to encrypt all messages/files, you can use the following methods in the Javascript SDK:

Your client can decrypt content encrypted using either of the modules. This way, you can interact with historical messages or messages sent from older clients while encoding new messages using the more secure 256-bit AES-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. Make sure to update your clients or encrypt data using the legacy algorithm.

SDK Initialization required

Before using encryption methods, ensure your PubNub client is properly configured with publish/subscribe keys and user ID. See the Configuration guide for setup instructions.

Encryption methods

Encrypt

This function allows to encrypt the data.

Deprecated parameter

The cipherKey parameter in this method is deprecated. We recommend that you configure a separate instance of the crypto module and use it for partial encryption.

If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Method(s)

To encrypt the data, you can use the following method(s) in 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 message

Returns

It returns the encrypted data as string.

Encrypt file

This function allow to encrypt the file content/data.

Deprecated

The key parameter in this method is deprecated. We recommend that you configure a separate instance of the crypto module and use it for partial encryption.

If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Method(s)

To encrypt the file, you can use the following method(s) in 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 of PubNubFile

Decryption methods

Decrypt

This function allows to decrypt the data.

Deprecated parameter

The cipherKey parameter in this method is deprecated. We recommend that you configure the crypto module on your PubNub instance instead.

If you pass cipherKey as an argument, it overrides the crypto module configuration and the legacy encryption with 128-bit cipher key entropy is used.

Method(s)

To decrypt the data, you can use the following method(s) in 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

It returns the decrypted data as an object.

Error Responses

If the decrypt() method fails, a verbose error with a reason for failure is thrown.

Decrypt file

This function allow to decrypt the file content/data.

Deprecated

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

Method(s)

To decrypt the file, you can use the following method(s) in 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 of PubNubFile.