Symmetric encryption in KMS

One of the available encryption modes in KMS is symmetric encryption. It uses the same (symmetric) key for both data encryption and decryption. KMS supports the AES with 128, 192, or 256-bit keys in GCM mode.

An important condition for secure encryption is the use of a cryptographically stable pseudo-random number generator (necessary for generating encryption keys and initialization vectors). KMS uses its own implementation of the Fortuna algorithm, which collects entropy from various sources (RDSEED and RDRAND, /dev/urandom, host entropy).

If you are using a Hardware Security Module (HSM), encryption keys are generated inside the HSM using a built-in reliable entropy generator.

The crypto material contained in key versions is not available as plaintext outside KMS. Encryption and decryption in KMS is performed by two cryptographic operations: encrypt and decrypt.

Encrypt operationEncrypt operation

1. Accepts the key ID (keyID) together with plaintext (plaintext) as input data.

   To perform encryption using a non-primary key version, supply the ID of any active key version (versionId) to the operation input.

2. Encrypts plaintext using the algorithm and cryptographic material of the primary key version.

3. Returns the resulting ciphertext (ciphertext).

The encrypt operation is suitable for encrypting small amounts of data. The maximum plaintext size is 32 KB. To encrypt large amounts of data, use envelope encryption.

Decrypt operationDecrypt operation

1. Accepts the key ID (keyID) and ciphertext (ciphertext) as input data.

   The ciphertext generated by the encrypt operation contains the version ID (versionId) used for encryption. The algorithm and cryptographic material for decryption are taken from this version of the key.

2. Decrypts the text.

3. Returns the resulting plaintext.

In KMS, the encrypt and decrypt operations support the transmission of AAD (Additional Authenticated Data) context as the parameter (aadContext) for extra encryption security.

AAD contextAAD context

Additional Authenticated Data (AAD) is additional data passed to the input of the encrypt and decrypt operations. To successfully decrypt data, provide the same AAD context as that provided for encryption.

The AAD context is closely related to the encrypted data (without knowing the AAD context, it is impossible to decrypt the ciphertext), but it does not increase the cryptographic stability of the ciphertext and is not part of it. The AAD context is designed to protect against confused deputy attacks through additional verification of the data during decryption.

Example of a confused deputy attackExample of a confused deputy attack

The service stores the users' residential addresses in relation to their usernames. The addresses are saved to the database in encrypted form. They are encrypted with a key but no AAD context. Each DB record is marked as belonging to a particular user.

• Alice used the service and gave her address.
  • A new entry is added to the database and marked as belonging to Alice. It contains the address in encrypted form.
  • Alice can see her address: records belonging to her will be selected from the database, decrypted, and shown to Alice.
• Another user, Trudy, was granted access to the database.
  • Trudy has no encryption key and cannot decrypt the content of the database, but she can modify it.
  • Trudy marks the entry containing Alice's encrypted address as owned by her and can now see Alice's address.

The problem is solved if during the encryption process you provide, for example, username as AAD context. In this case:

1. Trudy will try to view Alice's data marked as her own.
2. The service will pass Trudy's username instead of Alice's one as AAD context.
3. The data cannot be decrypted.

Use casesUse cases

• Encrypting data using the Yandex Cloud CLI and API
• Encrypting data using the Yandex Cloud SDK
• Encrypting secrets in Yandex Managed Service for Kubernetes
• Secure password transmission to an initialization script