Data Security

PubNub is serious about the security of your data. Using TLS and AES256 encryption algorithms, and with HIPAA, GDPR, SOC2 type 2, and CCPA compliance, you can be sure your data is safeguarded.

Compliance reports

If you are a Pro customer, you can access the most recent versions of the SOC2 type 2 and other compliance reports directly from the Admin Portal. If you’re not a Pro customer, contact PubNub Compliance.

Compliance reports

There are several ways in which PubNub helps to secure your app:

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

Connection security​

PubNub offers connection level security through TLS Encryption (Transport Layer Security). It's enabled by default and generally there is no reason to disable it for any production application.

TLS version

Connections to PubNub APIs are encrypted using TLS 1.2, which provides secure communication over HTTPS between clients and PubNub servers.

Configuring TLS​

TLS is enabled by default. If you need to disable it for any reason, it can be done during the PubNub object initialization.

SSL

Some PubNub SDKs, the parameter name is ssl (a legacy name for TLS) but it represents the latest connection encryption technology available. SSL v3 was deprecated due to a security exploit that was discovered and TLS was developed to replace it as the industry standard. Many will refer to TLS as SSL out of habit.

var pubnub = new PubNub({
    subscribeKey: "mySubscribeKey",
    publishKey: "myPublishKey",
    userId: "myUniqueUserId",
    ssl: false // default 'true'
});

TCP connection troubleshooting​

If you need to capture the TCP traffic (a tcpdump to a .pcap file) to analyze and debug the network traffic, you may need to disable TLS in your development environment. This level of analysis is only necessary to troubleshoot the most difficult network connection and communication issues that are typically outside of the PubNub domain.

Custom domain​

You might want to use your own domain name for client applications to access PubNub’s real-time messaging infrastructure instead of the default PubNub endpoint ps.pndsn.com.

The reasons can include:

  • Branding – a custom domain helps maintain a consistent and professional brand image across all your services and interactions by making your application's traffic appear under your own domain
  • Compliance and control – you may have legal or regulatory requirements to use custom domains for data management, offering more control over how data is accessed and tracked.
  • Infrastructure integration – for better integration with the existing security, CDN, or networking infrastructure, optimizing your overall system configuration.
  • Traffic management – a custom domain allows PubNub to route traffic per customer efficiently, mainly when a point of presence (PoP) is underperforming or unavailable, improving performance and reliability.
Secure connections

Ensure connections are made over HTTPS instead of HTTP. HTTPS ensures a secure network by encrypting data and protecting your client data by preventing man-in-the-middle attacks.

If you are a paid customer, you can submit a request to PubNub support and have the custom domain (a.k.a. origin) configured for you.

PubNub also provides TLS certificate hosting if required. When TLS is used, you must supply us with your own certificate. This service comes with an additional monthly fee.

Request process​

To request a custom domain, contact PubNub support by raising a support ticket entitled "Request Custom Origin" and providing the following details in the request:

  • The PubNub account email that has or will have the paid production keyset(s).
  • Three choices for your subdomain in order of preference (12 characters or less, like abc.pubnubapi.com).
  • PubNub SDKs you currently use in your applications: SDK language/name and version.
  • If you have customers or devices in China, mention it in the request.

PubNub support will confirm your custom origin name and SDK initialization code for the SDK/version you use.

Once you have it, you can start using it by changing the way you initialize a PubNub instance in your SDK (with the origin parameter).

Connection limits​

To improve response times and avoid congestion, browsers have their own limitations to concurrent connections:

BrowserConnections per host nameMax connections
Chrome
6
10
Chrome mobile
6
16
Internet Explorer 9
6
35
Internet Explorer Mobile 9
6
60
Internet Explorer 10
8
17
Internet Explorer 11
13
17
Firefox
6
17
Safari
6
17
Android
6
17

Message encryption​

PubNub SDKs allow you to configure the encryption/decryption algorithms using pre-bundled packages for encrypting/decrypting data (cryptors) in your apps through crypto modules.

icon

Why encrypt messages?

Crypto module​

A crypto module contains cryptors that encrypt and decrypt data in your app. You can choose the algorithm:

  • Legacy 128‑bit (legacy module)
  • Recommended AES‑CBC 256‑bit (CBC mode)

Compatibility:

  • Current SDKs can decrypt content from either module.
  • Legacy 128‑bit and AES‑CBC 256‑bit can read each other’s content.
  • You can switch to AES‑CBC 256‑bit and still read historical and older‑client messages.
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.

If you do not explicitly select either module in your app and have cipherKey and, optionally, useRandomInitializationVector set in PubNub configuration, the client defaults to using the legacy encryption.

For information on how to configure modules, refer to the Configuration documentation of each SDK.

Keep your clients up to date

Apps not using the latest SDK version 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 module.

Upgrade to 256-bit encryption​

For information on how to migrate to the recommended encryption algorithm, refer to 256-bit AES-CBC Encryption.

Encryption scope​

Depending on whether you want to encrypt all messages and files or just some of them, create and register a crypto module differently.

  • To fully encrypt every message and file in all channels for a given API key, specify and register the crypto module as part of the PubNub configuration when you create the object.

  • To only encrypt some or partially encrypt messages, do not specify the crypto module as part of the PubNub configuration. Instead, create a standalone instance of a crypto module and call one of the available encrypt() or decrypt() methods.

Encrypting messages​

To configure encryption for all messages and files in all channels for a given API key, you need to register a module, provide a cipherKey, and, optionally, decide whether to use a random initialization vector to encrypt (and decrypt) data.

