Importing Keys and Key Versions

Note

Before the introduction of secrets as a resource, Oracle Cloud Infrastructure Vault was known as Oracle Cloud Infrastructure Key Management.

When you create a key or key version protected by a hardware security module (HSM), you can import your own key material instead of leaving the Vault service responsible for generating the key material internally. (At this time, you cannot import key material to create a key or key version protected by software.) You might want to "bring your own key" (BYOK) if you need more control over the source of the key material or if you want to use the same keys that you already use for encryption purposes on-premises.

Keys must be AES symmetric keys and the key length must match what you specify at the time you create a key or import a key. The Vault service supports keys that are exactly 16 bytes (or 128 bits), 24 bytes (or 192 bits), or 32 bytes (or 256 bits). The key material must be wrapped by using the public wrapping key provided with each vault before you can import it. If you plan to use the command line interface (CLI) to create a new external key or external key version, the key material must also be base64-encoded. The wrapping key pair make it possible for the HSM to unwrap and store the key securely.

Required IAM Policy

Caution

Keys associated with volumes, buckets, file systems, clusters, and stream pools will not work unless you authorize Block Volume, Object Storage, File Storage, Container Engine for Kubernetes, and Streaming to use keys on your behalf. Additionally, you must also authorize users to delegate key usage to these services in the first place. For more information, see Let a user group delegate key usage in a compartment and Let Block Volume, Object Storage, File Storage, Container Engine for Kubernetes, and Streaming services encrypt and decrypt volumes, volume backups, buckets, file systems, Kubernetes secrets, and stream pools in Common Policies.

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  you should work in.

For administrators: for typical policies that give access to vaults, keys, and secrets, see Let security admins manage vaults, keys, and secrets. For more information about permissions or if you need to write more restrictive policies, see Details for the Vault Service.

If you're new to policies, see Getting Started with Policies and Common Policies.

Before You Begin

To bring your own key, you must first generate an AES key and then transform the key material by wrapping it. The process by which you transform the key material is called Optimal Asymmetric Encryption Padding (OAEP). OAEP is commonly used with the RSA encryption algorithm (RSA-OAEP). The Vault service supports RSA-OAEP with a SHA-256 hash. Applying RSA-OAEP to wrap the plaintext provides an additional layer of protection to the key material by making it possible for only the HSM in possession of the private RSA wrapping key to unwrap the key.

You can either import the key or key version by using the Console or the CLI. If you use the CLI, we've included an example script that you can refer to that includes all steps of the import process, including generating key material, wrapping the key material, and importing the key or key version. (If you want to use the Console or the CLI to create a key or key version with imported key material, you must separately apply RSA-OAEP first to wrap the key. With the CLI, you must also base64 encode the wrapped key material before you import it.)

If you're using MacOS or Linux, you'll need to install the OpenSSL 1.1.1 series to run commands. If you're using Windows, you'll need to install Git Bash for Windows and run commands with that tool.

Using the Console

The following procedures assume that you already generated key material by using the third-party tool of your choice. Once you have the key material, use the Console to get the public wrapping key that you'll need to wrap the key material. Wrap the key material, and then use the Console to import it as a new master encryption key or a new key version for an existing master encryption key.

To get the public RSA wrapping key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault in which you want to create the new master encryption key or key version.
  3. From the list of vaults in the compartment, click the name of the vault.
  4. In Vault Information, click Public Wrapping Key, and then click Copy.

Save the copied wrapping key, and then continue to To apply RSA-OAEP to wrap the key material.

To apply RSA-OAEP to wrap the key material

Open a command prompt and run the following command to wrap the AES key material with the public RSA wrapping key associated with the vault. Replace example file names and values as appropriate.

openssl pkeyutl -encrypt -in <AES_key_material> -inkey <public_RSA_wrapping_key> -pubin -out <wrapped_AES_key> -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

For example:


openssl pkeyutl -encrypt -in "aes_key.bin" -inkey "publickey.pem" -pubin -out "wrappedkey.bin" -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

After you wrap the key, you can then either import the key material by creating a new key or by rotating a key to a new key version.

To import the key material as a new external key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to create a key.
  3. From the list of vaults in the compartment, do one of the following:

    • Click the name of the vault where you want to import key material for a new key.

    • Create a new vault for the key by following the instructions in To create a new vault, and then click the name of the vault.

  4. Click Master Encryption Keys, and then click Create Key.
  5. In the Create Key dialog box, choose a compartment from the Create in Compartment list. (Keys can exist outside the compartment the vault is in.)
  6. Click Protection Mode, and then click HSM. (At this time, you cannot import key material for keys protected by software.)
  7. Click Name, and then enter a name to identify the key. Avoid entering any confidential information in this field.
  8. Specify the key length, in bits, by choosing a length from the Key Shape: Length list.
  9. Select the Import External Key check box.
  10. Under External Key Data Source, provide the file that contains the wrapped AES key material.
  11. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you are not sure if you should apply tags, then skip this option (you can apply tags later) or ask your administrator.
  12. When you are finished, click Create Key.
