# Crypto

The `Crypto` object provides utility methods for generating encryption keys and constructing `CipherParams` for use with [encrypted channels](https://ably.com/docs/channels/options/encryption.md). Access it via the `Crypto` property of a [`Realtime`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md) client instance.

<Aside data-type='note'>
Ably SDKs currently support AES with CBC, PKCS#7 with a default key length of 256 bits. All implementations also support AES128.
</Aside>

<Code>

#### Javascript

```
const crypto = Ably.Realtime.Crypto;
```
</Code>

## Get default cipher params 

`Crypto.getDefaultParams(params: CipherParamOptions): CipherParams`

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 valid and self-consistent.

You will rarely need to call this yourself, since the SDK 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.md)) or when setting channel options with [`channel.setOptions()`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-channel.md#set-options).

<Code>

### Javascript

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

### Parameters 

The `Crypto.getDefaultParams()` method takes the following parameters:

<Table id='GetDefaultParamsParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| params | Required | The cipher params that you want to specify. It must at a minimum include a `key`, which should be either binary (`ArrayBuffer` or `Uint8Array`) or a base64-encoded `String`. | <Table id='CipherParamOptions'/> |

</Table>

<Table id='CipherParamOptions' >

| Property | Required | Description | Type |
| --- | --- | --- | --- |
| key | Required | The private key used for encryption and decryption. Can be binary or base64-encoded. | `ArrayBuffer`, `Uint8Array`, or String |
| algorithm | Optional | The name of the algorithm in the default system provider, or the lower-cased version of it; for example `aes` or `AES`. Default: `AES`. | String |
| keyLength | Optional | The key length in bits. Either 128 or 256. Default: 256. | Number |
| mode | Optional | The cipher mode. Default: `CBC`. | String |

</Table>

### Returns 

`CipherParams`

Returns a complete `CipherParams` object. Throws an exception if the params are invalid or inconsistent.

<Table id='CipherParams'>

| Property | Description | Type |
| --- | --- | --- |
| key | The private key used for encryption and decryption. Do not set this value directly; pass a key to [`getDefaultParams()`](#get-default-params) instead. | `unknown` |
| algorithm | The name of the algorithm in the default system provider, or the lower-cased version of it; for example `aes` or `AES`. Default: `AES`. | String |
| keyLength | The key length in bits of the cipher. Either 128 or 256. Default: 256. | Number |
| mode | The cipher mode. Default: `CBC`. | String |

</Table>

## Generate a random key 

`Crypto.generateRandomKey(keyLength?: number): Promise<CipherKey>`

Generates a randomly-generated binary key of the specified key length. The returned key can be used directly as the `key` field of a `CipherParams` object or in a channel's `cipher` options.

You will rarely need to call this yourself, since the SDK will handle key generation for you when [encryption is configured on a channel](https://ably.com/docs/channels/options/encryption.md).

<Code>

### Javascript

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

### Parameters 

The `Crypto.generateRandomKey()` method takes the following parameters:

<Table id='GenerateRandomKeyParameters'>

| Parameter | Required | Description | Type |
| --- | --- | --- | --- |
| keyLength | Optional | The length of key to generate, in bits. For AES this should be either 128 or 256. Default: 256. | Number |

</Table>

### Returns 

`Promise<CipherKey>`

Returns a promise. The promise is fulfilled with the generated binary key (an `ArrayBuffer` in the browser, a `Buffer` in Node.js), or rejected with an [`ErrorInfo`](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md#errorinfo) object.


## Related Topics

- [Realtime client](https://ably.com/docs/pub-sub/api/javascript/realtime/realtime-client.md): API reference for the Realtime client class in the Ably Pub/Sub JavaScript Realtime SDK.
- [Auth](https://ably.com/docs/pub-sub/api/javascript/realtime/auth.md): API reference for the Authentication (Auth) interface in the Ably Pub/Sub JavaScript Realtime SDK.
- [Connection](https://ably.com/docs/pub-sub/api/javascript/realtime/connection.md): API reference for the Connection interface in the Ably Pub/Sub JavaScript Realtime SDK.

## Documentation Index

To discover additional Ably documentation:

1. Fetch [llms.txt](https://ably.com/llms.txt) for the canonical list of available pages.
2. Identify relevant URLs from that index.
3. Fetch target pages as needed.

Avoid using assumed or outdated documentation paths.