From 3cb1d4e844e0022a91e97c8acfbd2d23b328407a Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Thu, 9 Apr 2015 19:23:50 -0700 Subject: [PATCH] website: nit picking --- .../docs/internals/architecture.html.md | 23 +++++++++++-------- website/source/docs/internals/index.html.md | 3 ++- website/source/layouts/docs.erb | 4 ++-- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/website/source/docs/internals/architecture.html.md b/website/source/docs/internals/architecture.html.md index c25fbd035b..fd67554e6c 100644 --- a/website/source/docs/internals/architecture.html.md +++ b/website/source/docs/internals/architecture.html.md @@ -15,22 +15,25 @@ build a mental model of how it works, this page documents the system architectur of Vault. You don't 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. +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. # Glossary -Before describing the architecture, we provide a glossary of terms to help clarify what is being discussed: +Before describing the architecture, we provide a glossary of terms to help +clarify what is being discussed: -* Storage Backend - A storage backend is responsible for durable storage of _encrypted_ data. +* **Storage Backend** - A storage backend is responsible for durable storage of _encrypted_ data. backends are not trusted by Vault and are only expected to provide durability. The storage backend is configured when starting the Vault server. -* Barrier - The barrier is cryptographic steel and concrete around the Vault. All data that +* **Barrier** - The barrier is cryptographic steel and concrete around the Vault. All data that flows between Vault and the Storage Backend passes through the barrier. The barrier ensures that only encrypted data is written out, and that data is verified and decrypted on the way in. Much like a bank vault, the barrier must be "unsealed" before anything inside can be accessed. -* Secret Backend - A secret backend is responsible for managing secrets. Simple secret backends +* **Secret Backend** - A secret backend is responsible for managing secrets. Simple secret backends like the "generic" backend simply return the same secret when queried. Some backends support using policies to dynamically generate a secret each time they are queried. This allows for unique secrets to be used which allows Vault to do fine-grained revocation and policy updates. @@ -38,23 +41,23 @@ Before describing the architecture, we provide a glossary of terms to help clari is read, a new MySQL user/password pair will be generated with a limited set of privileges for the web server. -* Audit Backend - An audit backend is responsible for managing audit logs. Every request to Vault +* **Audit Backend** - An audit backend is responsible for managing audit logs. Every request to Vault and response from Vault goes through the configured audit backends. This provides a simple way to integrate Vault with multiple audit logging destinations of different types. -* Credential Backend - A credential backend is used to authenticate users or applications which +* **Credential Backend** - A credential backend is used to authenticate users or applications which are connecting to Vault. Once authenticated, the backend returns the list of applicable policies which shoud be applied. Vault takes an authenticated user and returns a client token that can be used for future requests. As an example, the `user-password` backend uses a username and password to authenticate the user. Alternatively, the `github` backend allows users to authenticate via GitHub. -* Client Token - A client token is a conceptually similar to a session cookie on a web site. +* **Client Token** - A client token is a conceptually similar to a session cookie on a web site. Once a user authenticates, Vault returns a client token which is used for future requests. The token is used by Vault to verify the identity of the client and to enforce the applicable ACL policies. -* Secret - A secret is the term for anything returned by Vault which contains confidential +* **Secret** - A secret is the term for anything returned by Vault which contains confidential or cryptographic material. Not all everything returned by Vault is a secret, for example system configuration, status information, or backend policies are not considered Secrets. Secrets always have an associated lease. This means clients cannot assume that the secret @@ -63,7 +66,7 @@ Before describing the architecture, we provide a glossary of terms to help clari between Vault and it's clients is critical, as it allows for changes in keys and policies without manual intervention. -* Server - Vault depends on a long-running instance which operates as a server. +* **Server** - Vault depends on a long-running instance which operates as a server. The Vault server provides an API which clients interact with and manages the interaction between all the backends, ACL enforcement, and secret lease revocation. Having a server based architecture decouples clients from the security keys and policies, diff --git a/website/source/docs/internals/index.html.md b/website/source/docs/internals/index.html.md index 53a52d9da1..c15aedaf46 100644 --- a/website/source/docs/internals/index.html.md +++ b/website/source/docs/internals/index.html.md @@ -13,4 +13,5 @@ details of how Vault functions, it's architecture and security properties. -> **Note:** Knowledge of Vault internals is not required to use Vault. If you aren't interested in the internals -of Vault, you may safely skip this section. +of Vault, you may safely skip this section. If you're operating Vault, +we recommend understanding the internals. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index a9720abd16..ed93d88fca 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -11,9 +11,9 @@ + + > Commands (CLI)