Encryption
The Ably.Realtime.Crypto object exposes the following public methods:
Methods
getDefaultParams
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
- params
- The cipher params that you want to specify. It must at a minimum include a
key, which should be either a binary () or a base64-encodedString.
Returns
On success, the method returns a complete CipherParams object. Failure will raise an exception.
Example
var cipherParams = Ably.Realtime.Crypto.getDefaultParams({key: <key>});
var channelOpts = { cipher: cipherParams };
var channel = realtime.channels.get('mud-ate-ago', channelOpts);
CopyCopied!generateRandomKey
Crypto.generateRandomKey(Int keyLength?, callback(ErrorInfo err,
Bufferkey))
This call obtains a randomly-generated binary key of the specified key length.
Parameters
- keyLength
- Optional
Intwith the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256128. - callback
- is a function of the form
function(err, key)which is called upon completion
Example
Ably.Realtime.Crypto.generateRandomKey(256, function(err, key) {
if(err) {
console.log("Key generation failed: " + err.toString());
} else {
var channel = realtime.channels.get('mud-ate-ago', {cipher: {key: key}});
}
});
CopyCopied!Related types
ChannelOptions Object
Channel options are used for configuring encryption.
Properties
- 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:
CipherParams
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 () or base64-encoded
Stringcontaining 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