# Quick Start

<!--- Template Guidance 
Write a short introduction and the getting started guide to your product. 
If there are any standout features to call it, this is probably the place to do it. 

NOTE: Take a look at the quick-start of Object Storage for an idea on the tone and the level of detail. 
-->

## Prerequisites

Update to the latest Exoscale CLI (minimum version: 1.74.5). For
installation, visit [Exoscale CLI Installation](https://github.com/exoscale/cli#installation).


## KMS Keys

### Create

Create a key and assign it a name that reflects its intended purpose:

```bash
exo kms key create my-key-name
```

The command returns the key's UUID, which you'll reference in all subsequent operations.

### List

List all keys in your organization:

```bash
exo kms key list
```

To inspect a specific key's status, zone, and metadata:

```bash
exo kms key show <key-uuid>
```

### Replication

For enabling replication of a kms key, you need to create a key with the `--multizone` flag:
```bash
exo kms key create replication-key-name --multizone
```

Then replicate it to a target zone:

```bash
exo kms key replicate <key-uuid> de-fra-1
```

Once replicated, you can direct operations to the replica either via a zone-specific CLI profile or the `--zone` flag:

```bash
exo kms crypto encrypt <key-uuid> "ZGVhdGggc3RhciBwbGFucwo=" --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg==" --zone de-fra-1
```

### Enable and Disable

Disabling a key blocks all cryptographic operations without destroying the key material. For replicated keys, this operation is zone-scoped. That means disabling a key in one zone leaves replicas in other zones fully operational.

```bash
exo kms key disable <key-uuid>
```

```bash
exo kms key enable <key-uuid>
```

### Deletion

Key deletion is a two-step process with a mandatory delay (7–30 days) to protect against accidental or premature deletion. During the `pending-deletion` period, all cryptographic operations on the key are disabled. Once the delay expires, the key and its material are permanently destroyed with no recovery.

Schedule a deletion:

```bash
exo kms key schedule-deletion <key-uuid> --delay-days 7
```

Cancel before the delay expires:

```bash
exo kms key cancel-deletion <key-uuid>
```

## Cryptographic Operations

### Encrypt

Plaintext must be base64-encoded. The encryption context is an authenticated, non-secret string bound to the ciphertext. If provided, it must be presented identically at decryption time.

```bash
exo kms crypto encrypt <key-uuid> "ZGVhdGggc3RhciBwbGFucwo=" --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg=="
```

The command returns base64-encoded ciphertext.

### Decrypt

```bash
exo kms crypto decrypt <key-uuid> <ciphertext> --encryption-context "bXktZW5jcnlwdGlvbi1jb250ZXh0Cg=="
```

The decryption context must match exactly what was used at encryption time. A mismatch results in a decryption failure.

### Generate Data Key

For bulk data, use envelope encryption: generate a DEK, encrypt your data locally with it, then discard the plaintext DEK. Store only the encrypted DEK alongside your ciphertext.

```bash
exo kms crypto generate-data-key <key-uuid> --key-spec AES-256 --encryption-context "Z2VuZXJhdGUtZGVrLWNvbnRleHQK"
```

The response includes both the plaintext and encrypted DEK. Use the plaintext DEK with your local cryptographic library, discard it immediately after use, and persist the encrypted form.

To decrypt again, call `decrypt` with the stored encrypted DEK to recover the plaintext DEK, then use it locally to decrypt your data.