This document shows you how to import and export Key Management System (KMS)
keys. These operations use the `kubectl` command line interface (CLI) and
interact with the following Kubernetes resources:

- [`KeyImport`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/service/kms/kms-api-overview.md.txt#keyimport)
- [`KeyExport`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/service/kms/kms-api-overview.md.txt#keyexport)

To view more details on these resources, see the
[KMS API overview](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/kms-api-overview).

Refer to the [Supported keys](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/kms/kms.md.txt#supported-keys) section in the Key
management system document to view the full list and details of KMS supported
keys.

This document is for audiences within the application operator group when
performing key management operations within Google Distributed Cloud (GDC) air-gapped. 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 importing or exporting keys, you must have the necessary permissions and
prepare your environment.

### Request IAM roles

Contact your IAM Org Admin to request the following roles in your
project:

- **KMS Key Import Admin** (`kms-keyimport-admin`): create, update, and delete `KeyImport` resources.
- **KMS Key Export Admin** (`kms-keyexport-admin`): create, update, and delete `KeyExport` resources.

### 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.

- [Install the kubectl CLI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/get-started/kubectl.md.txt).

- [Generate a kubeconfig file](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/gdcloud-auth.md.txt#get-kubeconfig)
  to configure `kubectl` access.

## Import an exported key

To import an exported key, complete the following steps:

1. Create a YAML file, and add in the `KeyImport` resource as the value of the
   `kind` object:

   ```yaml
   apiVersion: "kms.gdc.goog/v1"
   kind: KeyImport
   metadata:
     name: KEY_IMPORT_NAME
     namespace: PROJECT
   spec:
     context:
       mechanism: MECHANISM
   ```

   Replace the following variables:
   - <var translate="no">KEY_IMPORT_NAME</var>: the name of the `KeyImport` resource --- for example: `key-import-test`.
   - <var translate="no">PROJECT</var>: the name of the project namespace --- for example: `kms-test1`.
   - <var translate="no">MECHANISM</var>: the key sharing mechanism of the key --- for example: \`EDCH_P521_AES256\` .
2. Apply the contents of the YAML file to the KMS and create the `KeyImport`
   resource:

   ```bash
   kubectl apply -f FILENAME.yaml
   ```

   Replace <var translate="no">FILENAME</var> with the name of the YAML file.

   With the public key of an internally generated key pair, the KMS updates
   the status of the `KeyImport` resource to `AwaitingKeyToImport`. To
   continue, you need to view the status of the resource and obtain the KMS
   generated public key.
3. To view the status of `KeyImport` resource and obtain the KMS generated
   public key, run the following:

   ```bash
   kubectl describe keyimport KEY_IMPORT_NAME --namespace PROJECT
   ```

   Replace the following variables:
   - <var translate="no">KEY_IMPORT_NAME</var>: the `KeyImport` resource name --- for example, `key-import-test`.
   - <var translate="no">PROJECT</var>: the name of the project namespace --- for example: `kms-test1`.

   After running the command, you see output similar to the following:

       ...
       Status:
         Conditions:
           Last Transition Time:  2022-12-14T20:43:50Z
           Message:               waiting for user to provide KeyToImport
           Observed Generation:   1
           Reason:                AwaitingKeyToImport
           Status:                False
           Type:                  Ready
         Imported Key Ref:
           Kind: KeyImport
           Name: key-import-test
         Peer Context:
           Private Key:
           Public Key: PUBLIC_KEY
       Events:           <none>

   The value <var translate="no">PUBLIC_KEY</var> represents the KMS generated public
   key. Copy the public key, and add it to the `KeyExport` resource in the
   following step.
4. Create another YAML file, add in the `KeyExport` resource as the value of
   the `kind` object, and the following contents:

   ```yaml
   apiVersion: "kms.gdc.goog/v1"
   kind: KeyExport
   metadata:
     name: KEY_EXPORT_NAME
     namespace: PROJECT
   spec:
     context:
       mechanism: MECHANISM
       publicKey: PUBLIC_KEY
     keyToExport:
       kind: KEY_PRIMITIVE
       name: KEY_NAME
   ```

   Replace the following variables:
   - <var translate="no">KEY_EXPORT_NAME</var>: the name of the `KeyExport` resource --- for example: `key-export-test`.
   - <var translate="no">PROJECT</var>: the name of the project namespace --- for
     example: `kms-test1`.

     > [!IMPORTANT]
     > **Important:** The `KeyExport` custom resource definition (CRD) must reside in the same project namespace of the imported key. If the imported key resides in the project namespace `kms-test1`, the `KeyExport` CRD must also reside in the same project namespace.

   - <var translate="no">MECHANISM</var>: the key sharing mechanism of the key ---
     for example: \`EDCH_P521_AES256\` .

   - <var translate="no">PUBLIC_KEY</var>: the public key from
     `keyImport.Status.PeerContext.PublicKey`.

   - <var translate="no">KEY_PRIMITIVE</var>: the CRD of the key---for example,
     aeadkey and signingkey.

   - <var translate="no">KEY_NAME</var>: the name of the key---for example, `key-1`.

5. Apply the contents of the YAML file to the KMS and create the `KeyExport`
   resource:

   ```bash
   kubectl apply -f FILENAME.yaml
   ```

   Replace <var translate="no">FILENAME</var> with the name of the YAML file.

   After running the command, the KMS updates the status of the `KeyExport`
   resource and generates an exported key. To obtain the exported key, view
   the resource's status.
6. To view the resource's status, run the following:

   ```bash
   kubectl describe keyexport KEY_EXPORT_NAME --namespace PROJECT
   ```

   Replace the following variables:
   - <var translate="no">KEY_EXPORT_NAME</var>: the name of the `KeyExport` resource --- for example, `key-export-test`.
   - <var translate="no">PROJECT</var>: the name of the project namespace---for example: `kms-test1`.

   After running the command, you see an output similar to the following:

       ...
       Status:
       Conditions:
       Last Transition Time:  2022-12-14T20:45:57Z
       Message:               key successfully exported
       Observed Generation:   1
       Reason:                KeyExportCompleted
       Status:                True
       Type:                  Ready
       Exported Key: EXPORTED_KEY

   <var translate="no">EXPORTED_KEY</var> represents the metadata of the exported key.
   Copy the contents in <var translate="no">EXPORTED_KEY</var> to continue to the
   following step.
7. Edit the YAML file that contains the `KeyImport` resource, and add in the
   contents you copied from the output in `keyexport.status.exportedkey`.

   ```yaml
   apiVersion: "kms.gdc.goog/v1"
   kind: KeyImport
   metadata:
     name: key-import-test
     namespace: kms-test1
   spec:
     context:
       mechanism: EDCH_P521_AES256
     keyToImport: EXPORTED_KEY
   ```
8. After editing the YAML file, apply the contents to the KMS:

   ```bash
   kubectl apply -f FILENAME.yaml
   ```

   After running the command, the KMS imports the exported key you provided.
9. To view details on the imported key, run the following:

   ```bash
   kubectl get keyimport KEY_IMPORT_NAME
   ```

   You see output similar to the following:

       NAMESPACE   NAME             AGE    READY   REASON              KEY KIND
       kms-test1  KEY_IMPORT_NAME   60s    True    KeyImportCompleted  KEY_PRIMITIVE

   <var translate="no">KEY_PRIMITIVE</var> represents the kind of key you
   imported, between the AEAD and Signing keys.