Encrypted channels (BETA)

Encrypted channels provide the same subscription restrictions as private channels. In addition, the data field of events published to encrypted channels is encrypted using an implementation of the Secretbox encryption standard defined in NaCl before it leaves your server. Only authorized subscribers have access to the channel specific decryption key. This means that nobody except authorized subscribers can read the payload data, not even Pusher. Encrypted channels also provide end-to-end authenticity; that is your messages are protected from forgery, and that they are guaranteed to come from someone who holds the encryption master key.

Clients subscribing to encrypted channels must perform the same HTTP authentication step as private and presence channels.

Encrypted channels must be prefixed with private-encrypted-. See channel naming conventions.

After enabling this feature, you can verify that it is working by visiting the debug console for the app where you enabled the feature and seeing the ciphertext. You’ll know that it is working if the messages you send over the channel are unreadable in the debug console.

At the moment encrypted channels are in Beta. We really appreciate any feedback you might have so we can continue to make improvements. In particular, encrypted channels are currently supported in a limited number of client and server libraries – please let us know if you would like support added to an additional library. We can be contacted by email or through our support form.

Authenticate

Note on key rotation: Currently, if a client is unable to decrypt a message, it will make another request to your auth endpoint to obtain a new decryption key. If the client is still unable to decrypt the message with the new key, it will throw an error. We’re thinking about better solutions to this problem, so this may change in the future.

Encrypted channel subscriptions must be authenticated in the exact same way as private channels. See Authenticating Users.

For encryption and decryption to work the server library must be instantiated with a 32 byte encryption key.

client := pusher.Client{
  AppId:               appID,
  Key:                 key,
  Secret:              secret,
  Secure:              true,
  EncryptionMasterKey: "a-thirty-two-character-long-key!",
}
$pusher = new Pusher\Pusher(
  key,
  secret,
  app_id,
  array(
    'encrypted' => true,
    'encryption_master_key' => "a-thirty-two-character-long-key!",
  )
);

This encryption_master_key is never sent to pusher and should be something difficult to guess. We suggest using something like the openssl command below to generate a random key and keeping it somewhere secure.

openssl rand -base64 24

Subscribe

When a subscription takes place the user authentication process will be triggered. In addition to providing an auth token, the authentication process to an encrypted channel provides an encryption/decryption key which is used by the client to decrypt events. This happens automatically and if you are using a supported library you do not need to do anything.

var encryptedChannel = pusher.subscribe(encryptedChannelName);
  • encryptedChannelName (String)
    • The name of the channel to subscribe to. Since it is an encrypted channel the name must be prefixed with private-encrypted-
  • Returns
    • A Channel object which events can be bound to. See binding to events for more information on the Channel object.

Unsubscribe

See unsubscribing from channels.

Events

See binding to events for general information about how to bind to events on a channel object.

You can bind to the following pusher: events on an encrypted channel:

Limitations

This feature hides the sensitive data field of your messages. However, by design, there are many things which this feature does not do, and it is important that you are aware of these. They include:

  • It does not encrypt channel names. Pusher needs to inspect the message’s channel name to determine which clients to send it to.
  • It does not encrypt event names. Pusher needs to inspect the message’s event name to restrict namespaces (for example, only Pusher can publish events with the prefix pusher:).
  • It does not encrypt client events. Client events are disallowed on private-encrypted- channels. (We may lift this restriction in future.)
  • It does not encrypt messages published to channels without the private-encrypted- prefix, even if you have set a master encryption key.
  • It does not encrypt messages published by server libraries which do not have this feature implemented. Check that your library version is up-to-date.

The debug console in your dashboard may help demonstrate which things are encrypted, and which are not.

Library Support

At the moment encrypted channels are in Beta and library support is limited to those listed below. If you want to use encrypted channels and your library isn’t listed, please let us know!

Client events are not currently supported.

Technical Description

The authentication process for encrypted channels is very similar to that of private and presence channels. When clients are authenticated to access an encrypted channel, they receive a channel specific encryption/decryption key in addition to the authentication token.

Encrypted Channels

  1. When a new instance of the Pusher object is created a new WebSocket object is created.
  2. The WebSocket object connects to the Channels WebSocket endpoint.
  3. Once the connection has been established a universally unique socket_id is returned to the Channels JavaScript library.

  4. A subscription is made to a private-encrypted.
  5. The private-encrypted prefix identifies the channel as requiring authentication so a request is made to an authentication endpoint via AJAX.
  6. If successful your application returns an authentication string to the Channels JavaScript library signed with your Channels secret and a channel specific shared_secret used to encrypt/decrypt payload data. The shared_secret is stored by the Channels JavaScript library.
  7. The channel_name and authentication signature is sent to Channels over the WebSocket, which completes the authentication if the authentication string has been correctly signed.

  8. When events are triggered using the Channels Server Library, they’re decrypted using the channel specific encryption key.
  9. The encrypted events are sent to the Pusher API.
  10. The encrypted events are delivered to subscribers.
  11. The Channels JavaScript library decrypts the event payload with the shared_secret from step 6.
  12. The Channels JavaScript library emits decrypted events as normal

Have you tried using the search to find what you’re after? If you still have a question then get in touch with us and let us help you out.