Key Management

Understand vault and key management concepts for accessing and managing vaults, keys, and secrets.

Vaults

Vaults are logical entities where the Key Management service creates and durably stores vault keys and secrets. The type of vault you have determines features and functionality such as degrees of storage isolation, access to management and encryption, scalability, and the ability to back up. The type of vault you have also affects pricing. You cannot change a vault's type after you create the vault.

The Key Management service offers different vault types to accommodate your organization's needs and budget. All vault types ensure the security and integrity of the encryption keys and secrets that vaults store. A virtual private vault is an isolated partition on a hardware security module (HSM). Vaults otherwise share partitions on the HSM with other vaults.

Virtual private vaults include 1000 key versions by default. If you don't require the greater degree of isolation or the ability to back up the vault, you don't need a virtual private vault. Without a virtual private vault, you can manage costs by paying for key versions individually, as you need them. (Key versions count toward your key limit and costs. A vault key always contains at least one active key version. Similarly, a secret always has at least one secret version. However, limits on secrets apply to the tenancy, rather than a vault.)

For customers who have regulatory compliance to store keys outside Oracle cloud or any third-party cloud premises, OCI KMS now offers a functionality called External Key Management Service (External KMS). In External KMS, you can store and control master encryption keys (as external keys) on a third-party key management system hosted outside OCI. You can then use these keys for encrypting your data in Oracle. You can also disable your keys anytime. With the actual keys residing in the third-party key management system, you create only key references (associated with the key material) in OCI.

OCI KMS offers the Dedicated KMS, which is a customer-managed, highly available, single-tenant HSM partition resource as a service. It enables you to have greater control by owning the HSM partition and encrypted keys as well as the users in the partition. In a Dedicated KMS setup, the HSM Cluster comes with three HSM partitions by default, which are auto synchronized. You can manage keys and users in the HSMs integrated with OCI compute instances through Client utilities and PKCS #11 libraries. Dedicated KMS supports only HSM-protected keys and doesn't support Software protected keys. For cryptographic operations, the solution supports both symmetric and asymmetric encryption using AES, RSA, and ECDSA algorithms .

Virtual private vaults include 1000 key versions by default. If you don't require the greater degree of isolation or the ability to back up the vault, you don't need a virtual private vault. Without a virtual private vault, you can manage costs by paying for key versions individually, as you need them. (Key versions count toward your key limit and costs. A vault key always contains at least one active key version. Similarly, a secret always has at least one secret version. However, limits on secrets apply to the tenancy, rather than a vault.)

The Vault service designates vaults as an Oracle Cloud Infrastructure resource.

Keys

Keys are logical entities that represent one or more key versions, each of which contains cryptographic material. A vault key's cryptographic material is generated for a specific algorithm that lets you use the key for encryption or in digital signing. When used for encryption, a key or key pair encrypts and decrypts data, protecting the data where the data is stored or while the data is in transit. With an AES symmetric key, the same key encrypts and decrypts data. With an RSA asymmetric key, the public key encrypts data and the private key decrypts data.

You can use AES keys in encryption and decryption, but not in digital signing. RSA keys, however, can be used not only to encrypt and decrypt data, but also to digitally sign data and verify the authenticity of signed data. You can use ECDSA keys in digital signing, but not to encrypt or decrypt data.

When processed as part of an encryption algorithm, a key specifies how to transform plaintext into ciphertext during encryption and how to transform ciphertext into plaintext during decryption. When processed as part of a signing algorithm, together, the private key of an asymmetric key and a message produce a digital signature that accompanies the message in transit. When processed as part of a signature verifying algorithm by the recipient of the signed message, the message, signature, and the public key of the same asymmetric key confirm or deny the authenticity and integrity of the message.

Conceptually, the Key Management service recognizes three types of encryption keys: master encryption keys, wrapping keys, and data encryption keys.

The encryption algorithms that the Key Management service supports for vault master encryption keys include AES, RSA, and ECDSA. You can create AES, RSA, or ECDSA master encryption keys by using the Console, CLI, or API. When you create a master encryption key, the Key Management service can either generate the key material internally or you can import the key material to the service from an external source. (Support for importing key material depends on the encryption algorithm of the key material.) When you create vault master encryption keys, you create them in a vault, but where a key is stored and processed depends on its protection mode.

Vault master encryption keys can have one of two protection modes: HSM or software. A master encryption key protected by an HSM is stored on an HSM and can't be exported from the HSM. All cryptographic operations involving the key also happen on the HSM. Meanwhile, a master encryption key protected by software is stored on a server and, therefore, can be exported from the server to perform cryptographic operations on the client instead of on the server. While at rest, the software-protected key is encrypted by a root key on the HSM. For a software-protected key, any processing related to the key happens on the server. A key's protection mode affects pricing and can't be changed after you create the key.

After you create your first symmetric master encryption key, you can then use the API to generate data encryption keys that the Key Management service returns to you. Some services can also use a symmetric master encryption key to generate their own data encryption keys.

