Warning: You are viewing an old version (1.0) of this documentation. We recommend you view the latest version 1.2.
API Reference

Encryption

The Ably.Rest.CryptoAbly::Util::CryptoAbly\Utils\Cryptoably.util.cryptoio.ably.lib.util.cryptoARTCrypto IO.Ably.Encryption.Crypto object exposes the following public methods:

Methods

getDefaultParamsget_default_paramsget_default_paramsGetDefaultParams

CipherParams Crypto.getDefaultParams(Object params)CipherParams Crypto.get_default_params(Hash params)CipherParams Crypto.get_default_params(Dict params)CipherParams Crypto.getDefaultParam(Array params)CipherParams Crypto.getDefaultParams(Param[] params)CipherParams GetDefaultParams(byte[] key = null, byte[] iv = null, CipherMode? mode = null)getDefaultParams(values: [NSObject : AnyObject]) → ARTCipherParams

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.This call takes a key, an initialization vector (iv) and a Cipher mode. There is also on override which accepts the key and iv as base64 encoded strings. It will validate the passed values and generate CipherParams

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

paramsarguments
The cipher paramsarguments that you want to specify. It must at a minimum include a key, which should be either a binary (byte[]ArrayBuffer or WordArrayBufferbyte arrayNSData) or a base64-encoded NSString.

Returns

On success, the method returns a complete CipherParams object. Failure will raise an AblyException exception.

Example

var cipherParams = Ably.Rest.Crypto.getDefaultParams({key: <key>});
var channelOpts = { cipher: cipherParams };
var channel = rest.channels.get('bad-ewe-cub', channelOpts);
var cipherParams = Ably.Rest.Crypto.getDefaultParams({key: <key>});
var channelOpts = { cipher: cipherParams };
var channel = rest.channels.get('bad-ewe-cub', channelOpts);
cipher_params = Ably::Util::Crypto.get_default_params({key: <key>})
channel_opts = { cipher: cipher_params }
channel = rest.channels.get('bad-ewe-cub', channel_opts)
cipher_params = ably.util.crypto.get_default_params({'key': <key>})
channel = rest.channels.get('bad-ewe-cub', cipher=cipher_params)
$cipherParams = Ably\Utils\Crypto->getDefaultParams(array('key' => <key>));
$channelOpts = array('cipher' => $cipherParams);
$channel = $rest->channels->get('bad-ewe-cub', $channelOpts);
CipherParams params = Crypto.getDefaultParams(new Param[]{ new Param("key", <key>) });
ChannelOptions options = new ChannelOptions();
options.encrypted = true;
options.cipherParams = params;
Channel channel = rest.channels.get("bad-ewe-cub", options);
CipherParams cipherParams = Crypto.GetDefaultParams(<key>);
var channel = rest.Channels.Get("bad-ewe-cub", new ChannelOptions(cipherParams));
ARTCipherParams *params = [ARTCrypto getDefaultParams:@{@"key": <key>}];
ARTChannelOptions *options = [[ARTChannelOptions alloc] initWithCipher:params];
ARTRealtimeChannel *channel = [rest.channels get:@"bad-ewe-cub" options:options];
let params = ARTCrypto.getDefaultParams(["key": <key>])
let options = ARTChannelOptions(cipher: params)
let channel = rest.channels.get("bad-ewe-cub", options: options)
generateRandomKeygenerate_random_keygenerate_random_keyGenerateRandomKey

Crypto.generateRandomKey(Int keyLength?, callback(ErrorInfo err, Buffer key))byte array Crypto.generate_random_key(Int key_length?)byte array Crypto.generate_random_key(Int key_length?)string Crypto.generateRandomKey(Int keyLength?)byte[] Crypto.generateRandomKey(Int keyLength?)byte[] GenerateRandomKey(int? keyLength = null, CipherMode? mode = null)generateRandomKey(length?: UInt) → NSData

This call obtains a randomly-generated binary key of the specified key length and optional CipherMode.

Parameters

