# Encryption

The <If lang="javascript,nodejs,flutter,csharp">`Ably.Realtime.Crypto`</If><If lang="ruby">`Ably::Util::Crypto`</If><If lang="java">`io.ably.lib.util.Crypto`</If><If lang="swift,objc">`ARTCrypto`</If> object exposes the following public methods:

## Methods 

### <If lang="javascript,nodejs,java,flutter,objc,swift">getDefaultParams</If><If lang="ruby">get_default_params</If><If lang="csharp">GetDefaultParams</If>

<If lang="javascript,nodejs">

`Crypto.getDefaultParams(Object params): CipherParams`

</If>
<If lang="ruby">

`CipherParams Crypto.get_default_params(Hash params)`

</If>
<If lang="java">

`CipherParams Crypto.getDefaultParams(Param[] params)`

</If>
<If lang="swift,objc">

`getDefaultParams(values: [NSObject : AnyObject]) -> ARTCipherParams`

</If>
<If lang="csharp">

`static CipherParams GetDefaultParams(byte[] key = null, byte[] iv = null, CipherMode? mode = null)`

</If>

This call obtains a [`CipherParams`](#cipher-params) 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](https://ably.com/docs/channels/options/encryption))<If lang="javascript,nodejs"> or when setting channel options with `channel.setOptions()`</If>.

#### Parameters

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">params</If><If lang="csharp">arguments</If> | The cipher <If lang="javascript,nodejs,flutter,java,objc,swift,ruby">params</If><If lang="csharp">arguments</If> that you want to specify. It must at a minimum include a `key`, which should be either a binary (<If lang="java,csharp">`byte[]`</If><If lang="javascript">`ArrayBuffer` or `Uint8Array`</If><If lang="nodejs">`Buffer`</If><If lang="ruby">byte array</If><If lang="objc,swift">`NSData`</If>) or a base64-encoded <If lang="objc">`NS`</If>`String`. | <If lang="javascript,nodejs">`Object`</If><If lang="ruby">`Hash`</If><If lang="java">`Param[]`</If><If lang="objc,swift">`[NSObject : AnyObject]`</If><If lang="csharp">`byte[] key`, `byte[] iv`, `CipherMode? mode`</If> |

#### Returns

On success, the method returns a complete [`CipherParams`](#cipher-params) object. Failure will raise an <If lang="ruby,java">[`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception) </If><If lang="javascript,nodejs,flutter,objc,swift,csharp">exception</If>.

#### Example

<If lang="javascript">
<Code>
```javascript
  const cipherParams = Ably.Realtime.Crypto.getDefaultParams({ key: <key> });
  const channelOpts = { cipher: cipherParams };
  const channel = realtime.channels.get('your-channel-name', channelOpts);
```
</Code>
</If>

<If lang="nodejs">
<Code>
```nodejs
  const cipherParams = Ably.Realtime.Crypto.getDefaultParams({ key: <key> });
  const channelOpts = { cipher: cipherParams };
  const channel = realtime.channels.get('your-channel-name', channelOpts);
```
</Code>
</If>

<If lang="ruby">
<Code>
```ruby
  cipher_params = Ably::Util::Crypto.get_default_params({key: <key>})
  channel_opts = { cipher: cipher_params }
  channel = realtime.channels.get('your-channel-name', channel_opts)
```
</Code>
</If>

<If lang="java">
<Code>
```java
  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("your-channel-name", options);
```
</Code>
</If>

<If lang="csharp">
<Code>
```csharp
  var @params = Crypto.GetDefaultParams(<key>);
  ChannelOptions options = new ChannelOptions(@params);
  var realtime = new AblyRealtime("your-api-key");
  var channel = realtime.Channels.Get("your-channel-name", options);
```
</Code>
</If>

<If lang="objc">
<Code>
```objc
ARTCipherParams *params = [ARTCrypto getDefaultParams:@{@"key": <key>}];
ARTChannelOptions *options = [[ARTChannelOptions alloc] initWithCipher:params];
ARTRealtimeChannel *channel = [realtime.channels get:@"your-channel-name" options:options];
```
</Code>
</If>

<If lang="swift">
<Code>
```swift
let params = ARTCrypto.getDefaultParams(["key": <key>])
let options = ARTChannelOptions(cipher: params)
let channel = realtime.channels.get("your-channel-name", options: options)
```
</Code>
</If>

### <If lang="javascript,nodejs,java,flutter,objc,swift">generateRandomKey</If><If lang="ruby">generate_random_key</If><If lang="csharp">GenerateRandomKey</If>

<If lang="flutter">

`Crypto.generateRandomKey(Int keyLength?, callback(ErrorInfo err, Buffer key))`

</If>
<If lang="javascript">

`Crypto.generateRandomKey(Number keyLength?): Promise<ArrayBuffer>`

</If>
<If lang="nodejs">

`Crypto.generateRandomKey(Number keyLength?): Promise<Buffer>`

</If>
<If lang="ruby">

`byte array Crypto.generate_random_key(Int key_length?)`

</If>
<If lang="java">

`byte[] Crypto.generateRandomKey(Int keyLength?)`

</If>
<If lang="objc,swift">

`generateRandomKey(length?: UInt) -> NSData`

</If>
<If lang="csharp">

`static byte[] GenerateRandomKey(CipherMode? mode = null, int? keyLength = null)`

</If>

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

#### Parameters

<If lang="javascript,nodejs,flutter,java,ruby,objc,swift">

| Parameter | Description | Type |
|-----------|-------------|------|
| <If lang="javascript,nodejs,flutter,java,objc,swift">keyLength</If><If lang="ruby">key_length</If> | Optional. The length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | <If lang="flutter,java,objc,swift,ruby">`Int`</If><If lang="javascript,nodejs">`Number`</If> |

</If>

<If lang="csharp">

| Parameter | Description | Type |
|-----------|-------------|------|
| keyLength | Optional. The length of key to generate. For AES, this should be either 128 or 256. If unspecified, defaults to 256. | `Int` |
| mode | Optional AES cipher mode which is used when the key is generated | `CipherMode` |

</If>

<If lang="javascript,nodejs">

#### Returns

Returns a promise. On success, the promise is fulfilled with the generated key as <If lang="javascript">an `ArrayBuffer`</If><If lang="nodejs">a `Buffer`</If>. On failure, the promise is rejected with an [`ErrorInfo`](https://ably.com/docs/api/realtime-sdk/types#error-info) object that details the reason why it was rejected.

</If>

<If lang="java,ruby,objc,swift,csharp">

#### Returns

On success, the method returns the generated key as a <If lang="java,csharp">`byte[]` array</If><If lang="ruby">byte array</If><If lang="objc,swift">`NSData`</If>. Failure will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).

</If>

#### Example

<If lang="javascript">
<Code>
```javascript
  const key = await Ably.Realtime.Crypto.generateRandomKey(256);
  const channel = realtime.channels.get('your-channel-name', { cipher: { key: key } });
```
</Code>
</If>

<If lang="nodejs">
<Code>
```nodejs
  const key = await Ably.Realtime.Crypto.generateRandomKey(256);
  const channel = realtime.channels.get('your-channel-name', { cipher: { key: key } });
```
</Code>
</If>

<If lang="ruby">
<Code>
```ruby
  key = Ably::Util::Crypto.generate_random_key(256)
  channel = realtime.channels.get('your-channel-name', {cipher: {key: key}})
```
</Code>
</If>

<If lang="java">
<Code>
```java
  byte[] key = Crypto.generateRandomKey(256);
  ChannelOptions options = ChannelOptions.withCipher(key);
  Channel channel = realtime.channels.get("your-channel-name", options);
```
</Code>
</If>

<If lang="csharp">
<Code>
```csharp
  byte[] key = Crypto.GenerateRandomKey(keyLength: 256);
  var options = new ChannelOptions(key);
  var channel = realtime.Channels.Get("your-channel-name", options);
```
</Code>
</If>

<If lang="objc">
<Code>
```objc
  NSData *key = [ARTCrypto generateRandomKey:256];
  ARTChannelOptions *options = [[ARTChannelOptions alloc] initWithCipherKey:key];
  ARTRealtimeChannel *channel = [realtime.channels get:@"your-channel-name" options:options];
```
</Code>
</If>

<If lang="swift">
<Code>
```swift
let key = ARTCrypto.generateRandomKey(256)
let options = ARTChannelOptions(cipherWithKey: key)
let channel = realtime.channels.get("your-channel-name", options: options)
```
</Code>
</If>

## Related types 

### <If lang="javascript,nodejs,flutter">ChannelOptions Object</If><If lang="objc,swift">ARTChannelOptions</If><If lang="ruby">ChannelOptions Hash</If><If lang="java">io.ably.types.ChannelOptions</If><If lang="csharp">IO.Ably.ChannelOptions</If> 

Channel options are used for <If lang="javascript,nodejs,java,swift,objc,csharp">setting [channel parameters](https://ably.com/docs/channels/options) and</If> [configuring encryption](https://ably.com/docs/channels/options/encryption).

<If lang="javascript,nodejs">
`ChannelOptions`, a plain JavaScript object, may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options. The following attributes can be defined on the object:
</If>

<If lang="ruby">
`ChannelOptions`, a Hash object, may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:
</If>

<If lang="java,swift,objc">
<If lang="swift,objc">`ART`</If><If lang="java">`io.ably.lib.types.`</If>`ChannelOptions` may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options.
</If>

<If lang="csharp">
`IO.Ably.ChannelOptions` may optionally be specified when instancing a [`Channel`](https://ably.com/docs/channels), and this may be used to specify channel-specific options.
</If>

#### <If lang="javascript,nodejs,flutter,objc,swift,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

<If lang="javascript,nodejs,flutter,objc,swift,csharp,java">

| Property | Description | Type |
|----------|-------------|------|
| <If lang="javascript,nodejs,java,swift,objc">params</If><If lang="csharp">Params</If> | Optional [parameters](https://ably.com/docs/channels/options) which specify behaviour of the channel. | <If lang="java">`Map<String, String>`</If><If lang="javascript,nodejs,objc,csharp,swift">`JSON Object`</If> |
| <If lang="javascript,nodejs,java,swift,objc">cipher</If><If lang="csharp">CipherParams</If> | 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](https://ably.com/docs/channels/options/encryption). Must contain at a minimum a `key`. | [`CipherParams`](https://ably.com/docs/api/realtime-sdk/encryption#cipher-params)<If lang="javascript,nodejs"> or options object</If><If lang="java"> or `Param[]`</If><If lang="ruby"> or options hash</If> |

</If>

<If lang="ruby">

| 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](docs/channels/options/encryption) | [`CipherParams`](https://ably.com/docs/api/realtime-sdk/encryption) or an options hash containing at a minimum a `key` |

</If>

<If lang="java">
#### 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

| Parameter | Description | Type |
|-----------|-------------|------|
| key | A binary `Byte[]` array or a base64-encoded `String`. | `Byte[]` or `String` |

#### Returns

On success, the method returns a complete `ChannelOptions` object. Failure will raise an [`AblyException`](https://ably.com/docs/api/realtime-sdk/types#ably-exception).
</If>

### <If lang="javascript,nodejs,flutter">CipherParams</If><If lang="objc,swift">ARTCipherParams</If><If lang="ruby">CipherParams Hash</If><If lang="java">io.ably.lib.util.Crypto.CipherParams</If><If lang="csharp">IO.Ably.CipherParams</If> 

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 <If lang="javascript,nodejs,flutter,objc,swift,java">[`Crypto.getDefaultParams()`](https://ably.com/docs/api/realtime-sdk/encryption#get-default-params)</If><If lang="csharp">[`Crypto.GetDefaultParams()`](https://ably.com/docs/api/realtime-sdk/encryption#get-default-params)</If><If lang="ruby">[`Crypto.get_default_params()`](https://ably.com/docs/api/realtime-sdk/encryption#get-default-params)</If>, or generating one automatically when initializing a channel, as in [this example](https://ably.com/docs/channels/options/encryption).

#### <If lang="javascript,nodejs,flutter,objc,swift,csharp">Properties</If><If lang="java">Members</If><If lang="ruby">Attributes</If>

<If lang="javascript,nodejs,flutter,ruby,objc,swift,csharp">

| Property | Description | Type |
|----------|-------------|------|
| <If lang="javascript,nodejs,flutter,objc,swift">key</If><If lang="csharp">Key</If><If lang="ruby">:key</If> | The secret key used for encryption and decryption. Can be binary or base64-encoded. | <If lang="csharp">`byte[]`</If><If lang="javascript">`ArrayBuffer` or `Uint8Array`</If><If lang="nodejs">`Buffer`</If><If lang="ruby">byte array</If><If lang="objc,swift">`NSData`</If><If lang="flutter">`String`</If> or base64-encoded <If lang="objc">`NS`</If>`String` |
| <If lang="javascript,nodejs,flutter,objc,swift">algorithm</If><If lang="ruby">:algorithm</If><If lang="csharp">Algorithm</If> | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES".<br />_Default: AES_. | `String` |
| <If lang="javascript,nodejs,flutter,objc,swift">keyLength</If><If lang="ruby">:key_length</If><If lang="csharp">KeyLength</If> | The key length in bits of the cipher, either 128 or 256.<br />_Default: 256_. | `Integer` |
| <If lang="javascript,nodejs,flutter,objc,swift">mode</If><If lang="ruby">:mode</If><If lang="csharp">Mode</If> | The cipher mode.<br />_Default: CBC_. | <If lang="javascript,nodejs,flutter,objc,swift,ruby">`String`</If><If lang="csharp">`CipherMode`</If> |

</If>

<If lang="java">

| Property | Description | Type |
|----------|-------------|------|
| algorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; eg "aes" or "AES".<br />_Default: AES_. | `String` |
| keyLength | The key length in bits of the cipher, either 128 or 256.<br />_Default: 256_. | `Integer` |
| mode | The cipher mode.<br />_Default: CBC_. | `String` |
| keySpec | A `KeySpec` for the cipher key. | `SecretKeySpec` |

</If>