A type of encryption key that comes included with each vault by default is a wrapping key. A wrapping key is a 4096-bit asymmetric encryption key based on the RSA algorithm. The public and private key pair don't count against service limits. They also don't incur service costs. You use the public key as the key encryption key when you need to wrap key material for import into the Key Management service. You can't create, delete, or rotate wrapping keys.

The Key Management service recognizes master encryption keys as an Oracle Cloud Infrastructure resource.

Key Versions & Rotations

Each master encryption key is automatically assigned a key version. When you rotate a key, the Key Management service generates a new key version. The Key Management service can generate the key material for the new key version or you can import your own key material.

Periodically rotating keys limits the amount of data encrypted or signed by one key version. If a key is ever compromised, key rotation thus reduces the risk. A key’s unique, Oracle-assigned identifier, called an Oracle Cloud ID (OCID), remains the same across rotations, but the key version lets the Key Management service seamlessly rotate keys to meet any compliance requirements you might have.

Although you can't use an older key version for encryption after you rotate a key, the key version remains available to decrypt any data that it was used to encrypt. If you rotate an asymmetric key, the public key can no longer be used to encrypt data, but the private key remains available to decrypt data that was encrypted by the public key. When you rotate an asymmetric key used in digital signing, you can no longer use the private key version to sign data, but the public key version remains available to verify the digital signature of data previously signed by the older private key version.

For symmetric keys, you don't need to track which key version was used to encrypt what data because the key's ciphertext contains the information that the service needs for decryption purposes. Through rotations of asymmetric keys, however, you must track which key version was used to encrypt or sign what data. With asymmetric keys, the key's ciphertext doesn't contain the information that the service requires for decryption or verification.

With AES symmetric keys, each key version counts as one key version when calculating service limits usage. However, with RSA and ECDSA asymmetric keys, each key version counts as two when calculating usage against service limits because an asymmetric key has both a public key and private key. (Asymmetric keys are also known as key pairs.)

Automatic Key Rotation

Note

This feature is available only for private vaults.

OCI's Key Management service lets you schedule automatic key rotation for an encryption key in a virtual private vault. When you configure automatic rotation, you set the frequency of rotation and the start date of the rotation schedule. For the frequency, you chose a rotation interval between 60 days and 365 days. KMS supports automatic key rotation for both HSM and software keys, and supports automatic rotation of both symmetric and asymmetric keys. Note that a key must be in the "enabled" state to configure automatic rotation.

Features and requirements of automatic key rotation:

• You can update the rotation schedule for a key after you enable automatic rotation, as needed.
• You can rotate a key on-demand (perform a manual rotation) when automatic key rotation is enabled for the key.
• You can track automatic key rotation activities for a key, including the last rotation status and status message, updates to the rotation interval, and next rotation start date.
• You can send an event notification if a key rotation fails.

Auto rotation event notification: To receive automatic key rotation event notifications, you must configure the OCI Events service. After every key rotation, KMS sends out a notification about the rotation status and error messages, if any. The OCI Events service lets you use events rules to invoke a function, which you can use for automation. For example, you can use functions to automate the following tasks:

• Re-encrypt data with a new key version
• Delete an old key version
• Distribute the public portion of asymmetric keys for signing or verifying data

See Creating an Events Rule and Overview of Functions for more information.

HARDWARE SECURITY MODULES

When you create an AES symmetric master encryption key with the protection mode set to HSM, the Key Management service stores the key version within a hardware security module (HSM) to provide a layer of physical security. (When you create a secret, secret versions are base64-encoded and encrypted by a master encryption key, but are not stored within the HSM.) After you create the resources, the service maintains copies of any given key version or secret version within the service infrastructure to provide resilience against hardware failures. Key versions of HSM-protected keys are not otherwise stored anywhere else and cannot be exported from an HSM.

When you create an RSA or ECDSA asymmetric master encryption key with the protection mode set to HSM, the Key Management service stores the private key within an HSM and does not allow its export from the HSM. However, you can download the public key.

The Key Management service uses HSMs that meet Federal Information Processing Standards (FIPS) 140-2 Security Level 3 security certification. This certification means that the HSM hardware is tamper-evident, has physical safeguards for tamper-resistance, requires identity-based authentication, and deletes keys from the device when it detects tampering.

ENVELOPE ENCRYPTION

The data encryption key used to encrypt your data is, itself, encrypted with a master encryption key. This concept is known as envelope encryption. Oracle Cloud Infrastructure services do not have access to the plaintext data without interacting with the Key Management service and without access to the master encryption key that is protected by Oracle Cloud Infrastructure Identity and Access Management (IAM). For decryption purposes, integrated services like Object Storage, Block Volume, and File Storage store only the encrypted form of the data encryption key.

SECRETS