For information on partial encryption, refer to the Partial Message Encryption section.

var pubnub = new PubNub({
  ...
  // all necessary config options
  cryptoModule: PubNub.CryptoModule.aesCbcCryptoModule({cipherKey: 'pubnubenigma'})
});

The SDK encrypts each message before publish. The network routes only encrypted data. The message stays encrypted until it reaches the subscribing client.

The subscriber decrypts it with the same cipher key. Data stored in Message Persistence (and logging systems) remains encrypted. Only clients with the cipher key can decrypt it.

Protect your cipher key

You shouldn't share the cipher key outside of the PubNub network.

Partial message encryption​

Sometimes encrypting only part of the payload makes sense. With Mobile Push Notifications, push services must read specific keys and values. Encrypt only sensitive fields and leave push-related fields as clear text.

Create a separate crypto module instance and call encrypt() or decrypt() on that instance.

APNs example​

This example shows how to encrypt only the results object in an APNs payload.

Before encryption:

{
  "pn_apns": {
    "aps": {
      "alert": "Your test results are available.",
      "sound" : "bingbong.aiff"
    }
  },
  "results": {
    "test_name": "pregnancy",
    "results": "positive",
    "notes": "You are having twins!"
  }
}

Encrypt it:

Only the results object must be encrypted. Other fields can remain plain text.

const clearText = JSON.stringify(
  {"test_name":"pregnancy","results":"positive","notes":"You are having twins!"});

// create a crypto module instance
const cryptoModule = PubNub.CryptoModule.aesCbcCryptoModule({
  cipherKey: "pubnubenigma"
});

const secureText = cryptoModule.encrypt(clearText);

You can now add the secureData variable to the payload so that PubNub and third party mobile push vendors can process the Push payload correctly.

Using a 32‑character cipher key for AES‑256, the resulting message payload is as follows.

After encryption:

{
  "pn_apns": {
    "aps": {
      "alert": "Your test results are available.",
      "sound" : "bingbong.aiff"
    }
  },
  "results": "Nio2At2uvQzteLoSqznLkZQ3dlFlMzLGlUwbsMndZ7/7tllq2joJw6WcUv3XpMdEugYRnoEvsrlhEVkSnBibxaxDDWMFEDvKS+VLlA8mfmg="
}
Partial Message Encryption

You may need to encrypt certain data values within the APNs/FCM payload, but be sure not to encrypt any APNs/FCM keys, or any values that need to be parsed as unencrypted text by those mobile push services.

Decrypting messages​

On the receiver, use the same crypto module and cipher key to decrypt the encrypted parts of the payload.

// parse the received message and pass the encrypted parts to decrypt API.
const secureText =
  "Nio2At2uvQzteLoSqznLkZQ3dlFlMzLGlUwbsMndZ7/7tllq2joJw6WcUv3XpMdEugYRnoEvsrlhEVkSnBibxaxDDWMFEDvKS+VLlA8mfmg="

const clearData = pubnub.decrypt(secureText);

For more examples of decrypting messages in other languages, refer to the Configuration and/or Miscellaneous documentation of each SDK.

File encryption​

You can also encrypt files with a crypto module.

If you registered a crypto module in configuration, you don't need to pass it when encrypting or decrypting uploaded files.

Do not pass cipher key

Passing a cipher key in sendFile or downloadFile overrides the crypto module configuration and uses legacy 128‑bit encryption.

Refer to Encrypting Messages for information on how to configure the crypto module.

With client‑side encryption, the SDK encrypts file data before upload. The receiving client decrypts the data on download using the same key before it is displayed in the end‑user application.

Encrypting files​

The following shows how to encrypt a file using the crypto module registered in PubNub config.

 import fs from 'fs';

 const myFile = fs.readFileSync('./cat_picture.jpg');

 const result = await pubnub.sendFile({
   channel: 'my_channel',
   message: 'Look at this photo!',
   file: { data: myFile, name: 'cat_picture.jpg', mimeType: 'application/json' }
 });

Decrypting files​

The following shows how to decrypt a file using the crypto module registered in PubNub config.

const file = await pubnub.downloadFile({
   channel: 'my_channel',
   id: 'd9515cb7-48a7-41a4-9284-f4bf331bc770',
   name: 'cat_picture.jpg'
 });

For more examples of encrypting/decrypting files in other languages, refer to the Configuration and/or Files documentation of each SDK.

Custom encryption​

Encryption and decryption are decoupled from the SDKs. You can implement your own methods.

Each SDK exposes an interface to register cryptors.

During decryption, the SDK inspects the payload and chooses the matching cryptor.

Implementation guidelines​

Usage differs by SDK, but the flow is similar:

  1. Implement the required interfaces (names vary). See the Crypto interfaces.

  2. Create a Crypto module with your cryptor and pass it to PubNub configuration, or use it standalone for partial encryption. Refer to each SDK's Crypto module documentation.

Example custom cryptor implementation​

This example uses Kotlin, but the idea is the same across SDKs.

  1. Implement the Cryptor interface. Note that the id() method should return a ByteArray of exactly 4 bytes.


  2. Use your newly created myCustomCryptor that implements the Cryptor interface to instantiate a CryptoModule:

val customCryptor = myCustomCryptor()
val cryptoModule = CryptoModule.createNewCryptoModule(defaultCryptor = customCryptor)

Interfaces to implement​

Last updated on
Related Resources
On this page