Encrypted channels (BETA)

Encrypted channels provide the same subscription restrictions as private channels. In addition, the payload data of events published to encrypted channels is encrypted using strong encryption. Only authenticated subscribers have access to the channel specific decryption key. This means that nobody except authenticated subscribers can read the payload data, not even Pusher.

Client events are also supported. Client events sent to encrypted channels are encrypted by the client library. The corresponding webhooks will be encrypted too, and they can be validated and decrypted by one of the supported server libraries.

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

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

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:

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!

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.