Encryption API for PHP SDK

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

Configuration

crypto module

crypto provides encrypt/decrypt functionality for messages. From the 8.0.2 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.

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.

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.

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 for setup instructions.

crypto configuration

Use these methods to configure crypto:

//  encrypts using 256-bit AES-CBC cipher (recommended)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
$pnConfiguration = new PNConfiguration();
...
// all necessary config options
$pnConfiguration->setCrypto(CryptoModule::aesCbcCryptor("enigma", true));

$pubnub = new PubNub($pnconf);

// encrypts with 128-bit cipher key entropy(legacy)
// decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
$pnConfiguration = new PNConfiguration();
...
// all necessary config options
$pnConfiguration->setCrypto(CryptoModule::legacyCryptor("enigma", true));

show all 17 lines

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.

Older SDK versions

Apps built using the SDK versions lower than 8.0.2 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.

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

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.

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

Encrypt the JSON string using the crypto_module instance.

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.

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:

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

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.

decrypted_string = crypto_module.decrypt(decoded_data)