kms - Configure Cloud KMS encryption

Synopsis

gsutil kms authorize [-p <proj_id>] -k <kms_key>
gsutil kms encryption [(-d|[-k <kms_key>])] [-w] gs://<bucket_name>...
gsutil kms serviceaccount [-p <proj_id>]

Description

The kms command is used to configure Cloud Storage and Cloud KMS resources to support encryption of Cloud Storage objects with Cloud KMS keys.

The kms command has three sub-commands that deal with configuring Cloud Storage 's integration with Cloud KMS: authorize, encryption, and serviceaccount.

Before using this command, read the prerequisites. for using Cloud KMS with Cloud Storage.

Authorize

The authorize sub-command checks that the default (or supplied) project has a Cloud Storage service agent created for it, and if not, it creates one. It then adds appropriate encrypt/decrypt permissions to Cloud KMS resources such that the service agent can write and read Cloud KMS-encrypted objects in buckets associated with the service agent's project.

Authorize Examples

Authorize "my-project" to use a Cloud KMS key:

gsutil kms authorize -p my-project \
    -k projects/key-project/locations/us-east1/keyRings/key-ring/cryptoKeys/my-key

Authorize Options

-k <key>

The path to the KMS key to use. The path has the following form: projects/[project-id]/locations/[location]/keyRings/[key-ring]/cryptoKeys/[my-key]

-p <project>

The ID or number of the project being authorized to use the Cloud KMS key. If this flag is not included, your default project is authorized.

Encryption

The encryption sub-command is used to set, display, or clear a bucket's default KMS key, which is used to encrypt newly-written objects if no other key is specified.

Encryption Examples

Set the default KMS key for my-bucket:

gsutil kms encryption \
    -k projects/key-project/locations/us-east1/keyRings/key-ring/cryptoKeys/my-key \
    gs://my-bucket

Show the default KMS key for my-bucket, if one is set:

gsutil kms encryption gs://my-bucket

Clear the default KMS key so newly-written objects are not encrypted using it:

gsutil kms encryption -d gs://my-bucket

Once you clear the default KMS key, newly-written objects are encrypted with Google-managed encryption keys by default.

Encryption Options

-k <key>

Set the default KMS key for my-bucket using the full path to the key, which has the following form: projects/[project-id]/locations/[location]/keyRings/[key-ring]/cryptoKeys/[my-key]

-w

(used with -k key) Display a warning rather than failing if gsutil is unable to verify that the specified key contains the correct IAM bindings for encryption/decryption. This is useful for users that do not have getIamPolicy permission but know that the key has the correct IAM policy for encryption in the user's project.

-d

Clear the default KMS key.

Serviceaccount

The serviceaccount sub-command displays the Cloud Storage service agent that is used to perform Cloud KMS operations against your default project (or a supplied project).

Serviceaccount Examples

Show the service account for my-project:

gsutil kms serviceaccount -p my-project

Serviceaccount Options

-p <project>

The ID or number of the project whose Cloud Storage service agent is being requested. If this flag is not included, your default project is used.