Encryption API for Ruby SDK

PubNub Ruby SDK includes message and file encryption. This page shows how to set up the crypto module and perform manual 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_module encrypts and decrypts messages and files. From 5.2.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 random_iv 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 the 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_module configuration

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

# Encrypts using 256-bit AES-CBC cipher (recommended)
# Decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
pubnub = Pubnub.new(
    # ...
    crypto_module: Crypto::CryptoModule.new_aes_cbc("enigma", true)
)

# Encrypts with 128-bit cipher key entropy (legacy)
# Decrypts data encrypted with the legacy and the 256-bit AES-CBC ciphers
pubnub = Pubnub.new(
    # ...
    crypto_module: Crypto::CryptoModule.new_legacy("enigma", true)
)

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 5.2.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 = Crypto::CryptoModule.new_aes_cbc("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.

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)