[Yandex Cloud documentation](../../index.md) > [Yandex Key Management Service](../index.md) > [Step-by-step guides](index.md) > Symmetric encryption > Data encryption

# Symmetric data encryption

In this section, you will learn how to use KMS to encrypt and decrypt small-sized data (up to 32 KB) in [symmetric encryption](../concepts/symmetric-encryption.md) mode using the CLI, Terraform, and API. For more information about the available encryption methods, see [Which encryption method should I choose?](../tutorials/encrypt/index.md).

## Getting started {#before-you-begin}

If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

## Encrypt data {#encryption}

{% note info %}

Changes caused by [eventually consistent operations](../concepts/consistency.md) require up to three hours to become encryptable.

{% endnote %}

{% list tabs group=instructions %}

- CLI {#cli}

  This command will encrypt the plain text provided in `--plaintext-file` and write the resulting ciphertext to `--ciphertext-file`:

  * `--id`: ID of the [KMS key](../concepts/key.md). Make sure you set either the `--id` or `--name` flag.
  * `--name`: Name of the KMS key. Make sure you set either the `--id` or `--name` flag.
  * `--version-id` (optional): [Version](../concepts/version.md) of the KMS key to use for encryption. The primary version is used by default.
  * `--plaintext-file`: Input plaintext file.
  * `--aad-context-file` (optional): Input file with [AAD context](../concepts/symmetric-encryption.md#add-context).
  * `--ciphertext-file`: Output file with ciphertext.

  ```bash
  yc kms symmetric-crypto encrypt \
    --id abj76v82fics******** \
    --plaintext-file plaintext-file \
    --ciphertext-file ciphertext-file
  ```

- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.
  
  Terraform is distributed under the [Business Source License](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method.

  To encrypt data:
  
  1. In the configuration file, describe the parameters of the `yandex_kms_secret_ciphertext` resource and specify the [KMS key](../concepts/key.md) in the `key_id` field:
  
     ```hcl
     resource "yandex_kms_secret_ciphertext" "password" {
       key_id      = "<key_ID>"
       aad_context = "additional authenticated data"
       plaintext   = "strong password"
     }
     ```
  
     Where:
  
     * `key_id`: KMS key ID.
     * `aad_context`: [AAD context](../concepts/symmetric-encryption.md#add-context).
     * `plaintext`: String to encrypt.
  
     {% note warning %}
  
     With `yandex_kms_secret_ciphertext`, you can hide secrets when deploying an infrastructure, but generally speaking it is unsafe to specify `plaintext` and `aad_context` in the configuration file in plain text. Secrets can be read from configuration files or execution logs and can end up in the Terraform state.
  
     {% endnote %}
  
     For more information about resource properties in Terraform, see [this provider guide](../../terraform/resources/kms_secret_ciphertext.md).
  
  1. Validate your configuration using this command:
  
     ```
     terraform validate
     ```
  
     If the configuration is valid, you will get this message:
  
     ```
     Success! The configuration is valid.
     ```
  
  1. Run this command:
  
     ```
     terraform plan
     ```
  
     You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
  
  1. Apply the configuration changes:
  
     ```
     terraform apply
     ```
  
  1. Type `yes` and press **Enter** to confirm the changes.
  
     After this, you can access the ciphertext through the `ciphertext` variable, and the encrypted data, through `plaintext`.
  
  
     For verification, you can add the following code with the `decrypted_pass` output variable to the configuration file.
  
     {% note alert %}
  
     This is not safe and can only be used for testing.
  
     {% endnote %}
  
     ```hcl
     output "decrypted_pass" {
       sensitive = true
       value     = yandex_kms_secret_ciphertext.password.plaintext
     }
     ```
  
     After updating the configuration, you can check the encrypted data using the command:
  
     ```hcl
     terraform output decrypted_pass
     ```
  
     Result:
  
     ```
     "strong password"
     ```
  
     {% endnote %}

- API {#api}

  To encrypt data, use the [encrypt](../api-ref/SymmetricCrypto/encrypt.md) REST API method for the [SymmetricCrypto](../api-ref/SymmetricCrypto/index.md) resource or the [SymmetricCryptoService/Encrypt](../api-ref/grpc/SymmetricCrypto/encrypt.md) gRPC API call.

- Yandex Cloud SDK {#sdk-yc}

  For information about how to encrypt and decrypt data using the Yandex Cloud SDK, see [Encrypting data using the Yandex Cloud SDK](../tutorials/encrypt/sdk.md).

- AWS Encryption SDK {#sdk-aws}

  For information about how to encrypt and decrypt data using the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html), see [Encrypting data using the AWS Encryption SDK](../tutorials/encrypt/aws-encryption-sdk.md).

- Google Tink {#google-tink}

  For information about how to encrypt and decrypt data using [Google Tink](https://github.com/google/tink), see [Encrypting data using Google Tink](../tutorials/encrypt/google-tink.md).

{% endlist %}

## Decrypt data {#decryption}

{% note info %}

Changes caused by [eventually consistent operations](../concepts/consistency.md) require up to three hours to become decryptable.

{% endnote %}

{% list tabs group=instructions %}

- CLI {#cli}

  This command will decrypt the ciphertext provided in `--ciphertext-file` and write the resulting plain text to `--plaintext-file`:

  * `--id`: ID of the [KMS key](../concepts/key.md). Make sure you set either the `--id` or `--name` flag.
  * `--name`: Name of the KMS key. Make sure you set either the `--id` or `--name` flag.
  * `--ciphertext-file`: Input file with ciphertext.
  * `--aad-context-file` (optional): Input file with [AAD context](../concepts/symmetric-encryption.md#add-context).
  * `--plaintext-file`: Output plaintext file.

  ```bash
  yc kms symmetric-crypto decrypt \
    --id abj76v82fics******** \
    --ciphertext-file ciphertext-file \
    --plaintext-file decrypted-file
  ```

- API {#api}

  To decrypt data, use the [decrypt](../api-ref/SymmetricCrypto/decrypt.md) REST API method for the [SymmetricCrypto](../api-ref/SymmetricCrypto/index.md) resource or the [SymmetricCryptoService/Decrypt](../api-ref/grpc/SymmetricCrypto/decrypt.md) gRPC API call.

- Yandex Cloud SDK {#sdk-yc}

  For information about how to encrypt and decrypt data using the Yandex Cloud SDK, see [Encrypting data using the Yandex Cloud SDK](../tutorials/encrypt/sdk.md).

- AWS Encryption SDK {#sdk-aws}

  For information about how to encrypt and decrypt data using the [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html), see [Encrypting data using the AWS Encryption SDK](../tutorials/encrypt/aws-encryption-sdk.md).

- Google Tink {#google-tink}

  For information about how to encrypt and decrypt data using [Google Tink](https://github.com/google/tink), see [Encrypting data using Google Tink](../tutorials/encrypt/google-tink.md).

{% endlist %}

## Change the data encryption key {#reencryption}

{% note info %}

Changes triggered by [eventually consistent operations](../concepts/consistency.md) allow an encryption key change after as much as three hours.

{% endnote %}

{% list tabs group=instructions %}

- CLI {#cli}

  This command will decrypt the ciphertext from `--source-ciphertext-file`, re-encrypt it with a different key or a different version of the source key, and then write the resulting ciphertext to `--ciphertext-file`.

  * `--id` or `--name`: ID or name of the new [KMS key](../concepts/key.md) for re-encryption.

    {% note info %}

    * To use a different key, specify the `--id` or `--name` flag.

    * To only change the key version, skip both `--id` and `--name`.

    {% endnote %}

  * `--version-id` (optional): [Version](../concepts/version.md) of the KMS key to use for encryption. The primary version is used by default.
  * `--aad-context-file` (optional): Output file with [AAD context](../concepts/symmetric-encryption.md#add-context).
  * `--ciphertext-file`: Output file with ciphertext.
  * `--source-key-id`: ID of the Key Management Service encryption key used for source text encryption.
  * `--source-aad-context-file` (optional): Input file with AAD context.
  * `--source-ciphertext-file`: Input file with ciphertext.

  ```bash
  yc kms symmetric-crypto reencrypt \
    --id <key_ID> \
    --ciphertext-file ciphertext-file
    --source-key-id <source_key_ID> \
    --source-ciphertext-file source-ciphertext-file
  ```

- API {#api}

  To change the data encryption key or its version, use the [reEncrypt](../api-ref/SymmetricCrypto/reEncrypt.md) REST API method for the [SymmetricCrypto](../api-ref/SymmetricCrypto/index.md) resource or the [SymmetricCryptoService/ReEncrypt](../api-ref/grpc/SymmetricCrypto/reEncrypt.md) gRPC API call.

{% endlist %}

#### Useful links {#see-also}

* [Command line interface CLI](../../cli/index.md)
* [Symmetric encryption in Yandex Key Management Service](../concepts/symmetric-encryption.md)
* [Asymmetric encryption in Yandex Key Management Service](../concepts/asymmetric-encryption.md)
* [Managing keys in KMS](index.md)
* [Encrypting secrets in Hashicorp Terraform](../tutorials/terraform-secret.md)