# Create encryption keys with Cloud KMS

This quickstart shows you how to create and use encryption keys with
Cloud Key Management Service in a project you own. These instructions use the
Google Cloud console to create key rings, keys, and key versions in
Cloud KMS. For instructions that use other methods,
see [Autokey overview](https://docs.cloud.google.com/kms/docs/autokey-overview.md.txt), [Create a key
ring](https://docs.cloud.google.com/kms/docs/create-key-ring), and [Create a key](https://docs.cloud.google.com/kms/docs/create-key.md.txt).

This quickstart uses the command line to send requests to the
Cloud KMS API. For programming examples that use the client
libraries to send requests to the Cloud KMS API, see [Encrypting
and Decrypting](https://docs.cloud.google.com/kms/docs/encrypt-decrypt).

## Before you begin

<br />

> [!NOTE]
> **Note:** This quickstart creates Cloud KMS resources such as key rings and keys. Key rings and keys can't be renamed after they're created, and you can't reuse the names of deleted keys.

## Key rings and keys

To encrypt and decrypt content you will need a Cloud KMS key, which
is part of a key ring.

Create a key ring named `test`, and a key named `quickstart`. Refer to the
[object hierarchy overview](https://docs.cloud.google.com/kms/docs/object-hierarchy) for more
information about these objects and how they are related.

```bash
gcloud kms keyrings create "test" \
    --location "global"
```

```bash
gcloud kms keys create "quickstart" \
    --location "global" \
    --keyring "test" \
    --purpose "encryption"
```

You can use the `list` option to view the name and metadata for the key that you
just created.

```bash
gcloud kms keys list \
    --location "global" \
    --keyring "test"
```

You should see:

```
NAME                                                                      PURPOSE          PRIMARY_STATE
projects/PROJECT_ID/locations/global/keyRings/test/cryptoKeys/quickstart  ENCRYPT_DECRYPT  ENABLED
```

## Encrypt data

Now that you have a key, you can use that key to encrypt text or binary
content.

Store some text to be encrypted in a file called "mysecret.txt".

```bash
echo -n "Some text to be encrypted" > mysecret.txt
```

To encrypt the data with `gcloud kms encrypt`, provide your key information,
specify the name of the plaintext file to encrypt, and specify the name of the
file that will contain the encrypted content:

```bash
gcloud kms encrypt \
    --location "global" \
    --keyring "test" \
    --key "quickstart" \
    --plaintext-file ./mysecret.txt \
    --ciphertext-file ./mysecret.txt.encrypted
```

The `encrypt` method saves your encrypted content in the file specified by the
`--ciphertext-file` flag.

## Decrypt ciphertext

To decrypt the data with `gcloud kms decrypt`, provide your key information,
specify the name of the encrypted file (ciphertext file) to decrypt, and specify
the name of the file that will contain the decrypted content:

```bash
gcloud kms decrypt \
    --location "global" \
    --keyring "test" \
    --key "quickstart" \
    --ciphertext-file ./mysecret.txt.encrypted \
    --plaintext-file ./mysecret.txt.decrypted
```

The `decrypt` method saves your decrypted content in the file specified by the
`--plaintext-file` flag.

To decrypt encrypted content, you must use the same key that was
used to encrypt the content.

## Clean up


To avoid incurring charges to your Google Cloud account for
the resources used on this page, delete the Google Cloud project with the
resources.

List the versions available for your key:

```bash
gcloud kms keys versions list \
    --location "global" \
    --keyring "test" \
    --key "quickstart"
```

To destroy a version, run the following command, where `1` is the number
of the key version that you want to destroy:

> [!IMPORTANT]
> **Important:** When you destroy a key version, you can no longer decrypt content that was encrypted using that version of the key. Make sure that you no longer need a key version before you destroy it.

```
gcloud kms keys versions destroy 1 \
    --location "global" \
    --keyring "test" \
    --key "quickstart"
```

## What's next

- Start [using the API](https://docs.cloud.google.com/kms/docs/accessing-the-api.md.txt).
- Take a look at the [API Reference](https://docs.cloud.google.com/kms/docs/reference/rest.md.txt).
- Learn more about how to [encrypt data at
  rest](https://codelabs.developers.google.com/codelabs/encrypt-and-decrypt-data-with-cloud-kms).