Importing Keys and Key Versions

Import the key materials and key versions that you already have and allow the Vault service to use a copy of it.

When you use imported key material, you remain responsible for the key material while allowing the Vault service to use a copy of it. You might want to "bring your own key" (BYOK) if you want to:
  • Use key material that is generated by a tool or source based on your requirements.
  • Use the same key material that you use on other cloud or on-premise systems.
  • Manage the key material, its expiration and deletion in the Vault service.
  • Own and manage the key material outside Oracle Cloud Infrastructure for additional durability, and for recovery purposes.
When you create a key or key version, you can import your own key material instead of letting the Vault service generate the key material internally.
You can import the following key types and key shapes into the Vault service:
Supported Key Types and Key Sizes
Key Type Supported Key Size
Symmetric Keys: Advanced Encryption Standard (AES) algorithm-based symmetric keys are used to encrypt or decrypt. You can import AES keys having any of the following lengths:
  • 128 bits (16 bytes)
  • 192 bits (24 bytes)
  • 256 bits (32 bytes)
Asymmetric Keys: Rivest-Shamir-Adleman (RSA) algorithm-based assymetric keys are used to encrypt, decrypt, sign or verify. You can import RSA keys having any of the following lengths:
  • 2048 bits (256 bytes)
  • 3072 bits (384 bytes)
  • 4096 bits (512 bytes)
Note

Elliptic Curve Cryptography Digital Signature Algorithm (ECDSA) based asymmetric keys cannot be imported.

The length of the key material must match what you specify at the time you create or import a key. Furthermore, before you can import a key, you must wrap the key material by using the public wrapping key provided with each vault. The vault's wrapping key pair make it possible for the HSM to unwrap and store the key securely. To meet payment card industry (PCI) compliance, you cannot import a key of greater strength than the key that you use to wrap it. Vault wrapping keys are 4096-bit RSA keys. As such, if you want to meet PCI compliance, you cannot import AES keys that are longer than 128 bits.

Also, if you plan to use the command line interface (CLI) to create a new external key or external key version, the key material must be base64-encoded.

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. Keys associated with databases will not work unless you authorize a dynamic group that includes all nodes in the DB system to manage keys in the tenancy. For more information, see Required IAM Policy in Exadata Cloud Service

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  to 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 wrap the key material using RSA - Optimal Asymmetric Encryption Padding (OAEP) before importing it. Transforming the key material provides an additional layer of protection by making it possible for only the hardware security module (HSM) in possession of the private RSA wrapping key to unwrap the key.

The Vault service supports the following wrapping mechanisms based on key type:
Key Type Supported Wrapping Mechanism
Symmetric key (AES)
  • RSA_OAEP_SHA256 (RSA-OAEP with a SHA-256 hash)
  • RSA_OAEP_AES_SHA256 (RSA-OAEP with a SHA-256 hash and a temporary AES key)
Asymmetric key (RSA) RSA_OAEP_AES_SHA256 (RSA-OAEP with a SHA-256 hash and a temporary AES key)

If you're using MacOS or Linux, you'll need to install the OpenSSL 1.1.1 series to run commands. If you plan to use RSA_OAEP_AES_SHA256 wrapping, then you must also install an OpenSSL patch that supports it, see To configure and patch OpenSSL. If you're using Windows, you'll need to install Git Bash for Windows to run commands.

Importing Symmetric Keys

Import Advanced Encryption Standard (AES) algorithm-based symmetric keys for encryption and decryption.

Using the Console

Use the Console to get public wrapping key, wrap the AES key material, and then import it as a new master encryption key, or update the key version for an existing master encryption key.

The following procedures assume that you already have the key material. Use the Console to get the public wrapping key, wrap the AES key material and then import it as a new master encryption key, or as a new key version for an existing master encryption key.

To get the public RSA wrapping key

This section describes how to get public RSA wrapping key by using Console.

  1. Open the navigation menu, click Identity & Security, and then click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault for which you want the public RSA wrapping key.
  3. From the list of vaults in the compartment, click the name of the vault.
  4. Click Create Key under Master Encryption Keys.
  5. Select the Import external key check box to see the wrapping key information.
  6. Click the Public Wrapping Key value to view the public RSA wrapping key, and then click Copy.
  7. Save the copied wrapping key, and then continue To apply RSA-OAEP to wrap the key material.
