From 649f403ef2b60a135e5cfa3ca0f7d0cc0432ef58 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 6 Apr 2015 20:46:11 -0700 Subject: [PATCH] website: more getting started --- .../getting-started/first-secret.html.md | 110 ++++++++++++++++ .../getting-started/secret-backends.html.md | 119 ++++++++++++++++++ website/source/layouts/intro.erb | 8 ++ 3 files changed, 237 insertions(+) create mode 100644 website/source/intro/getting-started/first-secret.html.md create mode 100644 website/source/intro/getting-started/secret-backends.html.md diff --git a/website/source/intro/getting-started/first-secret.html.md b/website/source/intro/getting-started/first-secret.html.md new file mode 100644 index 0000000000..35a66b80de --- /dev/null +++ b/website/source/intro/getting-started/first-secret.html.md @@ -0,0 +1,110 @@ +--- +layout: "intro" +page_title: "Your First Secret" +sidebar_current: "gettingstarted-firstsecret" +description: |- + With the Vault server running, let's read and write our first secret. +--- + +# Your First Secret + +Now that the dev server is up and running, let's get straight to it and +read and write our first secret. + +One of the core features of Vault is the ability to read and write +arbitrary secrets securely. On this page, we'll do this using the CLI, +but there is also a complete +[HTTP API](#) +that can be used to programmatically do anything with Vault. + +Secrets written to Vault are encrypted and then written to the backend +storage. For our dev server, backend storage is in-memory, but in production +this would more likely be on disk or in [Consul](https://www.consul.io). +Vault encrypts the value before it is ever handed to the storage driver. +The backend storage mechanism _never_ sees the unencrypted value and doesn't +have the means necessary to decrypt it without Vault. + +## Writing a Secret + +Let's start by writing a secret. This is done very simply with the +`vault write` command, as shown below: + +``` +$ vault write secret/hello value=world +Success! Data written to: secret/hello +``` + +This writes the pair `value=world` to the path `secret/hello`. We'll +cover paths in more detail later, but for now it is important that the +path is prefixed with `secret/`, otherwise this example won't work. The +`secret/` prefix is where arbitrary secrets can be read and written. + +You can even write multiple pieces of data, if you want: + +``` +$ vault write secret/hello value=world excited=yes +Success! Data written to: secret/hello +``` + +`vault write` is a very powerful command. In addition to writing data +directly from the command-line, it can read values and keypairs from +stdin as well as files. For more information, see the +[vault write documentation](#). + +## Reading a Secret + +As you might expect, secrets can be read with `vault read`: + +``` +$ vault read secret/hello +Key Value +excited yes +value world +``` + +As you can see, the values we wrote are given back to us. Vault read +the data from storage and decrypted it. +The output format is purposefully whitespace separated to make it easy +to pipe into a tool like `awk`. + +In addition to the tabular format, if you're working with machines or +a tool like `jq`, you can output the data in JSON format: + +``` +$ vault read -format=json secret/hello +{ + "renewable": false, + "lease_duration": 2592000, + "data": { + "excited": "yes", + "value": "world" + } +} +``` + +This contains some extra information, but you can see our data mirrored +here as well. The JSON output is very useful for scripts. For example below +we use the `jq` tool to extract the "excited" value: + +``` +$ vault read -format=json secret/hello | jq -r .data.excited +yes +``` + +## Deleting a Secret + +Now that we've learned how to read and write a secret, let's go ahead +and delete it. We can do this with `vault delete`: + +``` +$ vault delete secret/hello +'secret/hello' successfully deleted. +``` + +## Next + +In this section we learned how to use the powerful CRUD features of +Vault to store arbitrary secrets. On its own this is already a useful +but basic feature. + +Next, we'll learn the basics about [secret backends](/intro/getting-started/secret-backends.html). diff --git a/website/source/intro/getting-started/secret-backends.html.md b/website/source/intro/getting-started/secret-backends.html.md new file mode 100644 index 0000000000..c38540f588 --- /dev/null +++ b/website/source/intro/getting-started/secret-backends.html.md @@ -0,0 +1,119 @@ +--- +layout: "intro" +page_title: "Secret Backends" +sidebar_current: "gettingstarted-secretbackends" +description: |- + Secret backends are what create, read, update, and delete secrets. +--- + +# Secret Backends + +Previously, we saw how to read and write arbitrary secrets to Vault. +To do this, we used the `secret/` prefix. This prefix specifies the +_secret backend_ to use, and Vault defaults to mounting the _generic_ +backend to `secret/`. The generic backend reads and writes raw data to +the backend storage. + +Vault supports other backends in addition to "generic", and this feature +in particular is what makes Vault unique. For example, the "aws" backend +generates AWS access keys dynamically, on demand. Another example -- +this time of a backend that doesn't yet exist -- is a backend that +reads and writes data directly to an +[HSM](http://en.wikipedia.org/wiki/Hardware_security_module). +As Vault matures, more and more backends will be added. + +To represent backends, Vault behaves much like a filesystem: backends +are _mounted_ at specific paths. For example, the "generic" backend is +_mounted_ at the `secret/` prefix. + +On this page, we'll learn about the mount system and the operations +that can be performed with them. We do this as prerequisite knowledge +to the next page, where we'll create dynamic secrets. + +## Mount a Backend + +To start, let's mount another "generic" backend. Just like a normal +filesystem, Vault can mount a backend multiple times at different +mount points. This is useful if you want different access control policies +(covered later) or configurations for different paths. + +To mount the backend: + +``` +$ vault mount generic +Successfully mounted 'generic' at 'generic'! +``` + +By default, the mount point will be the same name as the backend. This +is because 99% of the time, you don't want to customize this mount point. +In this example, we mounted the "generic" backend at `generic/`. + +You can inspect mounts using `vault mounts`: + +``` +$ vault mounts +Path Type Description +generic/ generic +secret/ generic generic secret storage +sys/ system system endpoints used for control, policy and debugging +``` + +You can see the `generic/` path we just mounted, as well as the built-in +secret path. You can also see the `sys/` path. We won't cover this in the +getting started guide, but this mount point is used to interact with +the Vault core system. + +Spend some time reading and writing secrets to the new mount point to +convince yourself it works. As a bonus, write to the `secret/` endpoint +and observe that those values unavailable via `generic/`: they share the +same backend, but do not share any data. In addition to this, backends +(of the same type or otherwise) _cannot_ access the data of other backends; +they can only access data within their mount point. + +## Unmount a Backend + +Once you're sufficiently convinced mounts behave as you expect, you can +unmount it. When a backend is unmounted, all of its secrets are revoked +and its data is deleted. If either of these operations fail, the backend +remains mounted. + +``` +$ vault unmount generic/ +Successfully unmounted 'generic/'! +``` + +In addition to unmounting, you can _remount_ a backend. Remounting a +backend changes its mount point. This is still a disruptive command: the +stored data is retained, but all secrets are revoked since secrets are +closely tied to their mount paths. + +## What is a Secret Backend? + +Now that you've mounted and unmounted a backend, you might wonder: +"what is a secret backend? what is the point of this mounting system?" + +Vault behaves a lot like a [virtual filesystem](http://en.wikipedia.org/wiki/Virtual_file_system). +The read/write/delete operations are forwarded to the backend, and the +backend can choose to react to these operations however it wishes. +For example, the "generic" backend simply passes this through to the +storage backend (after encrypting data first). + +However, the "aws" backend (which you'll see soon), will read/write IAM +policies and access tokens. So, while you might do a `vault read aws/deploy`, +this isn't readnig from any _physical_ path "aws/deploy". Instead, the AWS +backend is dynamically generating an access key based on the "deploy" policy. + +This abstraction is incredibly powerful. It lets Vault interface directly +with physical systems such as the backend as well as things such as SQL +databases, HSMs, etc. But in addition to these physical systems, Vault +can interact with more unique environments: AWS IAM, dynamic SQL user creation, +etc. all using the same read/write interface. + +## Next + +You now know about secret backends and how to operate on the mount table. +This is important knowledge to move forward and learn about other secret +backends. + +Next, we'll use the +[AWS backend to generate dynamic secrets](/intro/getting-started/dynamic-secrets.html). diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index b19d91aa32..478ef580b4 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -46,6 +46,14 @@ Your First Secret + > + Secret Backends + + + > + Dynamic Secrets + + > Next Steps