To import the key material as a new external key version
Note

Key versions must match the shape of the key to which they're added.
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault with the key you want to rotate.
  3. From the list of vaults in the compartment, click the vault name.

  4. Click Master Encryption Keys, and then click the name of the master encryption key that you want to rotate to a new key version.
  5. Under Resources, click Versions, and then, in the list of keys, click Rotate Key. (You can only rotate keys in an enabled state.)
  6. In the Confirm dialog box, select the Import External Key Version check box.
  7. Under External Key Data Source, provide the file that contains the wrapped AES key material.
  8. When you're ready, click Rotate Key.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

Tip

Each vault has a unique endpoint for create, update, and list operations for keys. This endpoint is referred to as the control plane URL or management endpoint. Each vault also has a unique endpoint for cryptographic operations. This endpoint is known as the data plane URL or the cryptographic endpoint. When using the CLI for key operations, you must provide the appropriate endpoint for the type of operation. To retrieve a vault's endpoints, see instructions in To view vault configuration details.

This section provides an example script that you can use to fully automate generating the key material, applying RSA-OAEP to wrap the key material, and then creating the new key or key version based on the imported, wrapped key material.

Tip

We recommend that you provide complex input, such as JSON, by providing a file that contains the input, rather than formatting the input in the command line.

To create a new key, open a command prompt, and then run the following script, replacing example file names and values as appropriate:

#!/usr/bin/env bash

#
# This script is for demonstration purposes only. It provides
# a functioning set of calls to show how to import AES keys 
# into the Vault service.
#


set -x

OPENSSL="<path_to_OpenSSL>"
AES_KEY="<path_to_AES_key>"
WRAPPING_KEY="<path_to_RSA_wrapping_key>"
WRAPPED_KEY="<path_to_wrapped_AES_key>"

VAULT_KEYMANAGEMENT_ENDPOINT="<target_vault_keymanagement_endpoint>"
COMPARTMENT_ID="<target_compartment_ID>"
DISPLAY_NAME="<key_display_name>"
KEY_SIZE="<key_size_as_bytes>" # Specify 16 (for 128 bits), 24 (for 192 bits), or 32 (for 256 bits).

BASE64="base64"
if [[ $(uname -s) == "MINGW"* ]]
then
    BASE64="base64 -w0";
fi


#
# Generate an AES key.
#
# Use OpenSSL to generate an AES key of ${KEY_SIZE} bytes.
# You can use any source for your AES key.
#
${OPENSSL} rand ${KEY_SIZE} > ${AES_KEY}

#
# Ask the Vault service for the public wrapping key by using 
# the vault's key management endpoint.
# The public key is stored as ${WRAPPING_KEY}.
#
key_text=$(oci kms management wrapping-key get --endpoint $VAULT_KEYMANAGEMENT_ENDPOINT | grep public-key | cut -d: -f2  | sed 's# "\(.*\)",#\1#g')
echo -e $key_text > ${WRAPPING_KEY}

#
# Wrap the AES key by using RSA-OAEP with SHA-256.
#
${OPENSSL} pkeyutl -encrypt -in ${AES_KEY} -inkey ${WRAPPING_KEY} -pubin -out ${WRAPPED_KEY} -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256


#
# Import the wrapped key to the Vault service after base64 encoding the payload.
#
# The service will provide a JSON document containing key details.
#
key_material=$(${BASE64} ${WRAPPED_KEY})
echo "{ \"wrappingAlgorithm\": \"RSA_OAEP_SHA256\", \"keyMaterial\": \"${key_material}\" }" > wrapped_import_key.json
echo "{ \"algorithm\": \"AES\", \"length\": ${KEY_SIZE} }" > key_shape.json

oci kms management key import --wrapped-import-key file://./wrapped_import_key.json --compartment-id ${COMPARTMENT_ID} --display-name ${DISPLAY_NAME} --endpoint ${VAULT_KEYMANAGEMENT_ENDPOINT} --key-shape file://./key_shape.json

To create a new key version, open a command prompt, and then run the following script, replacing example file names and values as appropriate:

#!/usr/bin/env bash

#
# This script is for demonstration purposes only. It provides
# a functioning set of calls to show how to import AES keys 
# into the Vault service.
#


