---
source_url: https://www.pubnub.com/docs/sdks/php/api-reference/encryption
title: Encryption API for PHP SDK
updated_at: 2026-06-29T11:49:23.898Z
sdk_name: PubNub PHP SDK
sdk_version: 9.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 PHP SDK

PubNub PHP SDK, use the latest version: 9.0.1

Install:

```bash
composer require pubnub/pubnub@9.0.1
```

PubNub PHP SDK includes message encryption. This page shows how to set up the crypto module and how to perform partial encryption. The SDK supports 128-bit Advanced Encryption Standard (AES) and 256-bit AES in Cipher Block Chaining (CBC) mode.

For general SDK configuration and initialization, refer to the [Configuration](https://www.pubnub.com/docs/sdks/php/api-reference/configuration) page.

## Configuration

### crypto module

`crypto` provides encrypt/decrypt functionality for messages. From the 9.0.1 onward, you can configure the algorithms it uses.

Each PubNub SDK is bundled with two ways of encryption: the legacy encryption with 128-bit cipher key entropy and the recommended 256-bit AES-CBC encryption. For more general information on how encryption works, refer to [Message Encryption](https://www.pubnub.com/docs/general/setup/data-security#message-encryption).

If you do not explicitly set the `crypto_module` in your app and have the `cipher_key` and `use_random_initialization_vector` params set in PubNub config, the client defaults to legacy encryption.

:::note Legacy encryption with 128-bit cipher key entropy
You don't have to change your encryption configuration if you want to keep using the legacy encryption. If you want to use the recommended 256-bit AES-CBC encryption, you must explicitly set that in PubNub config.
:::

:::note SDK initialization required
Before you use encryption methods, ensure your PubNub client is configured with a subscribe key and a user ID. See the [Configuration guide](https://www.pubnub.com/docs/sdks/php/api-reference/configuration#initialization) for setup instructions.
:::

#### crypto configuration

Use these methods to configure `crypto`:

```php
//  encrypts using 256-bit AES-CBC cipher (recommended)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
$pnConfiguration = new PNConfiguration();
$pnConfiguration->setSubscribeKey('demo');
$pnConfiguration->setPublishKey('demo');
$pnConfiguration->setUserId('crypto-demo');
$cryptoModule = CryptoModule::aesCbcCryptor("enigma", true);
$pnConfiguration->setCryptoModule($cryptoModule);

$pubnub = new PubNub($pnConfiguration);

// encrypts with 128-bit cipher key entropy(legacy)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
$pnConfiguration2 = new PNConfiguration();
$pnConfiguration2->setSubscribeKey('demo');
$pnConfiguration2->setPublishKey('demo');
$pnConfiguration2->setUserId('crypto-demo-legacy');
$legacyCryptoModule = CryptoModule::legacyCryptor("enigma", true);
$pnConfiguration2->setCryptoModule($legacyCryptoModule);

$pubnub2 = new PubNub($pnConfiguration2);
```

The client can decrypt content from either module. You can read historical messages and messages from older clients, and you can encrypt new messages with 256-bit AES-CBC.

:::warning Older SDK versions
Apps built using the SDK versions lower than 9.0.1 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.
:::

## Manual encryption

### Partial encryption

Manual encryption allows users to decide what and when to encrypt.

:::note Configuration settings
Do not configure crypto during PubNub client creation to use manual encryption.
:::

For partial encryption, serialize complex objects (e.g., dictionaries) to JSON strings.

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

```php
data_to_encrypt = { key: "value to encrypt" }
json_string = data_to_encrypt.to_json
```

Encrypt the JSON string using the `crypto_module` instance.

```php
crypto_module = CryptoModule::new_aes_cbc_cryptor("enigma", true)
encrypted_data = crypto_module.encrypt(json_string)
```

To make encrypted data "transportable", encode it as a Base64 string.

```php
base64_encrypted_string = Base64.strict_encode64(encrypted_data)
```

Use the Base64 string as an argument in the `publish()` function or as a value in a dictionary for partial encryption.

#### For partial encryption of individual strings

You can configure a separate crypto module instance and use it directly:

```php
// partial encryption
$pubnub->setCrypto(
    CryptoModule::aesCbcCryptor('myDifferentCipherKey', true)
);

// encrypts a string
$pubnub->getCrypto()->encrypt('string to encrypt');

// decrypts a string
$pubnub->getCrypto()->decrypt('string to decrypt');
```

### Decryption considerations

If the encrypted data is obtained as a Base64 encoded string (e.g., from subscribe response or history), decode it first.

```php
base64_encoded_data = "CxQ0dxjBqIHdfuvtTcKeaLlyeRY7ZuaKy27wwwWo1EE="
decoded_data = Base64.decode64(base64_encoded_data)
```

If dealing with a binary string output directly from `crypto_module.encrypt(data.to_json)`, you can use it directly for decryption.

```php
decrypted_string = crypto_module.decrypt(decoded_data)
```

## Terms in this document

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