Import and export keys

This page covers instructions for the Application Operator (AO) to perform key import operations from exported key management systems (KMS) keys. The AO performs the import and export operations using the kubectl command line interface (CLI) from the following resources:

To view more details on these resources, see the KMS API overview.

Refer to the Supported keys section in the Key management systems (KMS) page to view the full list and details of KMS supported keys.

Before you begin

Before continuing, ensure you have the following:

The kubectl command configured to access the Management API server. To do this, follow the sections Get a kubeconfig file and gdcloud command-line interface (CLI).
The KMS Key Import Admin and KMS Key Export Admin roles. To get the permissions that you need to import an exported key, ask your Platform Administrator (PA) to grant you the KMS Key Import Admin (kms-keyimport-admin) and the KMS Key Export Admin (kms-keyexport-admin) roles.

Import an exported key

To import an exported key, complete the following steps:

Create a YAML file, and add in the KeyImport resource as the value of the kind object:
```
apiVersion: "kms.gdc.goog/v1"
kind: KeyImport
metadata:
  name: KEY_IMPORT_NAME
  namespace: PROJECT
spec:
  context:
    mechanism: MECHANISM
```
Replace the following variables:
- KEY_IMPORT_NAME: the name of the KeyImport resource — for example: key-import-test.
- PROJECT: the name of the project namespace — for example: kms-test1.
- MECHANISM: the key sharing mechanism of the key — for example: `EDCH_P521_AES256` .
Apply the contents of the YAML file to the KMS and create the KeyImport resource:
```
kubectl apply -f FILENAME.yaml
```
Replace FILENAME 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.

To view the status of KeyImport resource and obtain the KMS generated public key, run the following:

kubectl describe keyimport KEY_IMPORT_NAME --namespace PROJECT

Replace the following variables:

KEY_IMPORT_NAME: the KeyImport resource name — for example, key-import-test.
PROJECT: 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 PUBLIC_KEY represents the KMS generated public key. Copy the public key, and add it to the KeyExport resource in the following step.

Create another YAML file, add in the KeyExport resource as the value of the kind object, and the following contents:
```
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:
- KEY_EXPORT_NAME: the name of the KeyExport resource — for example: key-export-test.
- PROJECT: the name of the project namespace — for example: kms-test1.
  
  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.
- MECHANISM: the key sharing mechanism of the key — for example: `EDCH_P521_AES256` .
- PUBLIC_KEY: the public key from keyImport.Status.PeerContext.PublicKey.
- KEY_PRIMITIVE: the CRD of the key—for example, aeadkey and signingkey.
- KEY_NAME: the name of the key—for example, key-1.
Apply the contents of the YAML file to the KMS and create the KeyExport resource:
```
kubectl apply -f FILENAME.yaml
```
Replace FILENAME 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.
To view the resource's status, run the following:
```
kubectl describe keyexport KEY_EXPORT_NAME --namespace PROJECT
```
Replace the following variables:
- KEY_EXPORT_NAME: the name of the KeyExport resource — for example, key-export-test.
- PROJECT: 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
```
EXPORTED_KEY represents the metadata of the exported key. Copy the contents in EXPORTED_KEY to continue to the following step.

Edit the YAML file that contains the KeyImport resource, and add in the contents you copied from the output in keyexport.status.exportedkey.

apiVersion: "kms.gdc.goog/v1"
kind: KeyImport
metadata:
  name: key-import-test
  namespace: kms-test1
spec:
  context:
    mechanism: EDCH_P521_AES256
  keyToImport: EXPORTED_KEY

After editing the YAML file, apply the contents to the KMS:
```
kubectl apply -f FILENAME.yaml
```
After running the command, the KMS imports the exported key you provided.

To view details on the imported key, run the following:

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

KEY_PRIMITIVE represents the kind of key you imported, between the AEAD and Signing keys.