Encryption

The Ably.Realtime.Ably::Util::io.ably.lib.util.ARTCrypto object exposes the following public methods:

Methods

getDefaultParamsget_default_paramsGetDefaultParams

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

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

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.Realtime.Crypto.getDefaultParams({key: <key>});
var channelOpts = { cipher: cipherParams };
var channel = realtime.channels.get('fly-bag-bay', channelOpts);

var cipherParams = Ably.Realtime.Crypto.getDefaultParams({key: <key>});
var channelOpts = { cipher: cipherParams };
var channel = realtime.channels.get('fly-bag-bay', channelOpts);

cipher_params = Ably::Util::Crypto.get_default_params({key: <key>})
channel_opts = { cipher: cipher_params }
channel = realtime.channels.get('fly-bag-bay', channel_opts)

CipherParams params = Crypto.getDefaultParams(new Param[]{ new Param("key", <key>) });
ChannelOptions options = new ChannelOptions();
options.encrypted = true;
options.cipherParams = params;
Channel channel = realtime.channels.get("fly-bag-bay", options);

var @params = Crypto.GetDefaultParams(<key>);
ChannelOptions options = new ChannelOptions(@params);
var realtime = new AblyRealtime("xVLyHw.35Xc6w:yMp3lBFCpsA7UzCzDfv-TD0r5g-CNWzmuEMR8RyXafg");
var channel = realtime.Channels.Get("fly-bag-bay", options);

ARTCipherParams *params = [ARTCrypto getDefaultParams:@{@"key": <key>}];
ARTChannelOptions *options = [[ARTChannelOptions alloc] initWithCipher:params];
ARTRealtimeChannel *channel = [realtime.channels get:@"fly-bag-bay" options:options];

let params = ARTCrypto.getDefaultParams(["key": <key>])
let options = ARTChannelOptions(cipher: params)
let channel = realtime.channels.get("fly-bag-bay", options: options)

generateRandomKeygenerate_random_keyGenerateRandomKey

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

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

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 256128.

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

Example

Ably.Realtime.Crypto.generateRandomKey(256, function(err, key) {
  if(err) {
    console.log("Key generation failed: " + err.toString());
  } else {
    var channel = realtime.channels.get('fly-bag-bay', {cipher: {key: key}});
  }
});

Ably.Realtime.Crypto.generateRandomKey(256, function(err, key) {
  if(err) {
    console.log("Key generation failed: " + err.toString());
  } else {
    var channel = realtime.channels.get('fly-bag-bay', {cipher: {key: key}});
  }
});

key = Ably::Util::Crypto.generate_random_key(256)
channel = realtime.channels.get('fly-bag-bay', {cipher: {key: key}})

byte[] key = Crypto.generateRandomKey(256);
ChannelOptions options = ChannelOptions.withCipher(key);
Channel channel = realtime.channels.get("fly-bag-bay", options);

byte[] key = Crypto.GenerateRandomKey(keyLength: 256);
var options = new ChannelOptions(key);
var channel = realtime.Channels.Get("fly-bag-bay", options);

NSData *key = [ARTCrypto generateRandomKey:256];
ARTChannelOptions *options = [[ARTChannelOptions alloc] initWithCipherKey:key];
ARTRealtimeChannel *channel = [realtime.channels get:@"fly-bag-bay" options:options];

let key = ARTCrypto.generateRandomKey(256)
let options = ARTChannelOptions(cipherWithKey: key)
let channel = realtime.channels.get("fly-bag-bay", options: options)

Related types

ChannelOptions ObjectARTChannelOptionsChannelOptions Hashio.ably.types.ClientOptionsIO.Ably.ClientOptions

Currently the supported channel options are only used for configuring encryption.

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

CipherParamsARTCipherParamsCipherParams Hashio.ably.lib.util.Crypto.CipherParamsIO.Ably.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_128 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