Skip to main content
You can use symmetric keys in Key Management Service (KMS) to encrypt and decrypt application data directly. Alternatively, you can use envelope encryption to encrypt larger volumes of data locally.

​
Prerequisites

  1. Install and configure the Nebius AI Cloud CLI.
  2. Make sure you are in a group 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 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. The maximum size is 64 KiB. For example, to encode Hello world: 
    echo -n "Hello world" | base64 -w 0
    The output looks like the following: 
    SGVsbG8gd29ybGQ=
  2. Encrypt the data: 
    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: 
      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: 
    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

To decrypt data with a symmetric KMS key:
  1. Run the following command: 
    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: 
      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.
    • --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: 
    key_id: kmssymkey-e00***
plaintext: SGVsbG8gd29ybGQ=
  2. Decode the plaintext value from Base64. For example, to decode SGVsbG8gd29ybGQ=, run: 
    echo 'SGVsbG8gd29ybGQ=' | base64 -d

​
How to use envelope encryption

You can use 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: 
    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: 
      nebius kms symmetric-key list
      In the output, copy the ID of the key that you want to use.
    • --data-key-spec: Encryption algorithm 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: 
    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: 
    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: 
      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.