To apply RSA-OAEP to wrap the key material

This section describes how to apply RSA-OAEP to wrap the key material by using Console.

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

openssl pkeyutl -encrypt -in <key_material_to_import> -inkey <public_RSA_wrapping_key> -pubin -out <wrapped_key_material> -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

This section describes how to import the key material as a new external key by using Console.

  1. Open the navigation menu, click Identity & Security, and then 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.
    Note

    You cannot import key material for keys protected by software.
  7. Click Name, and then enter a name to identify the key. Avoid entering confidential information.
  8. Click Key Shape: Algorithm, and choose AES.
  9. Click Key Shape: Length, and then choose the key length, in bits. For AES keys, the Vault service supports keys that are exactly 128 bits, 192 bits, or 256 bits in length.
  10. Select the Import External Key check box.
  11. Click Wrapping Algorithm, and then choose one of the following:
    • RSA_OAEP_SHA256
    • RSA_OAEP_AES_SHA256
  12. Under External Key Data Source, provide the file that contains the wrapped AES key material.
  13. 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 whether to apply tags, skip this option (you can apply tags later) or ask your administrator.
  14. When you are finished, click Create Key.
To import the key material as a new external key version

This section describes how to import the key material as a new external key version by using Console.

Note

Key versions must match the shape of the key to which they're added.
  1. Open the navigation menu, click Identity & Security, and then 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 key material.
  8. When you're ready, click Rotate Key.

Using the Command Line Interface (CLI)

Use the Command Line Interface to get public wrapping key, wrap the AES key material, patch OpenSSL, and then import symmetric key as a master encryption key, or update the key version for an existing master encryption key.

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.

When using the command line to import key material from outside Oracle Cloud Infrastructure, you can either refer to example scripts or you can run CLI commands individually.

The commands in this section 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.

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 get the public RSA wrapping key

This section describes how to get the public RSA wrapping key by using the Command Line Interface (CLI).

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 configure and patch OpenSSL

If you want to wrap your key material using RSA_OAEP_AES_SHA256, then you must patch your CLI with a supported OpenSSL patch.

The OpenSSL -id-aes256-wrap-pad cipher compatible with RSA_AES_KEY_WRAP is not enabled by default in the Command Line Interface (CLI). Patch OpenSSL to allow the envelope wrapping that is needed for the CKM_RSA_AES_KEY_WRAP mechanism.

