Encryption
- Methods
- Related types
The Ably.Realtime.
Ably::Util::
io.ably.lib.util.
ART
Crypto
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
orWordArray
Buffer
byte arrayNSData
) or a base64-encodedNS
String
.
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
Callback result
On successfully generating a key, the callback is called with that key as a WordArray
Buffer
, 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[]
arraybyte arrayNSData
. Failure will raise an AblyException
.
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.
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:
ART
io.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 objectaParam[]
listan options hashan Associative Array containing at a minimum akey
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-encodedString
.
Returns
On success, the method returns a complete ChannelOptions
object. Failure will raise an AblyException
.
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
orWordArray
Buffer
byte 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:String
CipherMode
- keySpec
- A
KeySpec
for the cipher key
Type:SecretKeySpec