Secrets are credentials such as passwords, certificates, SSH keys, or authentication tokens that you use with Oracle Cloud Infrastructure services. Storing secrets in a vault provides greater security than you might achieve storing them elsewhere, such as in code or configuration files. You can retrieve secrets from the Key Management service when you need them to access resources or other services.

You can create secrets by using the Console, CLI, or API. Secret contents for a secret are imported to the service from an external source. The Vault service stores secrets in vaults.

The Key Management service supports secrets as an Oracle Cloud Infrastructure resource.

SECRET VERSIONS

Each secret is automatically assigned a secret version. When you rotate secret, you provide new secret contents to the Key Management service to generate a new secret version. Periodically rotating secret contents reduces the impact in case a secret is exposed. A secret’s unique, Oracle-assigned identifier, called an Oracle Cloud ID (OCID), remains the same across rotations, but the secret version lets the Key Management service rotate secret contents to meet any rules or compliance requirements you might have. Although you can't use an older secret version's contents after you rotate it if you have a rule configured preventing secret reuse, the secret version remains available and is marked with a rotation state other than "current". For more information about secret versions and their rotation states, see Secret Versions and Rotation States.

SECRET BUNDLES

A vault secret bundle consists of the secret contents, properties of the secret and secret version (such as version number or rotation state), and user-provided contextual metadata for the secret. When you rotate a secret, you create a new secret version, which also includes a new secret bundle version.

The Vault service is available in all Oracle Cloud Infrastructure commercial regions. See About Regions and Availability Domains for the list of available regions, along with associated locations, region identifiers, region keys, and availability domains.

Unlike some Oracle Cloud Infrastructure services, however, the Vault service does not have one regional endpoint for all API operations. The service has one regional endpoint for the provisioning service that handles create, update, and list operations for vaults. For create, update, and list operations for keys, service endpoints are distributed across multiple independent clusters. Service endpoints for secrets are distributed further still across different independent clusters.

Because the Vault service has public endpoints, you can directly use data encryption keys generated by the service for cryptographic operations in your applications. However, if you want to use master encryption keys with a service that has integrated with Vault, you can do so only when the service and the vault that holds the key both exist within the same region. Different endpoints exist for key management operations, key cryptographic operations, secret management operations, and secret retrieval operations. For more information, see Oracle Cloud Infrastructure API Documentation

The Vault service maintains copies of vaults and their contents to durably persist them and to make it possible for the Vault service to produce keys or secrets upon request, even when an availability domain is unavailable. This replication is independent of any cross-region replication that a customer might configure.

For regions with multiple availability domains, the Vault service maintains copies of encryption keys across all availability domains within the region. Regions with multiple availability domains have one rack for each availability domain, which means that the replication happens across three total racks in these regions, where each rack belongs to a different availability domain. In regions with a single availability domain, the Vault service maintains encryption key copies across fault domains.

For secrets, in regions with multiple availability domains, the Vault service distributes secret copies across two different availability domains. In regions with a single availability domain, the Vault service distributes the copies across two different fault domains.

Every availability domain has three fault domains. Fault domains help provide high availability and fault tolerance by making it possible for the Vault service to distribute resources across different physical hardware within a given availability domain. The physical hardware itself also has independent and redundant power supplies that prevent a power outage in one fault domain from affecting other fault domains.

All of this makes it possible for the Vault service to produce keys and secrets upon request, even when an availability domain is unavailable in a region with multiple availability domains or when a fault domain is unavailable in a region with a single availability domain.

The Vault service supports private access from Oracle Cloud Infrastructure resources in a virtual cloud network (VCN) through a service gateway. Setting up and using a service gateway on a VCN lets resources (such as the instances that your encrypted volumes are attached to) access public Oracle Cloud Infrastructure services such as the Vault service without exposing them to the public internet. No internet gateway is required and resources can be in a private subnet and use only private IP addresses. For more information, see Access to Oracle Services: Service Gateway.

The Vault service supports vaults, keys, and secrets as Oracle Cloud Infrastructure resources. Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to identify your resources, see Resource Identifiers., see Resource Identifiers.

You can access the Oracle Cloud Infrastructure by entering your cloud account.

You can access Oracle Cloud Infrastructure (OCI) by using the Console (a browser-based interface), REST API, or OCI CLI. Instructions for using the Console, API, and CLI are included in topics throughout this documentation. For a list of available SDKs, see Software Development Kits and Command Line Interface.

To access the Console, you must use a supported browser. To go to the Console sign-in page, open the navigation menu at the top of this page and click Infrastructure Console. You are prompted to enter your cloud tenant, your user name, and your password.

Know the Vault Service limitation and its resource usage before you begin to use them.

For a list of applicable limits and instructions for requesting a limit increase, see Service Limits. To set compartment-specific limits on a resource or resource family, administrators can use compartment quotas.

For instructions to view your usage level against the tenancy's resource limits, see Viewing Your Service Limits, Quotas, and Usage. You can also get each individual vault's usage against key limits by viewing key and key version counts in the vault details.