Perform the following steps to download, compile, and run a new local copy of OpenSSL v1.1.1d using the CLI, without altering the default installation of OpenSSL in the system:

  1. Create directories to store the latest OpenSSL binaries in /root/build.
    mkdir $HOME/build
    mkdir -p $HOME/local/ssl
    cd $HOME/build
  2. Run the following command and note the OpenSSL version:
    openssl version
  3. Note the latest OpenSSL version at https://www.openssl.org/source/.
  4. Download and unpack the libraries.
    Replace openssl-1.1.1d.tar.gz with the latest version from step 3.
    curl -O https://www.openssl.org/source/openssl-1.1.1d.tar.gz
    tar -zxf openssl-1.1.1d.tar.gz
  5. Install the patch, make gcc tools to patch, and then compile the binaries.
    sudo yum install patch make gcc -y
  6. Run the following commands:
    Note

    You might need to update these commands for newer versions of OpenSSL.
    cat <<-EOF | patch -d $HOME/build/ -p0
    diff -ur orig/openssl-1.1.1d/apps/enc.c openssl-1.1.1d/apps/enc.c
    --- orig/openssl-1.1.1d/apps/enc.c      
    +++ openssl-1.1.1d/apps/enc.c   
    @@ -533,6 +533,7 @@
              */
    
             BIO_get_cipher_ctx(benc, &ctx);
    +        EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW);
    
             if (!EVP_CipherInit_ex(ctx, cipher, NULL, NULL, NULL, enc)) {
                 BIO_printf(bio_err, "Error setting cipher %s\n",
    EOF
    Confirm successful patching if response is similar to the following:
    [root@ip-172-31-20-119 ~]# cat «-EOF | patch -d $HOME/build/ -p0 
    diff -ur orig/openssl-1.1.1d/apps/enc.c openssl-1.1.1d/apps/enc.c 
    --- orig/openssl-1.1.1d/apps/enc.c 
    +++ openssl-l.1.1d/apps/enc.c 
    @@ -533,6 +533,7 @@
            */
    
        BIO_get_cipher_ctx (benc, &ctx) ; 
    +        EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW) ; 
    
        if (!EVP_CipherInit_ex (ctx, cipher, NULL, NULL, NULL, enc) )  {
             BIO_printf (bio_err, "Error setting cipher %s\n" , 
    EOF 
    
    patching file openssl-1.1.1d/apps/enc.c
  7. Compile the enc.c file.
    Note

    Compiling might take several minutes for each command.
    cd $HOME/build/openssl-1.1.1d/
    ./config --prefix=$HOME/local --openssldir=$HOME/local/ssl
    make -j$(grep -c ^processor /proc/cpuinfo)
    make install
    You have successfully installed the latest version of OpenSSL. This version is dynamically linked to libraries in the $HOME/local/ssl/lib/ directory, and cannot be run directly. Set the environment variable LD_LIBRARY_PATH to ensure that the associated libraries are available to OpenSSL.
  8. Create a script named openssl.sh that loads the $HOME/local/ssl/lib/ path before running the binary. This makes it easier to run OpenSSL multiple times.
    cd $HOME/local/bin/
    
    echo -e '#!/bin/bash \nenv LD_LIBRARY_PATH=$HOME/local/lib/ $HOME/local/bin/openssl "$@"' > ./openssl.sh
  9. Set the execute bit on the script.
    chmod 755 ./openssl.sh
  10. Start OpenSSL with the following command:
    $HOME/local/bin/openssl.sh
To apply RSA-OAEP to wrap the key material

This section describes how to apply RSA-OAEP to wrap the key material by using the Command Line Interface (CLI).

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 <key_material_to_import> -inkey <public_RSA_wrapping_key> -pubin -out <wrapped_key_material> -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

Apply base64 encoding on the wrapped key material and then import it to create a key or rotate an existing key to a new key version.

To import the key material as a new external key

This section describes how to import the key material as a new external key by using the Command Line Interface (CLI).

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

oci kms management key import --wrapped-import-key <wrapped_key_material> --compartment-id <compartment_id> --display-name <key_name> --endpoint <control_plane_URL> --key-shape <key_encryption_information> --protection-mode <key_protection_mode>
Note

protection-mode indicates how the key persists and where cryptographic operations that use the key are performed. A protection mode of HSM means that the key persists on a hardware security module (HSM) and all cryptographic operations are performed inside the HSM. A protection mode of SOFTWARE means that the key persists on the server, protected by the vault's RSA wrapping key which persists on the HSM. All cryptographic operations that use a key with a protection mode of SOFTWARE are performed on the server. By default, a key's protection mode is set to HSM. You can't change a key's protection mode after the key is created or imported.

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 --protection-mode HSM
To import the key material as a new external key version

This section describes how to import the key material as a new external key version by using the Command Line Interface (CLI).

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_key_material>

For example:

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

Example Scripts

Fully auto generate 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.

This section includes example scripts for importing AES key material.

Script to import AES key material as a new external key

Automate the import of AES key material as a new key with the following example script.

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).
​
# PROTECTION_MODE either SOFTWARE or HSM
PROTECTION_MODE="SOFTWARE"
​
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 --protection-mode ${PROTECTION_MODE}
Script to import AES key material as a new external key version

Automate the import of AES key material as a new key version of an existing key with the following example script.

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}

Importing Asymmetric Keys

Import asymmetric keys or key versions, get the public wrapping key, wrap the RSA key material and then import it as a new master encryption key, or as a new key version for an existing master encryption key.

Using the Console

Use the Console to import symmetric keys.

The following procedures assume that you already have the key material. Use the Console to get the public wrapping key, wrap the RSA key material and then import it as a new master encryption key, or as a new key version for an existing master encryption key.

To get the public RSA wrapping key

This section describes how to get the public RSA wrapping key.

  1. Open the navigation menu, click Identity & Security, and then click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment that contains the vault for which you want the public RSA wrapping key.
  3. From the list of vaults in the compartment, click the name of the vault.
  4. Click Create Key under Master Encryption Keys.
  5. Select the Import external key check box to see the wrapping key information.
  6. Click the Public Wrapping Key value to view the public RSA wrapping key, and then click Copy.
  7. Save the copied wrapping key, and then continue To apply RSA-OAEP with AES to wrap the key material.
To apply RSA-OAEP with AES to wrap the key material

This section describes how to apply RSA-OAEP with AES to wrap key material.

Prerequisites:
Open a command prompt and perform the following steps. Replace variables with appropriate values:
  1. Generate a temporary AES key:
    openssl rand -out <temporary_AES_key_path> 32
  2. Wrap the temporary AES key with the public wrapping key using RSA-OAEP with SHA-256:
    openssl pkeyutl -encrypt -in <temporary_AES_key_path> -inkey <vault_public_wrapping_key_path> -pubin -out <wrapped_temporary_AES_key_file> -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
  3. Generate hexadecimal of the temporary AES key material:
    temporary_AES_key_hexdump=$(hexdump -v -e '/1 "%02x"' < ${temporary_AES_key_path})
  4. If the RSA private key you want to import is in PEM format, convert it to DER:
    ${OpenSSL_path} pkcs8 -topk8 -nocrypt -inform PEM -outform DER -in <your_pem_RSA_private_key_path> -out <your_RSA_private_key_file>
  5. Wrap your RSA private key with the temporary AES key:
    openssl enc -id-aes256-wrap-pad -iv A65959A6 -K temporary_AES_key_hexdump -in <your_RSA_private_key_file> -out <wrapped_target_key_file>
  6. Create the wrapped key material by concatenating both wrapped keys:
    cat <wrapped_temporary_AES_key_file> <wrapped_target_key_file> > <wrapped_key_material_file>

You can now import the wrapped key material to create a key or rotate an existing key to a new key version.

To import the key material as a new external key

This section describes how to import key material as a new external key.

  1. Open the navigation menu, click Identity & Security, and then 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.
    Note

    You cannot import key material for keys protected by software.
  7. Click Name, and then enter a name to identify the key. Avoid entering confidential information.
  8. Click Key Shape: Algorithm, and choose RSA.
  9. Click Key Shape: Length, and then choose the key length, in bits. For RSA keys, the Vault service supports keys that are exactly 2048 bits, 3072 bits, or 4096 bits in length.
  10. Select the Import External Key check box.
  11. Click Wrapping Algorithm, and then choose RSA_OAEP_AES_SHA256 (RSA-OAEP with a SHA-256 with a temporary AES key).
  12. Under External Key Data Source, provide the file that contains the wrapped RSA key material.
  13. 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 whether to apply tags, skip this option (you can apply tags later) or ask your administrator.
  14. When you are finished, click Create Key.
To import the key material as a new external key version

This section describes how to import 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, click Identity & Security, and then 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 key material.
  8. When you're ready, click Rotate Key.

Using the Command Line Interface (CLI)

Use the Command Line Interface to import asymmetric keys.

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.

When using the command line to import key material from outside Oracle Cloud Infrastructure, you can either refer to example scripts or you can run CLI commands individually.

The commands in this section 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.

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 get the public RSA wrapping key

This section describes how to get the public wrapping key Command Line Interface (CLI).

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 RSA key material by applying RSA-OAEP with AES.

To configure and patch OpenSSL

If you want to wrap your key material using RSA_OAEP_AES_SHA256, then you must patch your CLI with a supported OpenSSL patch.

The OpenSSL -id-aes256-wrap-pad cipher compatible with RSA_AES_KEY_WRAP is not enabled by default in the Command Line Interface (CLI). Patch OpenSSL to allow the envelope wrapping that is needed for the CKM_RSA_AES_KEY_WRAP mechanism.

Perform the following steps to download, compile, and run a new local copy of OpenSSL v1.1.1d using the CLI, without altering the default installation of OpenSSL in the system:

  1. Create directories to store the latest OpenSSL binaries in /root/build.
    mkdir $HOME/build
    mkdir -p $HOME/local/ssl
    cd $HOME/build
  2. Run the following command and note the OpenSSL version:
    openssl version
  3. Note the latest OpenSSL version at https://www.openssl.org/source/.
  4. Download and unpack the libraries.
    Replace openssl-1.1.1d.tar.gz with the latest version from step 3.
    curl -O https://www.openssl.org/source/openssl-1.1.1d.tar.gz
    tar -zxf openssl-1.1.1d.tar.gz
  5. Install the patch, make gcc tools to patch, and then compile the binaries.
    sudo yum install patch make gcc -y
  6. Run the following commands:
    Note

    You might need to update these commands for newer versions of OpenSSL.
    cat <<-EOF | patch -d $HOME/build/ -p0
    diff -ur orig/openssl-1.1.1d/apps/enc.c openssl-1.1.1d/apps/enc.c
    --- orig/openssl-1.1.1d/apps/enc.c      
    +++ openssl-1.1.1d/apps/enc.c   
    @@ -533,6 +533,7 @@
              */
    
             BIO_get_cipher_ctx(benc, &ctx);
    +        EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW);
    
             if (!EVP_CipherInit_ex(ctx, cipher, NULL, NULL, NULL, enc)) {
                 BIO_printf(bio_err, "Error setting cipher %s\n",
    EOF
    Confirm successful patching if response is similar to the following:
    [root@ip-172-31-20-119 ~]# cat «-EOF | patch -d $HOME/build/ -p0 
    diff -ur orig/openssl-1.1.1d/apps/enc.c openssl-1.1.1d/apps/enc.c 
    --- orig/openssl-1.1.1d/apps/enc.c 
    +++ openssl-l.1.1d/apps/enc.c 
    @@ -533,6 +533,7 @@
            */
    
        BIO_get_cipher_ctx (benc, &ctx) ; 
    +        EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW) ; 
    
        if (!EVP_CipherInit_ex (ctx, cipher, NULL, NULL, NULL, enc) )  {
             BIO_printf (bio_err, "Error setting cipher %s\n" , 
    EOF 
    
    patching file openssl-1.1.1d/apps/enc.c
  7. Compile the enc.c file.
    Note

    Compiling might take several minutes for each command.
    cd $HOME/build/openssl-1.1.1d/
    ./config --prefix=$HOME/local --openssldir=$HOME/local/ssl
    make -j$(grep -c ^processor /proc/cpuinfo)
    make install
    You have successfully installed the latest version of OpenSSL. This version is dynamically linked to libraries in the $HOME/local/ssl/lib/ directory, and cannot be run directly. Set the environment variable LD_LIBRARY_PATH to ensure that the associated libraries are available to OpenSSL.
  8. Create a script named openssl.sh that loads the $HOME/local/ssl/lib/ path before running the binary. This makes it easier to run OpenSSL multiple times.
    cd $HOME/local/bin/
    
    echo -e '#!/bin/bash \nenv LD_LIBRARY_PATH=$HOME/local/lib/ $HOME/local/bin/openssl "$@"' > ./openssl.sh
  9. Set the execute bit on the script.
    chmod 755 ./openssl.sh
  10. Start OpenSSL with the following command:
    $HOME/local/bin/openssl.sh
To apply RSA-OAEP with AES to wrap the key material

This section describes how to apply RSA-OAEP with AES to wrap the key material Command Line Interface (CLI).

Open a command prompt and run the following commands to wrap the RSA key material using RSA-OAEP with a temporary AES key. Replace example file names and values as appropriate.

  1. Generate a temporary AES key:
    openssl rand -out <temporary_AES_key_path> 32
  2. Wrap the temporary AES key with the public wrapping key using RSA-OAEP with SHA-256:
    openssl pkeyutl -encrypt -in <temporary_AES_key_path> -inkey <vault_public_wrapping_key_path> -pubin -out <wrapped_temporary_AES_key_file> -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
  3. Generate hexadecimal of the temporary AES key material:
    temporary_AES_key_hexdump=$(hexdump -v -e '/1 "%02x"' < ${temporary_AES_key_path})
  4. If the RSA private key you want to import is in PEM format, convert it to DER:
    ${OpenSSL_path} pkcs8 -topk8 -nocrypt -inform PEM -outform DER -in <your_pem_RSA_private_key_path> -out <your_RSA_private_key_file>
  5. Wrap your RSA private key with the temporary AES key:
    openssl enc -id-aes256-wrap-pad -iv A65959A6 -K temporary_AES_key_hexdump -in <your_RSA_private_key_file> -out <wrapped_target_key_file>
  6. Create the wrapped key material by concatenating both wrapped keys:
    cat <wrapped_temporary_AES_key_file> <wrapped_target_key_file> > <wrapped_key_material_file>

Apply base64 encoding on the wrapped key material and then import it to create a key or rotate an existing key to a new key version.

To import the key material as a new external key

This section describes how to import the key material as a new external key Command Line Interface (CLI).

Open a command prompt and run oci kms management key import to import the wrapped RSA key material:
oci kms management key import --wrapped-import-key <wrapped_key_material> --compartment-id <compartment_id> --display-name <key_name> --endpoint <control_plane_URL> --key-shape <key_encryption_information> --protection-mode <key_protection_mode>
Note

protection-mode indicates how the key persists and where cryptographic operations that use the key are performed. A protection mode of HSM means that the key persists on a hardware security module (HSM) and all cryptographic operations are performed inside the HSM. A protection mode of SOFTWARE means that the key persists on the server, protected by the vault's RSA wrapping key which persists on the HSM. All cryptographic operations that use a key with a protection mode of SOFTWARE are performed on the server. By default, a key's protection mode is set to HSM. You can't change a key's protection mode after the key is created or imported.

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 --protection-mode SOFTWARE
To import the key material as a new external key version

This section describes how to import the key material as a new external key version using the Command Line Interface (CLI).

Open a command prompt and run oci kms management key-version import to import the wrapped RSA 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_key_material>

For example:

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

Example Scripts

Example scripts illustrate how you might fully automate generating the key material, applying RSA-OAEP with AES to wrap the key material, and then creating the new key or key version based on the imported, wrapped key material.

This section includes example scripts for importing RSA key material.

Script to import RSA key material as a new external key

Automate the import of RSA key material as a new key with the following example script.

Open a command prompt, and then run the following script, replacing example file names and values as appropriate:
#!/bin/bash

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

set -e;
#set -x;

OPENSSL_PATH="<path to patched openssl.sh>"
PRIVATE_KEY="<path to target private key which needs to be imported>"
WRAPPING_KEY="<path to vault public wrapping key>"
WORK_DIR=$(mktemp -d -t kms_XXXX)
BASE64="base64"

echo "Openssl Path: ${OPENSSL_PATH}"
echo "Work Dir: ${WORK_DIR}"

# Convert the private key to PKCS8 DER format.
target_key_path=${WORK_DIR}/target_key.key
${OPENSSL_PATH} pkcs8 -topk8 -nocrypt -inform PEM -outform DER -in ${PRIVATE_KEY} -out ${target_key_path} 

# Generate a temporary AES key.
temp_aes_key_path=${WORK_DIR}/temp_aes_key.key
${OPENSSL_PATH} rand -out ${temp_aes_key_path} 32

# Wrap the temporary AES key by using RSA-OAEP with SHA-256.
wrapped_temp_aes_key=${WORK_DIR}/wrapped_temp_aes_key.bin
${OPENSSL_PATH} pkeyutl -encrypt -in ${temp_aes_key_path} -inkey ${WRAPPING_KEY} -pubin -out ${wrapped_temp_aes_key} -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

# Wrap the target RSA key.
wrapped_target_key=${WORK_DIR}/wrapped_target_key.bin
temp_aes_key_hexdump=$(hexdump -v -e '/1 "%02x"' < ${temp_aes_key_path})
${OPENSSL_PATH} enc -id-aes256-wrap-pad -iv A65959A6 -K ${temp_aes_key_hexdump} -in ${target_key_path} -out ${wrapped_target_key}

# Create the wrapped key material.
wrapped_key_material_bin=${WORK_DIR}/wrapped_key_material.bin
cat ${wrapped_temp_aes_key} ${wrapped_target_key} > ${wrapped_key_material_bin}

echo "Binary wrapped key for console is available at: ${wrapped_key_material_bin}"

#
# Import the wrapped key to the Vault service after base64 encoding the payload.
#
wrapped_key_material_base64=${WORK_DIR}/wrapped_key_material.base64
${BASE64} ${wrapped_key_material_bin} -w 0 > ${wrapped_key_material_base64}
echo "Base64 encoded wrapped key for CLI or API is available at: ${wrapped_key_material_base64}"


##### 1. IMPORT NEW KEY USING CONSOLE #####
# browse and upload ${WORK_DIR}/wrapped_key_material.bin file in key import section on console.

##### 2. IMPORT NEW KEY USING OCI_CLI #####
# key_material=$(${BASE64} ${wrapped_key_material_bin})
# echo "{ \"wrappingAlgorithm\": \"RSA_OAEP_AES_SHA256\", \"keyMaterial\": \"${key_material}\" }" > wrapped_import_key.json
# echo "{ \"algorithm\": \"RSA\", \"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 --protection-mode SOFTWARE
Script to import RSA key material as a new external key version

You can automate the import of AES key material as a new key version for an existing key.

Open a command prompt, and then run the following script, replacing example file names and values as appropriate:
#!/bin/bash

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

set -e;
#set -x;

OPENSSL_PATH="<path to patched openssl.sh>"
PRIVATE_KEY="<path to target private key which needs to be imported>"
WRAPPING_KEY="<path to vault public wrapping key>"
KEY_OCID="<Key OCID of OCI Vault in which the key version will be created>"
WORK_DIR=$(mktemp -d -t kms_XXXX)
BASE64="base64"

echo "Openssl Path: ${OPENSSL_PATH}"
echo "Work Dir: ${WORK_DIR}"

# Convert the private key to PKCS8 DER format.
target_key_path=${WORK_DIR}/target_key.key
${OPENSSL_PATH} pkcs8 -topk8 -nocrypt -inform PEM -outform DER -in ${PRIVATE_KEY} -out ${target_key_path} 

# Generate a temporary AES key.
temp_aes_key_path=${WORK_DIR}/temp_aes_key.key
${OPENSSL_PATH} rand -out ${temp_aes_key_path} 32

# Wrap the temporary AES key by using RSA-OAEP with SHA-256.
wrapped_temp_aes_key=${WORK_DIR}/wrapped_temp_aes_key.bin
${OPENSSL_PATH} pkeyutl -encrypt -in ${temp_aes_key_path} -inkey ${WRAPPING_KEY} -pubin -out ${wrapped_temp_aes_key} -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256

# Wrap the target RSA key.
wrapped_target_key=${WORK_DIR}/wrapped_target_key.bin
temp_aes_key_hexdump=$(hexdump -v -e '/1 "%02x"' < ${temp_aes_key_path})
${OPENSSL_PATH} enc -id-aes256-wrap-pad -iv A65959A6 -K ${temp_aes_key_hexdump} -in ${target_key_path} -out ${wrapped_target_key}

# Create the wrapped key material.
wrapped_key_material_bin=${WORK_DIR}/wrapped_key_material.bin
cat ${wrapped_temp_aes_key} ${wrapped_target_key} > ${wrapped_key_material_bin}

echo "Binary wrapped key for console is available at: ${wrapped_key_material_bin}"

#
# Import the wrapped key to the Vault service after base64 encoding the payload.
#
wrapped_key_material_base64=${WORK_DIR}/wrapped_key_material.base64
${BASE64} ${wrapped_key_material_bin} -w 0 > ${wrapped_key_material_base64}
echo "Base64 encoded wrapped key for CLI or API is available at: ${wrapped_key_material_base64}"


##### 1. IMPORT NEW KEY_VERSION USING CONSOLE #####
# browse and upload ${WORK_DIR}/wrapped_key_material.bin file in import key version section on console.

##### 2. IMPORT NEW KEY_VERSION USING OCI_CLI #####
# key_material=$(${BASE64} ${wrapped_key_material_bin})
# echo "{ \"wrappingAlgorithm\": \"RSA_OAEP_AES_SHA256\", \"keyMaterial\": \"${key_material}\" }" > wrapped_import_key.json
#
# oci kms management key-version import --key-id ${KEY_OCID} --wrapped-import-key file://wrapped_import_key.json