Oracle Cloud Infrastructure Documentation

Importing Vault Keys and Key Versions

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's generated by a tool or source based on your requirements.
  • Use the same key material that you use on other cloud or on-premises systems.
  • Manage the key material, its expiration and deletion in the Vault service.
  • Own and manage the key material outside Oracle Cloud Infrastructure for extra durability, and for recovery purposes.
When you create a key or key version, you can import 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 can't 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 can't 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, to meet PCI compliance, you can't import AES keys that are longer than 128 bits.
Note

The wrapping key is created at the time of Vault creation and it's exclusive to the vault. However, you can't create, delete, or rotate a wrapping key.

Also, if you plan to use the 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, Kubernetes Engine, 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 Create a policy to enable encryption keys 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 Configuring OpenSSL Patch to Wrap Key Material. If you're using Windows, you'll need to install Git Bash for Windows to run commands.