Encryption
The Ably.Realtime.Crypto object exposes the following public methods:
Methods
getDefaultParams
Crypto.getDefaultParams(Object params): CipherParams
This call obtains a 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 getting started example) or when setting channel options with channel.setOptions().
Parameters
- params
- The cipher params that you want to specify. It must at a minimum include a
key, which should be either a binary (ArrayBufferorUint8Array) or a base64-encodedString.
Returns
On success, the method returns a complete CipherParams object. Failure will raise an exception.
Example
const cipherParams = Ably.Realtime.Crypto.getDefaultParams({ key: <key> });
const channelOpts = { cipher: cipherParams };
const channel = realtime.channels.get('dry-tag-bay', channelOpts);
CopyCopied!generateRandomKey
Crypto.generateRandomKey(Number keyLength?): Promise<ArrayBuffer>
This call obtains a randomly-generated binary key of the specified key length.
Parameters
- keyLength
- Optional number with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256.
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
const key = await Ably.Realtime.Crypto.generateRandomKey(256);
const channel = realtime.channels.get('dry-tag-bay', { cipher: { key: key } });
CopyCopied!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
- params
- Optional parameters which specify behaviour of the channel.Type:
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 exampleType:
CipherParamsor an options object containing at a minimum akey
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
- key
- A binary (
ArrayBufferorUint8Array) or base64-encodedStringcontaining the secret key used for encryption and decryption - algorithm
- AES The name of the algorithm in the default system provider, or the lower-cased version of it; eg “aes” or “AES“Type:
String - keyLength
- 256 The key length in bits of the cipher, either 128 or 256Type:
Integer - mode
- CBC The cipher modeType:
String