Encrypt and decrypt data

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.

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 Organization IAM Admin to request the KMS Developer (kms-developer) role in your project namespace.

Prepare your environment

Required permissions

To get the permissions you need, ask your Organization IAM Admin to grant you the KMS Developer (kms-developer) role in your project.

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:

    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:

    • NAMESPACE: the project namespace—for example: kms-test1.
    • KEY_NAME: the name of the key used to encrypt the plaintext—for example: key-1.
    • PLAINTEXT_PATH: the path to the file that contains the plaintext to encrypt.
    • ADDITIONAL_AUTHENTICATED_DATA_FILE: 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.
    • CIPHERTEXT_PATH: 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:

    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:

    • NAMESPACE: the project namespace.
    • KEY_NAME: the name of the key used to encrypt the plaintext.
    • CIPHERTEXT_PATH: the path of the file you want to decrypt.
    • ADDITIONAL_AUTHENTICATED_DATA_FILE: 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.
    • PLAINTEXT_PATH: 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.