> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cryptographic operations with symmetric keys

You can use [symmetric keys](/kms/types-operations#symmetric-and-asymmetric-keys) in Key Management Service (KMS) to [encrypt](#how-to-encrypt-data) and [decrypt](#how-to-decrypt-data) application data directly. Alternatively, you can use [envelope encryption](#how-to-use-envelope-encryption) to encrypt larger volumes of data locally.

## Prerequisites

1. [Install and configure](/cli/install) the Nebius AI Cloud CLI.
2. Make sure you are in a [group](/iam/authorization/groups/index) that has at least the `editor` role within your tenant or project; for example, the default `editors` group. You can check this in the [Administration → IAM](https://console.nebius.com/iam) section of the web console.

## How to encrypt data

To encrypt data with a symmetric KMS key:

1. Prepare your data to be encrypted by encoding it in [Base64](https://developer.mozilla.org/en-US/docs/Glossary/Base64). The maximum size is 64 KiB.

   For example, to encode `Hello world`:

   <CodeGroup>
     ```bash Ubuntu theme={null}
     echo -n "Hello world" | base64 -w 0
     ```

     ```bash macOS theme={null}
     echo -n "Hello world" | base64
     ```
   </CodeGroup>

   The output looks like the following:

   ```text theme={null}
   SGVsbG8gd29ybGQ=
   ```

2. Encrypt the data:

   ```bash theme={null}
   nebius kms symmetric-crypto encrypt \
     --key-id <key_ID> \
     --plaintext <plaintext_Base64> \
     --aad-context <AAD_context_Base64>
   ```

   In the command, specify the following parameters:

   * `--key-id`: ID of the symmetric key. To get it, run:

     ```bash theme={null}
     nebius kms symmetric-key list
     ```

     In the output, copy the ID of the key that you want to use.
   * `--plaintext`: Plaintext data to encrypt, encoded in Base64.
   * `--aad-context` (optional): Additional authenticated data (AAD) context linked to the ciphertext, encoded in Base64. If you specify this parameter during encryption, you must specify the same value for decryption.

   The output looks like the following:

   ```yaml theme={null}
   key_id: kmssymkey-e00***
   ciphertext: CAESI2ttc3N5bWtleXZlcnNpb24tZTAwcmV0OXM1bTV4dnp6OHR***
   ```

   The `ciphertext` parameter contains the encrypted version of your data. Save this value because it is required for [decrypting the data](#how-to-decrypt-data).

## How to decrypt data

To decrypt data with a symmetric KMS key:

1. Run the following command:

   ```bash theme={null}
   nebius kms symmetric-crypto decrypt \
     --key-id <key_ID> \
     --ciphertext <ciphertext> \
     --aad-context <AAD_context_Base64>
   ```

   In the command, specify the following parameters:

   * `--key-id`: ID of the symmetric key that was used to encrypt the data. To get it, run:

     ```bash theme={null}
     nebius kms symmetric-key list
     ```

     In the output, copy the ID of the key that you used for encryption.
   * `--ciphertext`: Encrypted data returned as `ciphertext` when you [encrypted the data](#how-to-encrypt-data).
   * `--aad-context` (optional): Extra data linked to the ciphertext, encoded in Base64. If you specified this parameter when you encrypted the data, specify the same value during decryption.

   The output looks like the following:

   ```yaml theme={null}
   key_id: kmssymkey-e00***
   plaintext: SGVsbG8gd29ybGQ=
   ```

2. Decode the `plaintext` value from Base64.

   For example, to decode `SGVsbG8gd29ybGQ=`, run:

   ```bash theme={null}
   echo 'SGVsbG8gd29ybGQ=' | base64 -d
   ```

## How to use envelope encryption

You can use [envelope encryption](/kms/types-operations#envelope-encryption) when you want KMS to use a key encryption key (KEK) stored in the service to protect a data encryption key (DEK), which is used by your application for encrypting data.

To use envelope encryption:

1. Generate a data key:

   ```bash theme={null}
   nebius kms symmetric-crypto generate-data-key \
     --key-id <key_ID> \
     --data-key-spec aes_256 \
     --aad-context <AAD_context_Base64>
   ```

   In the command, specify the following parameters:

   * `--key-id`: ID of the symmetric KMS key that should encrypt the generated data key. To get it, run:

     ```bash theme={null}
     nebius kms symmetric-key list
     ```

     In the output, copy the ID of the key that you want to use.
   * `--data-key-spec`: [Encryption algorithm](/kms/types-operations#encryption-algorithms) and key length for the generated data key. Only the `aes_256` value is supported.
   * `--aad-context` (optional): Extra data linked to the encrypted data key, encoded in Base64. If you specify this parameter, you must specify the same value when you later decrypt the encrypted data key.
   * `--skip-plaintext` (optional): Returns only the encrypted data key and doesn't return the plaintext key. For example, use this parameter if one application generates and stores encrypted data keys, while another application later decrypts and uses them. This reduces how often plaintext keys are exposed, but adds an extra step because the data key must be decrypted before use.

   The output looks like the following:

   ```yaml theme={null}
   key_id: kmssymkey-e00***
   data_key_plaintext: LpNuYDgpTjy0Z***
   data_key_ciphertext: CAESI2ttc3N5bWtleXZlcnNpb24tZTAwcmV0OXM1bTV4dnp6OHR***
   ```

   The output contains two versions of the same generated data key:

   * `data_key_plaintext`: The plaintext version of the data key that you can use to encrypt the data.
   * `data_key_ciphertext`: The encrypted version of the data key that you need to provide to decrypt the data later.

2. When you need to decrypt the data later, decrypt the data key:

   ```bash theme={null}
   nebius kms symmetric-crypto decrypt \
     --key-id <key_ID> \
     --ciphertext <data_key_ciphertext> \
     --aad-context <AAD_context_Base64>
   ```

   In the command, specify the following parameters:

   * `--key-id`: ID of the symmetric KMS key that was used to generate the data key. To get it, run:

     ```bash theme={null}
     nebius kms symmetric-key list
     ```

     In the output, copy the ID of the key that you used to generate the data key.
   * `--ciphertext`: The `data_key_ciphertext` value that was returned when you generated the data key.
   * `--aad-context` (optional): Extra data linked to the encrypted data key, encoded in Base64. Specify this parameter only if you provided it when you generated the data key. In that case, specify the same value here.

   The output contains the plaintext data key.

3. Use the plaintext data key that KMS returned to decrypt the data locally.