For AI agents: this page in Markdown: https://www.pubnub.com/docs/security/encryption/overview.md. Documentation index: https://www.pubnub.com/llms-full.txt.

Data security and encryption

PubNub secures data at two levels: transport and content.

  • Transport security. TLS encrypts every connection between your clients and PubNub servers.
  • Content security. The CryptoModule encrypts message and file payloads so only clients holding the cipher key can read them.

Both layers are independent. You can use TLS alone (default), add content encryption on top, or implement a custom cryptor.

Transport security​

All connections to PubNub use TLS 1.2 by default. TLS is enabled in the SDK during initialization and applies to every API call. Some SDKs expose this setting as ssl, a legacy name for TLS.

TLS can be disabled during SDK initialization for debugging. This is not recommended for production. For code examples, see Disable TLS.

Custom domain

For a custom domain (origin) instead of the default PubNub endpoint ps.pndsn.com, see Request a custom domain. PubNub also provides TLS certificate hosting for custom domains.

Content encryption​

CryptoModule​

The CryptoModule is the recommended way to configure message and file encryption. It contains one or more cryptors, each implementing an encrypt/decrypt algorithm, and handles which cryptor to apply on a given payload.

Two algorithms are available:

  • AES-CBC 256-bit (recommended). Provides 256-bit AES encryption in CBC mode with a random initialization vector.
  • Legacy 128-bit. If SDK configuration sets a cipherKey without an explicit CryptoModule, the SDK defaults to legacy 128-bit encryption.

The two algorithms are backward-compatible in one direction:

  • A CryptoModule configured for AES-CBC 256-bit encryption can also decrypt content encrypted with the legacy 128-bit module. Switching to it does not break existing stored messages; they remain readable.
  • An SDK version that doesn't support AES-CBC 256-bit encryption can't decrypt content encrypted with it. Update clients before switching.
Switching algorithms

To upgrade to 256-bit AES-CBC encryption, you must explicitly set it in the SDK configuration. See Migrate to 256-bit AES-CBC encryption.

Cipher key​

All clients that send and receive encrypted content must configure the SDK with the same cipher key. PubNub servers handle only ciphertext and never store cipher keys. A client without the correct cipher key receives unreadable content.

Message encryption scope​

Two scopes are available:

  • All messages and files. Register the CryptoModule at SDK initialization. The SDK encrypts every message before publish and decrypts every received message. Data stored in Message Persistence remains encrypted.
  • Individual messages or files. Create a standalone CryptoModule instance and call encrypt() or decrypt() per item. Use this when you need to encrypt only part of a payload, for example sensitive fields in a Mobile Push Notification payload while leaving push keys in clear text.
File cipher key override

Passing a cipherKey directly to sendFile or downloadFile bypasses the CryptoModule and forces legacy 128-bit encryption. Configure encryption through the CryptoModule, not through per-call cipher keys.

File encryption​

When a CryptoModule is registered in SDK configuration, file encryption is automatic: the SDK encrypts file data before upload and decrypts on download. No extra parameters are required.

Custom encryption​

PubNub SDKs expose an interface to register custom cryptors. During decryption, the SDK inspects the payload header and selects the matching cryptor. This lets you use a proprietary algorithm alongside the built-in ones.

For implementation details, see Use custom encryption.

Was this page useful?

Last updated on