Overview of Vault

Note

Before the introduction of secrets as a resource, Oracle Cloud Infrastructure Vault was known as Oracle Cloud Infrastructure Key Management. Also, support for secrets is not available in Oracle Cloud Infrastructure Government Cloud realms.

Oracle Cloud Infrastructure Vault lets you centrally manage the encryption keys that protect your data and the secret credentials that you use to securely access resources. You can use the Vault service to create and manage the following resources:

  • Vaults
  • Keys
  • Secrets

Vaults securely store master encryption keys and secrets that you might otherwise store in configuration files or in code. Specifically, depending on the protection mode, keys are either stored on the server or they are stored on highly available and durable hardware security modules (HSM) that meet Federal Information Processing Standards (FIPS) 140-2 Security Level 3 security certification.

You can use the Vault service to exercise the following lifecycle management features for vaults, master encryption keys, and secrets, helping you to control these resources and access to them:

  • Create vaults
  • Create or import cryptographic material as master encryption keys
  • Create secrets to store secret credentials
  • Enable or disable master encryption keys for use in cryptographic operations
  • Rotate keys to generate new cryptographic material
  • Export key or vault metadata to a backup that you can restore and use again later

  • Update secrets with new secret contents
  • Specify which secret version is currently in use through promotion
  • Configure rules to govern the management and use of secrets
  • Tag vaults, master encryption keys, or secrets to add metadata to resources
  • Delete vaults, keys, or secrets when they're no longer needed

Regarding the use of master encryption keys, you can do the following:

  • Use keys for encryption and decryption
  • Assign keys to supported Oracle Cloud Infrastructure resources, including, but not limited to, buckets and file systems
  • Generate data encryption keys

Oracle Cloud Infrastructure Object Storage, Oracle Cloud Infrastructure Block Volume, Oracle Cloud Infrastructure File Storage, and Oracle Cloud Infrastructure Streaming integrate with the Vault service to support encryption of data in buckets, block or boot volumes, file systems, and stream pools. Oracle Cloud Infrastructure Container Engine for Kubernetes integrates with the Vault service to support the creation of new clusters with encrypted Kubernetes secrets at rest in the etcd key-value store.

Integration with Oracle Cloud Infrastructure Identity and Access Management (IAM) lets you control who and what services can access which keys and secrets and what they can do with those resources. Oracle Cloud Infrastructure Audit integration gives you a way to monitor key and secret usage. Audit tracks administrative actions on vaults, keys, and secrets.

The Vault service uses the Advanced Encryption Standard (AES) as its encryption algorithm and its keys are AES symmetric keys.

Key and Secret Management Concepts

The following concepts are key to understanding the Vault service.

VAULTS
Vaults are logical entities where the Vault service creates and durably stores keys and secrets. The type of vault you have determines features and functionality such as degrees of storage isolation, access to management and encryption, and scalability. The type of vault you have also affects pricing.
The Vault service offers different vault types to accommodate your organization's needs and budget. A virtual private vault is an isolated partition on a hardware security module (HSM) that ensures the security and integrity of the encryption keys and secrets that are stored in the vault. 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, regular vaults let you manage costs by paying for key versions individually, as you need them. Key versions count toward your key limit and costs. A 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 that contain the cryptographic material used to encrypt and decrypt data, protecting the data where it is stored. 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. Conceptually, the Vault service recognizes three types of encryption keys: master encryption keys, wrapping keys, and data encryption keys.
You can create master encryption keys by using the Console, CLI, or API. Master encryption keys can either be generated internally by the Vault service or imported to the service from an external source. When you create master encryption keys, you create them in a vault, but where a key is actually stored and processed depends on its protection mode. 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 cannot 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 cannot be changed after you create the key.
After you create your first master encryption key, you can then use the API to generate data encryption keys that the Vault service returns to you. Some services can also use a 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 pair based on the RSA algorithm. The public and private key count against your service limits as two key versions, but 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 Vault service. You cannot create, delete, or rotate wrapping keys.
The Vault service recognizes master encryption keys as an Oracle Cloud Infrastructure resource.
KEY VERSIONS
Each master encryption key is automatically assigned a key version. When you rotate a key, the Vault service generates a new key version. The key material for the new key version can be generated by the Vault service or, if the key is protected by an HSM, you can import key material for the new key version. Periodically rotating keys limits the amount of data encrypted by one key version. Key rotation thereby reduces the risk if a key is ever compromised. A key’s unique, Oracle-assigned identifier, called an Oracle Cloud ID (OCID), remains the same across rotations, but the key version enables the Vault service to 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 it, the key version remains available to decrypt any data that it previously encrypted. The Vault service removes the need for you to track which key version was used to encrypt what data because the key's ciphertext contains the information that the service requires for decryption.
HARDWARE SECURITY MODULES
When you create a master encryption key with the protection mode set to "HSM", the Vault 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.) Any given key version or secret version, after it’s created, is replicated within the service infrastructure as a measure of protection against hardware failures. Key versions of HSM-protected keys are not otherwise stored anywhere else and cannot be exported from an HSM.
The Vault service uses HSMs that meet Federal Information Processing Standards (FIPS) 140-2 Security Level 3 security certification. This 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 Vault service and without access to the master encryption key that is protected by Oracle Cloud Infrastructure Identity and Access Management (IAM). For decryption purposes, 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 Vault 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 Vault 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 Vault 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 Vault 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 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.

Regions and Availability Domains

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 encryption keys and secrets across all availability domains within a region. This replication makes it possible for the Vault service to produce keys or secrets upon request, even when an availability domain is unavailable.

Private Access to Vault

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.

Resource Identifiers

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.

Ways to Access Oracle Cloud Infrastructure

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

To access the Console, you must use a supported browser. You can use the Console link at the top of this page to go to the sign-in page. You will be prompted to enter your cloud tenant, your user name, and your password.

For general information about using the API, see REST APIs.

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up groups , compartments , and policies  that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, etc. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.

Limits on Vault Resources

See Service Limits for a list of applicable limits and instructions for requesting a limit increase. 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.