keyLengthkey_length
Optional Int with the length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256.
mode
Optional AES CipherMode which is used when the key is generated
callback
is a function of the form function(err, key) which is called upon completion

Callback result

On successfully generating a key, the callback is called with that key as a WordArrayBuffer, and err is null. On failure to create a key, err contains an ErrorInfo object describing the failure reason.

Returns

On success, the method returns the generated key as a byte[] arraybytesbyte arraybinary stringNSData. Failure will raise an AblyException .

Example

Ably.Rest.Crypto.generateRandomKey(256, function(err, key) {
  if(err) {
    console.log("Key generation failed: " + err.toString());
  } else {
    var channel = rest.channels.get('bad-ewe-cub', {cipher: {key: key}});
  }
});
Ably.Rest.Crypto.generateRandomKey(256, function(err, key) {
  if(err) {
    console.log("Key generation failed: " + err.toString());
  } else {
    var channel = rest.channels.get('bad-ewe-cub', {cipher: {key: key}});
  }
});
key = Ably::Util::Crypto.generate_random_key(256)
channel = rest.channels.get('bad-ewe-cub', { cipher: {key: key}})
cipher_params = ably.util.crypto.generate_random_key(256)
channel = rest.channels.get('bad-ewe-cub', cipher={'key': key})
$key = Ably\Utils\Crypto->generateRandomKey(256);
$channel = $rest->channels->get('bad-ewe-cub', array('cipher' => array('key' => $key)));
byte[] key = Crypto.generateRandomKey(256);
ChannelOptions options = ChannelOptions.withCipher(key);
Channel channel = rest.channels.get("bad-ewe-cub", options);
byte[] key = Crypto.GenerateRandomKey(256);
ChannelOptions options = new ChannelOptions(key);
var channel = rest.Channels.Get("bad-ewe-cub", options);
NSData *key = [ARTCrypto generateRandomKey:256];
ARTChannelOptions *options = [[ARTChannelOptions alloc] initWithCipherKey:key];
ARTRealtimeChannel *channel = [rest.channels get:@"bad-ewe-cub" options:options];
let key = ARTCrypto.generateRandomKey(256)
let options = ARTChannelOptions(cipherWithKey: key)
let channel = rest.channels.get("bad-ewe-cub", options: options)

ChannelOptions ObjectARTChannelOptionsChannelOptions HashChannelOptions DictChannelOptions ArrayIO.Ably.ChannelOptionsio.ably.lib.types.ChannelOptions

Currently the supported channel options are only used for 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:

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:

ChannelOptions, an Associative Array, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following named keys and values can be added to the Associated Array:

ARTio.ably.lib.types.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

IO.Ably.ChannelOptions may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options.

PropertiesMembersAttributes

cipher:cipherCipherParams
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
Type: CipherParams or an options objecta Param[] listan options hashan Associative Array containing at a minimum a key

Static methods

withCipherKey

static ChannelOptions.withCipherKey(Byte[] or String key)

A helper method to generate a ChannelOptions for the simple case where you only specify a key.

Parameters

key
A binary Byte[] array or a base64-encoded String.

Returns

On success, the method returns a complete ChannelOptions object. Failure will raise an AblyException.

CipherParamsARTCipherParamsCipherParams HashCipherParams DictCipherParams ArrayIO.Ably.CipherParamsio.ably.lib.util.Crypto.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()Crypto.GetDefaultParams()Crypto.get_default_params(), or generating one automatically when initializing a channel, as in this example.

PropertiesMembersAttributes

keyKey:key
A binary (byte[]ArrayBuffer or WordArrayBufferbyte arrayNSData) containing the secret key used for encryption and decryption
algorithm:algorithmAlgorithm
AES The name of the algorithm in the default system provider, or the lower-cased version of it; eg “aes” or “AES
Type: String
key_length:key_lengthkeyLengthKeyLength
256 The key length in bits of the cipher, either 128 or 256
Type: Integer
mode:modeMode
CBC The cipher mode
Type: StringCipherMode
keySpec
A KeySpec for the cipher key
Type: SecretKeySpec

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.