Overview
Read about the basics of Vault
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 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.
Vault Concepts
The Vault service contains Vault Items of either type key, secret, or Pangea API token. 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 States
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 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.
- Active -> any
- Deactivated -> any
- Suspended -> any
- Compromised -> Destroyed
- Destroyed -> none
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.
Manual rotation
All Vault Items can be manually rotated. Manual rotation requires you to provide the Vault Item material and the target state to which the current version of the Vault Item should transition. The default target state is "deactivated."
Rotation Policies
Rotation Policies allow you to configure the automatic rotation of Vault Items at scheduled intervals. Once configured, a Rotation Policy will automatically generate the new Vault Item material as part of the rotation process. Rotation Policies are available to Keys and Pangea API tokens only.
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.
Vault Keys support the following capabilities:
- Symmetric and asymmetric keys
- Pangea-generated keys
- Importing customer keys
- Manual rotation
- Automated rotation policies
- Versioning
- Cryptographic Operations
- Encrypt/Decrypt
- Sign/Verify
- Sign/Verify of JWTs
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.
Secrets support the following:
- Import of secret material
- Secure retrieval and access of secret material
- Manual rotation
- Versioning
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.
Pangea API Tokens support:
- Import of existing Pangea Tokens
- Creation of new Pangea tokens (UI only)
- Manual rotation
- Automated rotation policy
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?