---
source_url: https://www.pubnub.com/docs/sdks/javascript/api-reference/encryption
title: Encryption API for JavaScript SDK
updated_at: 2026-06-04T11:11:55.054Z
sdk_name: PubNub JavaScript SDK
sdk_version: 11.0.1
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Encryption API for JavaScript SDK

PubNub JavaScript SDK, use the latest version: 11.0.1

Install:

```bash
npm install pubnub@11.0.1
```

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](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration) page.

## Configuration

### cryptoModule configuration

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

```javascript
// encrypts using 256-bit AES-CBC cipher (recommended)
// decrypts data encrypted with the legacy and the 256 bit AES-CBC ciphers
const pubnub = new PubNub({
  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
  userId: 'YOUR_USER_ID',
  cryptoModule: PubNub.CryptoModule.aesCbcCryptoModule({ cipherKey: 'pubnubenigma' }),
});

// encrypts with 128-bit cipher key entropy (legacy)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
const pubnubLegacy = new PubNub({
  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
  userId: 'YOUR_USER_ID',
  cryptoModule: PubNub.CryptoModule.legacyCryptoModule({ cipherKey: 'pubnubenigma' }),
});
```

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.

:::warning 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.
:::

:::note 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](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration#initialization) 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.

:::warning Deprecated parameter
The `customCipherKey` parameter is deprecated. Configure a separate instance of the [cryptoModule](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration#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.

```javascript
encrypt(
    data: string,
    customCipherKey?: string
)
```

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| data | string | Yes |  | The `data` to `encrypt`. |
| customCipherKey | string | Optional |  | If provided, the legacy encryption with 128-bit cipher-key entropy is used. |

#### Sample code

:::tip 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

```javascript
import PubNub from 'pubnub';
// Initialize PubNub with your keys
const pubnub = new PubNub({
  publishKey: 'YOUR_PUBLISH_KEY',
  subscribeKey: 'YOUR_SUBSCRIBE_KEY',
  userId: 'YOUR_USER_ID',
});
```

```javascript
// Create a crypto module instance with AES-CBC encryption
const cryptoModule = PubNub.CryptoModule.aesCbcCryptoModule({
  cipherKey: 'pubnubenigma',
});

const msgContent = 'This is the data I wish to encrypt.';
console.log(`Original Message: ${msgContent}`);

// Encrypt the message
const encryptedMessage = cryptoModule.encrypt(JSON.stringify(msgContent));
console.log('message encrypted successfully');
```

#### Returns

Returns the encrypted data as a string.

### Encrypt file

Use this function to encrypt file content.

:::warning Deprecated
The `key` parameter in this method is deprecated. Configure a separate instance of the [cryptoModule](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration#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.

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

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

#### Sample code

```javascript
// Node.js example
// import fs from 'fs';

const fileBuffer = fs.readFileSync('./cat_picture.jpg');

const file = pubnub.File.create({ data: fileBuffer, name: 'cat_picture.jpg', mimeType: 'image/jpeg' });

const encryptedFile = await pubnub.encryptFile(file);
```

#### Returns

Returns a promise that resolves to [PubNubFile](https://www.pubnub.com/docs/sdks/javascript/api-reference/misc#pubnubfile)

## Decryption methods

### Decrypt

Use this function to decrypt data.

:::warning Deprecated parameter
The `customCipherKey` parameter is deprecated. Configure the [cryptoModule](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration#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.

```javascript
decrypt(
    data: string,
    customCipherKey?: string
```

| 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](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration#cryptomodule). |

#### Sample code

```javascript
const decrypted = pubnub.decrypt(encrypted); // Pass the encrypted data as the first parameter in decrypt Method
```

#### 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.

:::warning Deprecated
This method uses the legacy encryption with 128-bit cipher-key entropy. For more information, refer to [Crypto module configuration](https://www.pubnub.com/docs/sdks/javascript/api-reference/configuration#cryptomodule).
:::

#### Method(s)

Use the following method in the JavaScript SDK.

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

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

#### Sample code

```javascript
// Node.js example.
// import fs from 'fs';
const fileBufferData = fs.readFileSync('./cat_picture_encrypted.jpg');

const fileData = pubnub.File.create({ data: fileBuffer, name: 'cat_picture.jpg', mimeType: 'image/jpeg' });

const decryptedFile = await pubnub.decryptFile(fileData);
```

#### Returns

Returns a promise that resolves to [PubNubFile](https://www.pubnub.com/docs/sdks/javascript/api-reference/misc#pubnubfile).

## Terms in this document

* **Publish Key** - A unique identifier that allows your application to send messages to PubNub channels. It's part of your app's credentials and should be kept secure.
* **Subscribe Key** - A unique identifier that allows your application to receive messages from PubNub channels. It's part of your app's credentials and should be kept secure.
* **User** - An individual or entity that interacts with a system, application, or service. In PubNub, a user typically refers to someone who sends or receives messages through the platform, identified by a unique user ID or username.
* **User ID** - UTF-8 encoded, unique string of up to 92 characters used to identify a single client (end user, device, or server) that connects to PubNub.