This document describes how to encrypt and decrypt data using Key Management
System (KMS) keys with the gdcloud CLI.

This document is for audiences within the application operator group who need
to perform cryptographic operations within GDC projects.
For more information, see
[Audiences for GDC air-gapped documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences.md.txt).

## Before you begin

Before encrypting or decrypting data, you must have the necessary permissions
and prepare your environment.

### Request IAM roles

To encrypt and decrypt data, contact your IAM Org Admin to request the
**KMS Developer** (`kms-developer`) role in your project namespace.

### Prepare your environment

- [Download](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-download.md.txt) and
  [install](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-install.md.txt) the gdcloud CLI,
  if you haven't already done so.

- [Sign in to the gdcloud CLI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/iam/sign-in.md.txt#cli).

## Encrypt data

To encrypt data, use the `gdcloud kms keys encrypt` command. This command encrypts a
given plaintext file using the `AEAD` key, and writes it to a named ciphertext
file.

- To encrypt data, pass in the key name and the following:

  ```bash
  gdcloud kms keys encrypt namespaces/NAMESPACE/aeadKeys/KEY_NAME \
    --plaintext-file=PLAINTEXT_PATH \
    --additional-authenticated-data-file=ADDITIONAL_AUTHENTICATED_DATA_FILE \
    --ciphertext-file=CIPHERTEXT_PATH
  ```

  Replace the following variables:
  - <var translate="no">NAMESPACE</var>: the project namespace---for example: `kms-test1`.
  - <var translate="no">KEY_NAME</var>: the name of the key used to encrypt the plaintext---for example: `key-1`.
  - <var translate="no">PLAINTEXT_PATH</var>: the path to the file that contains the plaintext to encrypt.
  - <var translate="no">ADDITIONAL_AUTHENTICATED_DATA_FILE</var>: an optional file that contains additional authenticated data (AAD). AAD is used for integrity checks and protects your data from a confused deputy attack. AAD and the plaintext each have a size limit of 64KB.
  - <var translate="no">CIPHERTEXT_PATH</var>: the path to the file that contains the encrypted plaintext.

  After running the command, you see a file you specified in the
  `--ciphertext-file` flag that contains the encrypted contents of the plaintext
  file.

## Decrypt data

To decrypt data, use the `gdcloud kms keys decrypt` command. This command decrypts a
given ciphertext file using the `AEAD` key, and writes it to a named plaintext
file.

- To decrypt ciphertext, pass in the key name and the following:

  ```bash
  gdcloud kms keys decrypt namespaces/NAMESPACE/aeadKeys/KEY_NAME \
   --ciphertext-file=CIPHERTEXT_PATH \
   --additional-authenticated-data-file=ADDITIONAL_AUTHENTICATED_DATA_FILE \
   --plaintext-file=PLAINTEXT_PATH
  ```

  Replace the following variables:
  - <var translate="no">NAMESPACE</var>: the project namespace.
  - <var translate="no">KEY_NAME</var>: the name of the key used to encrypt the plaintext.
  - <var translate="no">CIPHERTEXT_PATH</var>: the path of the file you want to decrypt.
  - <var translate="no">ADDITIONAL_AUTHENTICATED_DATA_FILE</var>: an optional file that contains additional authenticated data (AAD). AAD is used for integrity checks and protects your data from a confused deputy attack. AAD and the plaintext each have a size limit of 64KB.

    > [!NOTE]
    > **Note**: You must use the same AAD you passed during the encrypt operation for the decrypt operation.

  - <var translate="no">PLAINTEXT_PATH</var>: the path to the file that contains the decrypted plaintext.

  After running the command, you see a file you specified in the
  `--plaintext-file` flag that contains the decrypted data.