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, you can import your own key material instead of leaving the Vault service responsible for generating the key material internally. 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

Warning

Keys associated with volumes, buckets, file systems, and clusters will not work unless you authorize Oracle Cloud Infrastructure Block Volume, Oracle Cloud Infrastructure Object Storage, Oracle Cloud Infrastructure File Storage, and Oracle Cloud Infrastructure Container Engine for Kubernetes 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, and Container Engine for Kubernetes services encrypt and decrypt volumes, volume backups, buckets, file systems, and Kubernetes secrets in Common Policies.

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted 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
To apply RSA-OAEP to wrap the key material
To import the key material as a new external key
To import the key material as a new external key version

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 CLI Help.

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
To apply RSA-OAEP to wrap the key material
To import the key material as a new external key
To import the key material as a new external key version

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations to wrap and import keys: