---
source_url: https://www.pubnub.com/docs/sdks/ruby/api-reference/encryption
title: Encryption API for Ruby SDK
updated_at: 2026-06-25T11:28:40.351Z
sdk_name: PubNub Ruby SDK
sdk_version: 6.1.0
---

> 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 Ruby SDK

PubNub Ruby SDK, use the latest version: 6.1.0

Install:

```bash
gem install pubnub@6.1.0
```

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](https://www.pubnub.com/docs/sdks/ruby/api-reference/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](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 `random_iv` params set in PubNub config, the client defaults to using the 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 the 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/ruby/api-reference/configuration#initialization) 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:

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

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

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

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

Encrypt the JSON string using the `crypto_module` instance.

```ruby
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.

```ruby
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.

```ruby
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.

```ruby
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.