luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity

vault documentation: updated architecture doc page (#16569)

Browse source 
* updated content

* fixed spelling error

* Update website/content/docs/internals/architecture.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/internals/architecture.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/internals/architecture.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/internals/architecture.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* Update website/content/docs/internals/architecture.mdx

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>

* updated content

* italicized barrier

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>
This commit is contained in:
Loann Le 2022-08-04 11:29:31 -07:00 committed by GitHub
parent e2d3846a25
commit 85539da102
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 40 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

112
website/content/docs/internals/architecture.mdx
View file

@ -6,42 +6,28 @@ description: Learn about the internal architecture of Vault.
# Architecture # Architecture
Vault is a complex system that has many different pieces. To help both users and Vault is an intricate system with numerous distinct components. This page details the system architecture and hopes to assist Vault users and developers to build a mental model while understanding the theory of operaton.
developers of Vault build a mental model of how it works, this page documents
the system architecture.
~> **Advanced Topic!** This page covers technical details of Vault. You don't ~> **Note:** This page covers the technical details of Vault. The descriptions and elements contained within are for users that wish to learn about Vault without having to reference the source code. Although not required, we encourage all users and operators to review the provided information before using Vault due to its significance in an environment.
need to understand these details to effectively use Vault. The details are
documented here for those who wish to learn about them without having to go
spelunking through the source code. However, if you're an operator of Vault, we
recommend learning about the architecture due to the importance of Vault in an
environment.
# High-Level Overview # High-Level Overview
A very high level overview of Vault looks like this: The diagram below illustrates the intricacies and distinct components of Vault.
[![Architecture Overview](/img/layers.png)](/img/layers.png) [![Architecture Overview](/img/layers.png)](/img/layers.png)
Let's begin to break down this picture. There is a clear separation of Vault’s encryption layer, referred to as the _barrier_, is responsible for encrypting and decrypting Vault data. When the Vault server starts, it writes data to its storage backend. Since the storage backend resides outside the barrier, it’s considered untrusted so Vault will encrypt the data before it sends them to the storage backend. This mechanism ensures that if an unauthorized attacker attempts to access the storage backend, the data cannot be compromised since it remains encrypted, until Vault decrypts the data. The storage backend provides a durable data persistent layer where data is secured and available across server restarts.
components that are inside or outside of the security barrier. Only the storage
backend and the HTTP API are outside, all other components are inside the
barrier.
The storage backend is untrusted and is used to durably store encrypted data. When a Vault server is started, it begins in a _sealed_ state. Before any
When the Vault server is started, it must be provided with a storage backend so operation can be performed on Vault, it must be _unsealed_. This is done by
that data is available across restarts. The HTTP API similarly must be started providing the unseal keys. During the Vault initialization, it generates an
by the Vault server on start so that clients can interact with it. encryption key, which is used to protect all Vault data. This key is protected by
a root key that is stored alongside all other Vault data, but is encrypted by another mechanism: the unseal key.
When a Vault server is started, it starts in a _sealed_ state. Before any
operation can be performed on the Vault, it must be _unsealed_. This is done by
providing the unseal keys. When the Vault is initialized, it generates an
encryption key which is used to protect all Vault data. This key is protected by
a root key. The root key is stored alongside all other Vault data, but is encrypted by yet another mechanism: the unseal key.
By default, Vault uses [Shamir's Secret By default, Vault uses [Shamir's Secret
Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the Sharing](https://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing) to split the
unseal key into a configured number of shards (referred as key shares or unseal unseal key into a configured number of shards (key shares or unseal
keys). A certain threshold of shards is required to reconstruct the unseal key, keys). A precise number of shards are required to reconstruct the unseal key,
which is then used to decrypt the Vault's root key. which is then used to decrypt the Vault's root key.
![Unseal keys](/img/vault-shamir-seal.png) ![Unseal keys](/img/vault-shamir-seal.png)
@ -49,73 +35,53 @@ which is then used to decrypt the Vault's root key.
Refer to the [Seal/Unseal](/docs/concepts/seal#seal-unseal) documentation for Refer to the [Seal/Unseal](/docs/concepts/seal#seal-unseal) documentation for
further details. further details.
The number of shares and the minimum threshold required can both be specified. The number of shares and the minimum number of shards required can both be specified.
Shamir's technique can be disabled, and the root key can be used directly for Shamir's technique can be disabled, and the root key can be used directly for
unsealing. Once Vault retrieves the encryption key, it is able to decrypt the unsealing. Once Vault retrieves the encryption key, it decrypts the
data in the storage backend, and enters the _unsealed_ state. Once unsealed, data in the storage backend, and enters the _unsealed_ state. Once unsealed,
Vault loads all of the configured audit devices, auth methods, and secrets Vault loads the configured audit devices, auth methods, and secrets
engines. engines.
-> The default Vault configuration uses a Shamir seal; however, Vault can be [auto ~> **Note:** The default Vault configuration uses a Shamir seal; however, Vault can be [auto
unseal](/docs/concepts/seal#auto-unseal) by a trusted cloud key management unseal](/docs/concepts/seal#auto-unseal) by a trusted cloud key management
system (KMS) or hardware security module (HSM) to increase security. system (KMS) or hardware security module (HSM) to increase security.
The configuration of those audit devices, auth methods, and secrets engines must The configuration of the audit devices, auth methods, and secrets engines are security sensitive that they are stored in Vault. Users with permissions can modify them and cannot be specified outside of the barrier. By storing them in Vault, changes are protected by the ACL system and tracked by audit logs.
be stored in Vault since they are security sensitive. Only users with the
correct permissions should be able to modify them, meaning they cannot be
specified outside of the barrier. By storing them in Vault, any changes to them
are protected by the ACL system and tracked by audit logs.
After the Vault is unsealed, requests can be processed from the HTTP API to the Requests may be processed from the HTTP API to the core once Vault is unsealed.
Core. The core is used to manage the flow of requests through the system, The core manages the flow of requests through the system,
enforce ACLs, and ensure audit logging is done. enforce ACLs, and ensure audit logging is done.
When a client first connects to Vault, it needs to authenticate. Vault provides When a client first connects to Vault, the client needs to authenticate. Vault provides
configurable auth methods providing flexibility in the authentication mechanism configurable auth methods and offers flexibility within the authentication mechanism
used. Human friendly mechanisms such as username/password or GitHub might be used. Mechanisms such as username/password or GitHub may be
used for operators, while applications may use public/private keys or tokens to used for operators, while applications may use public/private keys or tokens to
authenticate. An authentication request flows through core and into an auth authenticate. An authentication request that flows through the core and into an auth
method, which determines if the request is valid and returns a list of method determines if the request is valid and returns a list of
associated policies. associated policies.
Policies are just a named ACL rule. For example, the "root" policy is built-in Policies are just a named ACL rule. For example, the "root" policy is built-in
and permits access to all resources. You can create any number of named policies and permits access to all resources. You may create any number of named policies
with fine-grained control over paths. Vault operates exclusively in a allowed-access with fine-grained control over paths. Vault operates in an allowed-access mode, meaning the action is not allowed unless access is granted via a policy explicitly. Since a user may have multiple policies associated, actions are allowed when policy permits. Policies are stored and managed by an internal
mode, meaning that unless access is explicitly granted via a policy, the action policy store. This internal store is affected through the system backend,
is not allowed. Since a user may have multiple policies associated, an action is
allowed if any policy permits it. Policies are stored and managed by an internal
policy store. This internal store is manipulated through the system backend,
which is always mounted at `sys/`. which is always mounted at `sys/`.
Once authentication takes place and an auth method provides a set of applicable Once authentication takes place and an auth method provides a set of applicable
policies, a new client token is generated and managed by the token store. This policies, a new client token is generated and managed by the token store. This
client token is sent back to the client, and is used to make future requests. client token is used to make future requests.
This is similar to a cookie sent by a website after a user logs in. The client This token method is similar to a cookie sent by a website when a user logs in. Depending on the auth method configuration, the client
token may have a lease associated with it depending on the auth method token may have a lease associated with it, and may need to be renewed periodically to avoid invalidation.
configuration. This means the client token may need to be periodically renewed
to avoid invalidation.
Once authenticated, requests are made providing the client token. The token is Once authenticated, requests are made by providing the client token. The client token is
used to verify the client is authorized and to load the relevant policies. The used to verify the client, ensuring they are authorized while loading the relevant policies. The
policies are used to authorize the client request. The request is then routed to policies are used to authorize the client request. The request is then routed to the secrets engine, which is processed depending on its type. When the secrets engine returns the secret, the core registers it with the expiration manager and attaches a lease ID. Clients use the lease ID to renew or revoke their
the secrets engine, which is processed depending on its type. If the secrets secret. The expiration manager automatically revokes the secret if a client allows the lease to expire.
engine returns a secret, the core registers it with the expiration manager and
attaches a lease ID. The lease ID is used by clients to renew or revoke their
secret. If a client allows the lease to expire, the expiration manager
automatically revokes the secret.
The core handles logging of requests and responses to the audit broker, which The core logs requests and responses to the audit broker, distributing the requests to all configured audit devices. Outside of the request
fans the request out to all the configured audit devices. Outside of the request flow, the core performs specific background activities. Lease management is critical, allowig expired client tokens or secrets to be revoked automatically. Additionally, Vault handles specific partial-failure cases by using write-ahead logging with a rollback manager. This is managed transparently within the core and is not user-visible.
flow, the core performs certain background activity. Lease management is
critical, as it allows expired client tokens or secrets to be revoked
automatically. Additionally, Vault handles certain partial failure cases by
using write ahead logging with a rollback manager. This is managed transparently
within the core and is not user visible.
# Getting in Depth # Resources
This has been a brief high-level overview of the architecture of Vault. There - To learn more about each components and sub-systems within Vault, select a topic from the left-navigation menu.
are more details available for each of the sub-systems. - For in depth details, consult the code.
- To get started with Vault, try out our [Getting Started](https://learn.hashicorp.com/collections/vault/getting-started) tutorial.
For other details, either consult the code or reach out to the
mailing list.

5
website/content/docs/internals/index.mdx
View file

@ -11,7 +11,4 @@ description: >-
This section covers the internals of Vault and explains the technical This section covers the internals of Vault and explains the technical
details of how Vault functions, its architecture and security properties. details of how Vault functions, its architecture and security properties.
-> **Note:** Knowledge of Vault internals is not -> **Note:** Knowledge of Vault internals is recommended but not required to use Vault. However, if you're operating Vault, we recommend understanding the internals.
required to use Vault. If you aren't interested in the internals
of Vault, you may safely skip this section. If you're operating Vault,
we recommend understanding the internals.