website: leasing

website/source/docs/concepts/lease.html.md

@@ -0,0 +1,75 @@
+---
+layout: "docs"
+page_title: "Lease, Renew, and Revoke"
+sidebar_current: "docs-concepts-lease"
+description: |-
+  Vault provides a lease with every secret. When this lease is expired, Vault will revoke that secret.
+---
+
+# Lease, Renew, and Revoke
+
+With every secret and authentication token, Vault provides a _lease_:
+an amount of time that Vault promises that the data will be valid for.
+Once the lease is up, Vault can automatically revoke the data, and the
+consumer of the secret can no longer be certain that it is valid.
+
+The benefit should be clear: consumers of secrets need to check in with
+Vault routinely to either renew the lease (if allowed) or request a
+replacement secret. This makes the Vault audit logs more valuable and
+also makes key rolling a lot easier.
+
+All secrets in Vault are required to have a lease. Even if the data is
+meant to be valid for eternity, a lease is required to force the consumer
+to check in routinely.
+
+In addition to renewals, a lease can be _revoked_. When a lease is revoked,
+it invalidates that secret immediately and prevents any further renewals.
+For
+[dynamic secrets](#),
+the secrets themselves are often immediately disabled. For example, with
+the
+[AWS secret backend](/docs/secrets/aws/index.html), the access keys will
+be deleted from AWS the moment a secret is revoked. This renders the access
+keys invalid from that point forward.
+
+Revocation can happen manually via the API or `vault revoke`, or automatically
+by Vault. When a lease is expired, Vault will automatically revoke that
+lease.
+
+## Lease IDs
+
+When reading a secret, such as via `vault read`, Vault always returns
+a `lease_id`. This is the ID used with commands such as `vault renew` and
+`vault revoke` to manage the lease of the secret.
+
+## Lease Durations and Renewal
+
+Along with the lease ID, a _lease duration_ can be read. The lease duration
+is the time in seconds that the lease is valid for. A consumer of this
+secret must renew the lease within that time.
+
+When renewing the lease, the user can request a specific amount of time
+from now to extend the lease. For example: `vault renew my-lease-id 3600`
+would request to extend the lease of "my-lease-id" by 1 hour (3600 seconds).
+
+The requested increment is completely advisory. The backend in charge
+of the secret can choose to completely ignore it. For most secrets, the
+backend does its best to respect the increment, but often limits it to
+ensure renewals every so often.
+
+As a result, the return value of renews should be carefully inspected
+to determine what the new lease is.
+
+## Prefix-based Revocation
+
+In addition to revoking a single secret, operators with proper access
+control can revoke multiple secrets based on their lease ID prefix.
+
+Lease IDs are structured in a way that their prefix is always the path
+where the secret was requested from. This lets you revoke trees of
+secrets. For example, to revoke all AWS access keys, you can do
+`vault revoke -prefix aws/`.
+
+This is very useful if there is an intrustion within a specific system:
+all secrets of a specific backend or a certain configured backend can
+be revoked quickly and easily.

website/source/layouts/docs.erb

@@ -34,7 +34,9 @@
 							<a href="/docs/concepts/seal.html">Seal/Unseal</a>
 						</li>
 
-
+						<li<%= sidebar_current("docs-concepts-lease") %>>
+							<a href="/docs/concepts/lease.html">Lease, Renew, and Revoke</a>
+						</li>
 					</ul>
 				</li>