set -x

OPENSSL="<path_to_OpenSSL>"
AES_KEY="<path_to_AES_key>"
WRAPPING_KEY="<path_to_RSA_wrapping_key>"
WRAPPED_KEY="<path_to_wrapped_AES_key>"

KEY_ID="<key_OCID>"
KEY_SIZE="<key_size_as_bytes>"

BASE64="base64"
if [[ $(uname -s) == "MINGW"* ]]
then
    BASE64="base64 -w0";
fi


#
# Generate an AES key.
#
# Use OpenSSL to generate an AES key of ${KEY_SIZE} bytes.
# You can use any source for your AES key.
#
${OPENSSL} rand ${KEY_SIZE} > ${AES_KEY}

#
# Ask the Vault service for the public wrapping key by using 
# the vault's key management endpoint.
# The public key is stored as ${WRAPPING_KEY}.
#
key_text=$(oci kms management wrapping-key get --endpoint $VAULT_KEYMANAGEMENT_ENDPOINT | grep public-key | cut -d: -f2  | sed 's# "\(.*\)",#\1#g')
echo -e $key_text > ${WRAPPING_KEY}

#
# Wrap the AES key by using RSA-OAEP with SHA-256.
#
${OPENSSL} pkeyutl -encrypt -in ${AES_KEY} -inkey ${WRAPPING_KEY} -pubin -out ${WRAPPED_KEY} -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256


#
# Import the wrapped key to the Vault service after base64 encoding the payload.
#
# The service will provide a JSON document containing key details.
#
key_material=$(${BASE64} ${WRAPPED_KEY})
echo "{ \"wrappingAlgorithm\": \"RSA_OAEP_SHA256\", \"keyMaterial\": \"${key_material}\" }" > wrapped_import_key.json
echo "{ \"algorithm\": \"AES\", \"length\": ${KEY_SIZE} }" > key_shape.json

oci kms management key import --wrapped-import-key file://./wrapped_import_key.json --compartment-id ${COMPARTMENT_ID} --display-name ${DISPLAY_NAME} --endpoint ${VAULT_KEYMANAGEMENT_ENDPOINT} --key-shape file://./key_shape.json

##### IMPORT NEW KEY VERSION #####
# import the key version by using the CLI
oci kms management key-version import --key-id ${KEY_ID} --wrapped-import-key ${WRAPPED_KEY}

The following section explains the individual steps in the example script. These commands assume that you already generated key material by using the third-party tool of your choice. Once you have the key material, use the CLI to get the public wrapping key that you'll need to wrap the key material. Wrap the key material by applying RSA-OAEP, and then use the CLI again to import the key material as a new master encryption key or a new key version for an existing master encryption key.

To get the public RSA wrapping key

Open a command prompt and run oci kms management wrapping-key get to get the vault's public RSA wrapping key:

oci kms management wrapping-key get --endpoint <control_plane_URL>

For example:


oci kms management wrapping-key get --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com

After you get the public wrapping key, wrap the AES key material by applying RSA-OAEP.

To apply RSA-OAEP to wrap the key material

Open a command prompt and run the following command to wrap the AES key material with the public RSA wrapping key associated with the vault. Replace example file names and values as appropriate.

openssl pkeyutl -encrypt -in <AES_key_material> -inkey <public_RSA_wrapping_key> -pubin -out <wrapped_AES_key> -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

For example:


openssl pkeyutl -encrypt -in "aes_key.bin" -inkey "publickey.pem" -pubin -out "wrappedkey.bin" -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

After you wrap the key, you can then either import the key material by creating a new key or by rotating a key to a new key version.

To import the key material as a new external key

Open a command prompt and run oci kms management key import to import the wrapped AES key material with the public RSA wrapping key associated with the vault:

oci kms management key import --wrapped-import-key <wrapped_AES_key> --compartment-id <compartment_id> --display-name <key_name> --endpoint <control_plane_URL> --key-shape <key_encryption_information>

For example:

oci kms management key import --wrapped-import-key file://./wrapped_import_key.json --compartment-id ocid1.compartment.oc1..example1example25qrlpo4agcmothkbgqgmuz2zzum45ibplooqtabwk3zz --display-name new-external-key --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com --key-shape file://./key_shape.json
To import the key material as a new external key version

Open a command prompt and run oci kms management key-version import to import the wrapped AES key material as a new key version for an existing key:


oci kms management key-version import --key-id <key_OCID> --wrapped-import-key <wrapped_AES_key>

For example:

oci kms management key-version import --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --wrapped-import-key file://./wrapped_import_key.json