Encryption
The Ably::Util::Crypto object exposes the following public methods:
Methods
get_default_params
CipherParams Crypto.get_default_params(Hash params)
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).
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 (byte array) or a base64-encoded String. | Hash |
Returns
On success, the method returns a complete CipherParams object. Failure will raise an AblyException .
Example
1
2
3
cipher_params = Ably::Util::Crypto.get_default_params({key: <key>})
channel_opts = { cipher: cipher_params }
channel = realtime.channels.get('who-fab-dip', channel_opts)generate_random_key
byte array Crypto.generate_random_key(Int key_length?)
This call obtains a randomly-generated binary key of the specified key length.
Parameters
| Parameter | Description | Type |
|---|---|---|
| key_length | Optional. The length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | Int |
Returns
On success, the method returns the generated key as a byte array. Failure will raise an AblyException.
Example
1
2
key = Ably::Util::Crypto.generate_random_key(256)
channel = realtime.channels.get('who-fab-dip', {cipher: {key: key}})Related types
ChannelOptions Hash
Channel options are used for configuring encryption.
ChannelOptions, a Hash object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:
Attributes
| Property | Description | Type |
|---|---|---|
| :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 hash containing at a minimum a key |
CipherParams Hash
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.get_default_params(), or generating one automatically when initializing a channel, as in this example.
Attributes
| Property | Description | Type |
|---|---|---|
| :key | The secret key used for encryption and decryption. Can be binary or base64-encoded. | byte array or base64-encoded String |
| :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 |
| :key_length | The key length in bits of the cipher, either 128 or 256. Default: 256. | Integer |
| :mode | The cipher mode. Default: CBC. | String |