Overview
This page describes the benefits of Vault, its basic concepts, and how to use it.
Quick View
| What it does | Provides secure storage of secrets, cryptographic keys, and Pangea API Tokens tokens as Vault items. Easily generate, import, and manage secrets and keys to stay compliant and secure. |
| Supported Languages | |
| Capabilities |
|
About Vault service
The Vault service combines the best capabilities of key and secrets management solutions into one service. It enables you to generate, import, and manage key lifecycles while also providing endpoints for performing cryptographic operations without ever exposing private key material. Similarly, the Vault service allows you to store, manage, and access secrets as text strings. Using the Vault service helps ensure a secure development lifecycle by preventing private key material from ever being leaked into code and preventing the accidental hard-coding and exposure of secrets.
Benefits of Vault
The Vault service provides the following benefits to keys, secrets, and Pangea tokens.
- Rotation policy: Keys and Pangea tokens are able to be automatically rotated via a rotation policy, limiting the amount of time a leaked or stolen key is useful to an adversary.
- Security layer: Storing keys, secrets, and Pangea tokens in the Vault provides a layer of security, reducing exposure and the likelihood of being stolen without losing any access or functionality.
- Reduced code maintenance: Secrets and Keys can be accessed by ID, so no code change is required when a key is rotated.
- Grace period: When a Vault item is rotated, the former token remains usable for a set amount of time. This allows existing code that utilized the former token to continue working while the code is updated to the new token.
Vault Concepts
The Vault service contains Vault items of key, secret, or Pangea API token types. All Vault items share some universal properties and functionality while providing unique capabilities to each type.
Vault Items
Everything stored in the Vault service is, at a high level, a Vault item with a base set of functionality and capabilities. All Vault items enable you to configure and manage versions, metadata, state, and deletion of that Vault item.
Versions
All new Vault items are created with a v1 version. As Vault items are rotated, new versions are created and accessible as the current version of the Vault item. Each version of a Vault item has a Version state, which dictates capabilities available to that Vault item version.
There is one active state and several deactivated states. Vault items in deactivated states behave differently depending on their type.
A key in a deactivated state may be used only for processing (decryption and verification).
A secret or Pangea Token in a deactivated may not have its secret material accessible.
Version States
Active
All capabilities of the Vault item are enabled. The current Vault item version will default to the Active state.
Deactivated
This is the default state assigned to a version as the result of rotation. It indicates that the Vault item was retired under normal conditions due to rotation.
Suspended
This state should be used if a Vault item is suspected of being leaked or breached but not confirmed.
Compromised
This state should be used only in case of a confirmed breach or leakage. Moving a Vault item version to the compromised state will require you to define a timeframe for destroying the Vault item material and transitioning to the destroyed state.
Destroyed
Destroyed Vault items no longer have any secret or key material available; only metadata remains.
Allowed version state transitions
It is essential to understand that there are restrictions on Vault item transitions. For instance, a Vault item moved to the compromised state can never be moved back to an active state.
This diagram is an overview of the various states and transitions that can be completed in Vault.
Vault item lifecycle
Vault items begin as Pre-activated.
-
An item in Pre-activated state can move to Active state when it is ready for use.
-
The item moves from Pre-activated to Destroyed if it is no longer necessary.
-
The item moves from Pre-activated to Compromised when it has been compromised.
-
Active state items transition to Destroyed when they expire, are replaced, or are no longer required.
-
Items can transition from Active to Deactivated when they are no longer required.
-
Items shall transition from Deactivated to Compromised when their integrity has been, or is suspected to have been compromised.
-
An item goes from Active to Compromised when its integrity is either known or suspected of being compromised.
-
An item can transition from Active to Suspended if it is not used for a certain amount of time. A suspended key is eligible to be transitioned back to Active.
-
Compromised items can only transition to Destroyed.
-
When a Suspended item is confirmed or suspected of being compromised, it shall transition to Compromised.
-
An item can transition from Suspended to Deactivated if the suspension is no longer necessary, but it is found to not be compromised.
-
Suspended items can be transitioned to Destroyed if they are no longer required.
-
A Deactivated item can be transitioned to Destroyed if it is no longer required.
Vault items can also be rotated and versioned without modifying the code. For more information on rotation and Vault item versions, see rotation.
Metadata
Vault items allow you to store user-defined tags and key-value pairs used to help you identify the Vault item and its purpose.
State
A Vault item can be in one of the following states - enabled or disabled. The state of a Vault item affects all versions of the Vault item.
Expiration
You can configure an expiration date when creating or updating a Vault item. When a Vault item expires, it is automatically moved to the disabled state. A Vault item may be "unexpired" by transitioning the item back to an enabled state. Doing so will clear the expiration date field if the expiration date has already been exceeded.
Rotation
Rotation is the process of generating a new version of Vault item by providing or generating new key or secret material. All Vault items have a "current" version, starting with v1 when first created. As Vault items rotate, new versions are created, replacing the current version with v2 and so on. Rotation allows developers to access new key and secret material by ID, meaning their code does not have to change when Vault items are rotated. Regular rotation of secrets and keys is a best practice and often a compliance mandate, as it minimizes the amount of time that a leaked key or secret could be usable by an adversary.
Keys
Vault supports the generation and import of symmetric and asymmetric key pairs. Storing a key in the Vault service prohibits anyone from ever accessing private key material. The Vault service performs cryptographic operations on your developers' behalf, ensuring that your private key material is never exposed outside of the service.
Secrets
Secrets provide users with a text blob to store any secret information developers require - most commonly, user credentials or API keys for use in application code. Storing secrets in the Vault allows developers to securely access and utilize confidential material in their code without hard-coding it in the application, reducing the risk of leakage or breach.
Pangea API Tokens
Pangea API Tokens are a special type of secret that can be stored in the Vault Service. Storing a Pangea API Token in the Vault allows you to rotate your Pangea tokens through manual or scheduled rotation. Rotation will result in the automatic generation of a new Pangea Token with the same permissions as the previous token; it will also destroy the old token. When a Pangea Token is rotated, it will automatically be moved to the destroyed state.
Additionally, Pangea Tokens support a unique feature - Grace Period.
Grace period
A grace period defines a period after rotation when a new Pangea Token is generated, but the old token has not been destroyed. The purpose of a grace period is to allow code that relies on the rotated token to continue to function for some time before retrieving the new token from the Vault service.
Example with a grace period set to 8 hours:
- Token_1 is stored in the Pangea Vault as Vault_Item_1.
- Vault_Item_1 has a rotation policy assigned to occur every 1 month.
- 1 month passes and Vault_Item_1 generates a new Pangea API token, Token_2, matching the permissions of Token_1.
- Token_2 is now stored as version 2, the current version, in Vault_Item_1.
- Token_1 is still usable.
- 8 hours after rotation, the Vault service destroys Token_1; Token_1 is no longer usable.
Was this article helpful?