Encryption
The Ably.Rest.Crypto object exposes the following public methods:
Methods
getDefaultParams
Crypto.getDefaultParams(Object params): CipherParams
CipherParams object using the values passed in (which must be a subset of CipherParams fields that at a minimum includes a key), filling in any unspecified fields with default values, and checks that the result is a valid and self-consistent.
You will rarely need to call this yourself, since the client library will handle it for you if you specify cipher params when initializing a channel (as in the example at the top) or when setting channel options with channel#setOptions.
Parameters
| Parameter | Description | Type |
|---|---|---|
| params | The cipher params that you want to specify. It must at a minimum include a key, which should be either a binary (ArrayBuffer or Uint8Array) or a base64-encoded String. | Object |
Returns
On success, the method returns a complete CipherParams object. Failure will raise an exception.
Example
1
2
3
const cipherParams = Ably.Rest.Crypto.getDefaultParams({ key: <key> });
const channelOpts = { cipher: cipherParams };
const channel = rest.channels.get('aft-far-spy', channelOpts);generateRandomKey
Crypto.generateRandomKey(Number keyLength?): Promise<ArrayBuffer>
This call obtains a randomly-generated binary key of the specified key length.
Parameters
| Parameter | Description | Type |
|---|---|---|
| keyLength | Optional with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | number |
Returns
Returns a promise. On success, the promise is fulfilled with the generated key as an ArrayBuffer. On failure, the promise is rejected with an ErrorInfo object that details the reason why it was rejected.
Example
1
2
const key = await Ably.Rest.Crypto.generateRandomKey(256);
const channel = rest.channels.get('aft-far-spy', { cipher: { key: key } });Related types
ChannelOptions Object
Channel options are used for setting channel parameters and configuring encryption.
ChannelOptions, a plain JavaScript object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following attributes can be defined on the object:
Properties
| Property | Description | Type |
|---|---|---|
| params | Optional parameters which specify behaviour of the channel. | JSON Object |
| cipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example | CipherParams or an options object containing at a minimum a key |
CipherParams
A CipherParams contains configuration options for a channel cipher, including algorithm, mode, key length and key. Ably client libraries currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128.
Individual client libraries may support either instancing a CipherParams directly, using Crypto.getDefaultParams(), or generating one automatically when initializing a channel, as in this example.
Properties
| Property | Description | Type |
|---|---|---|
| key | A binary (ArrayBuffer or Uint8Array) or base64-encoded String containing the secret key used for encryption and decryption | |
| algorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES" default: AES | String |
| keyLength | The key length in bits of the cipher, either 128 or 256 default: 256 | Integer |
| mode | The cipher mode default: CBC | String |