Encryption API for PHP SDK

PubNub PHP SDK provides built-in message encryption to secure your real-time communications. This documentation covers crypto module configuration and partial encryption methods using both legacy 128-bit and enhanced 256-bit AES-CBC encryption.

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 release on, you can configure how the actual encryption/decryption algorithms work.

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 using the 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 using encryption methods, ensure your PubNub client is properly configured with subscribe key and user ID. See the Configuration guide for setup instructions.

crypto configuration

To configure crypto, you can use the following methods in the PHP SDK:

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

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 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)