gcloud-kms-decrypt

--location
    The Google Cloud region or global endpoint where the KMS key is located.

--keyring
    The name of the key ring that contains the cryptographic key.

--key
    The name of the cryptographic key to use for decryption.

--ciphertext-file
    Path to the input file containing the data to be decrypted.

--plaintext-file
    Path to the output file where the decrypted data will be written.

--version
    (optional) The specific version of the cryptographic key to use. If not specified, the primary (latest) version is used.

--additional-authenticated-data
    (optional) Additional authenticated data (AAD) that was provided during encryption. This data is not encrypted but must be provided during decryption to ensure integrity.

--project
    (optional) The Google Cloud project ID to which the key belongs, if different from the currently configured project.

gcloud-kms-decrypt is a command-line tool designed to decrypt data using the Google Cloud Key Management Service (KMS). It leverages the robust cryptographic capabilities of Google Cloud to securely unlock previously encrypted sensitive information.

This command typically takes a file containing ciphertext, a reference to a specific KMS cryptographic key, and outputs the decrypted plaintext to another specified file. It abstracts away the underlying API calls, providing a convenient interface for developers and operations teams to manage encrypted data within their workflows.

KMS provides a centralized, cloud-hosted key management service for creating, storing, and managing cryptographic keys. Using gcloud-kms-decrypt ensures that decryption operations are performed in a controlled environment, often requiring appropriate Identity and Access Management (IAM) permissions, thus enhancing data security and compliance. It's an essential tool for applications that encrypt data at rest or in transit and need a secure method for retrieval.

Requires the gcloud CLI to be installed and properly configured with authenticated access to Google Cloud.
The user or service account executing the command must possess the necessary IAM permissions on the KMS key (e.g., cloudkms.cryptoKeyDecrypter).
Network connectivity to Google Cloud services is essential for the command to function.
Decryption will fail if the provided key is incorrect, if the additional-authenticated-data (if used during encryption) does not match, or if the ciphertext has been tampered with.
The exact behavior and available options might vary slightly if gcloud-kms-decrypt is a custom wrapper script rather than a direct alias to gcloud kms decrypt.

Instead of --location, --keyring, and --key, some gcloud commands or wrapper scripts might accept a full KMS key resource path directly, in the format projects/<project_id>/locations/<location>/keyRings/<key_ring_name>/cryptoKeys/<key_name>. This provides a concise way to specify the key.

For successful decryption, the principal (user account, service account, or group) executing gcloud-kms-decrypt must have the cloudkms.cryptoKeyDecrypter role granted on the specific KMS key or its parent resources (key ring, project). This role allows the principal to use the key for decryption operations.

The command is designed to work with file-based input and output. For small pieces of data, base64 encoding/decoding might be necessary if the ciphertext is provided directly on the command line or via standard input, as gcloud kms encrypt typically outputs base64-encoded ciphertext.

Google Cloud Key Management Service (KMS) was officially launched in 2017, providing a managed service for cryptographic keys. The gcloud CLI has since evolved to include comprehensive support for KMS operations, allowing users to manage keys and perform encryption/decryption operations directly from the command line. The gcloud kms decrypt functionality, which gcloud-kms-decrypt likely wraps or mirrors, has been a core component of this offering, enabling secure data handling in cloud environments.

gcloud(1), gcloud kms(1), gcloud kms encrypt(1)