1 files changed, 611 insertions, 0 deletions
diff --git a/vendor/github.com/hashicorp/vault/api/SPEC.md b/vendor/github.com/hashicorp/vault/api/SPEC.md
new file mode 100644
index 0000000..15345f3
--- /dev/null
+++ b/vendor/github.com/hashicorp/vault/api/SPEC.md
@@ -0,0 +1,611 @@
+FORMAT: 1A
+
+# vault
+
+The Vault API gives you full access to the Vault project.
+
+If you're browsing this API specifiction in GitHub or in raw
+format, please excuse some of the odd formatting. This document
+is in api-blueprint format that is read by viewers such as
+Apiary.
+
+## Sealed vs. Unsealed
+
+Whenever an individual Vault server is started, it is started
+in the _sealed_ state. In this state, it knows where its data
+is located, but the data is encrypted and Vault doesn't have the
+encryption keys to access it. Before Vault can operate, it must
+be _unsealed_.
+
+**Note:** Sealing/unsealing has no relationship to _authentication_
+which is separate and still required once the Vault is unsealed.
+
+Instead of being sealed with a single key, we utilize
+[Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
+to shard a key into _n_ parts such that _t_ parts are required
+to reconstruct the original key, where `t <= n`. This means that
+Vault itself doesn't know the original key, and no single person
+has the original key (unless `n = 1`, or `t` parts are given to
+a single person).
+
+Unsealing is done via an unauthenticated
+[unseal API](#reference/seal/unseal/unseal). This API takes a single
+master shard and progresses the unsealing process. Once all shards
+are given, the Vault is either unsealed or resets the unsealing
+process if the key was invalid.
+
+The entire seal/unseal state is server-wide. This allows multiple
+distinct operators to use the unseal API (or more likely the
+`vault unseal` command) from separate computers/networks and never
+have to transmit their key in order to unseal the vault in a
+distributed fashion.
+
+## Transport
+
+The API is expected to be accessed over a TLS connection at
+all times, with a valid certificate that is verified by a well
+behaved client.
+
+## Authentication
+
+Once the Vault is unsealed, every other operation requires
+authentication. There are multiple methods for authentication
+that can be enabled (see
+[authentication](#reference/authentication)).
+
+Authentication is done with the login endpoint. The login endpoint
+returns an access token that is set as the `X-Vault-Token` header.
+
+## Help
+
+To retrieve the help for any API within Vault, including mounted
+backends, credential providers, etc. then append `?help=1` to any
+URL. If you have valid permission to access the path, then the help text
+will be returned with the following structure:
+
+        {
+            "help": "help text"
+        }
+
+## Error Response
+
+A common JSON structure is always returned to return errors:
+
+        {
+            "errors": [
+                "message",
+                "another message"
+            ]
+        }
+
+This structure will be sent down for any non-20x HTTP status.
+
+## HTTP Status Codes
+
+The following HTTP status codes are used throughout the API.
+
+- `200` - Success with data.
+- `204` - Success, no data returned.
+- `400` - Invalid request, missing or invalid data.
+- `403` - Forbidden, your authentication details are either
+   incorrect or you don't have access to this feature.
+- `404` - Invalid path. This can both mean that the path truly
+   doesn't exist or that you don't have permission to view a
+   specific path. We use 404 in some cases to avoid state leakage.
+- `429` - Rate limit exceeded. Try again after waiting some period
+   of time.
+- `500` - Internal server error. An internal error has occurred,
+   try again later. If the error persists, report a bug.
+- `503` - Vault is down for maintenance or is currently sealed.
+   Try again later.
+
+# Group Initialization
+
+## Initialization [/sys/init]
+### Initialization Status [GET]
+Returns the status of whether the vault is initialized or not. The
+vault doesn't have to be unsealed for this operation.
+
++ Response 200 (application/json)
+
+        {
+            "initialized": true
+        }
+
+### Initialize [POST]
+Initialize the vault. This is an unauthenticated request to initially
+setup a new vault. Although this is unauthenticated, it is still safe:
+data cannot be in vault prior to initialization, and any future
+authentication will fail if you didn't initialize it yourself.
+Additionally, once initialized, a vault cannot be reinitialized.
+
+This API is the only time Vault will ever be aware of your keys, and
+the only time the keys will ever be returned in one unit. Care should
+be taken to ensure that the output of this request is never logged,
+and that the keys are properly distributed.
+
+The response also contains the initial root token that can be used
+as authentication in order to initially configure Vault once it is
+unsealed. Just as with the unseal keys, this is the only time Vault is
+ever aware of this token.
+
++ Request (application/json)
+
+        {
+            "secret_shares": 5,
+            "secret_threshold": 3,
+        }
+
++ Response 200 (application/json)
+
+        {
+            "keys": ["one", "two", "three"],
+            "root_token": "foo"
+        }
+
+# Group Seal/Unseal
+
+## Seal Status [/sys/seal-status]
+### Seal Status [GET]
+Returns the status of whether the vault is currently
+sealed or not, as well as the progress of unsealing.
+
+The response has the following attributes:
+
+- sealed (boolean) - If true, the vault is sealed. Otherwise,
+    it is unsealed.
+- t (int) - The "t" value for the master key, or the number
+    of shards needed total to unseal the vault.
+- n (int) - The "n" value for the master key, or the total
+    number of shards of the key distributed.
+- progress (int) - The number of master key shards that have
+    been entered so far towards unsealing the vault.
+
++ Response 200 (application/json)
+
+        {
+            "sealed": true,
+            "t": 3,
+            "n": 5,
+            "progress": 1
+        }
+
+## Seal [/sys/seal]
+### Seal [PUT]
+Seal the vault.
+
+Sealing the vault locks Vault from any future operations on any
+secrets or system configuration until the vault is once again
+unsealed. Internally, sealing throws away the keys to access the
+encrypted vault data, so Vault is unable to access the data without
+unsealing to get the encryption keys.
+
++ Response 204
+
+## Unseal [/sys/unseal]
+### Unseal [PUT]
+Unseal the vault.
+
+Unseal the vault by entering a portion of the master key. The
+response object will tell you if the unseal is complete or
+only partial.
+
+If the vault is already unsealed, this does nothing. It is
+not an error, the return value just says the vault is unsealed.
+Due to the architecture of Vault, we cannot validate whether
+any portion of the unseal key given is valid until all keys
+are inputted, therefore unsealing an already unsealed vault
+is still a success even if the input key is invalid.
+
++ Request (application/json)
+
+        {
+            "key": "value"
+        }
+
++ Response 200 (application/json)
+
+        {
+            "sealed": true,
+            "t": 3,
+            "n": 5,
+            "progress": 1
+        }
+
+# Group Authentication
+
+## List Auth Methods [/sys/auth]
+### List all auth methods [GET]
+Lists all available authentication methods.
+
+This returns the name of the authentication method as well as
+a human-friendly long-form help text for the method that can be
+shown to the user as documentation.
+
++ Response 200 (application/json)
+
+        {
+            "token": {
+                "type": "token",
+                "description": "Token authentication"
+            },
+            "oauth": {
+                "type": "oauth",
+                "description": "OAuth authentication"
+            }
+        }
+
+## Single Auth Method [/sys/auth/{id}]
+
++ Parameters
+    + id (required, string) ... The ID of the auth method.
+
+### Enable an auth method [PUT]
+Enables an authentication method.
+
+The body of the request depends on the authentication method
+being used. Please reference the documentation for the specific
+authentication method you're enabling in order to determine what
+parameters you must give it.
+
+If an authentication method is already enabled, then this can be
+used to change the configuration, including even the type of
+the configuration.
+
++ Request (application/json)
+
+        {
+            "type": "type",
+            "key": "value",
+            "key2": "value2"
+        }
+
++ Response 204
+
+### Disable an auth method [DELETE]
+Disables an authentication method. Previously authenticated sessions
+are immediately invalidated.
+
++ Response 204
+
+# Group Policies
+
+Policies are named permission sets that identities returned by
+credential stores are bound to. This separates _authentication_
+from _authorization_.
+
+## Policies [/sys/policy]
+### List all Policies [GET]
+
+List all the policies.
+
++ Response 200 (application/json)
+
+        {
+            "policies": ["root"]
+        }
+
+## Single Policy [/sys/policy/{id}]
+
++ Parameters
+    + id (required, string) ... The name of the policy
+
+### Upsert [PUT]
+
+Create or update a policy with the given ID.
+
++ Request (application/json)
+
+        {
+            "rules": "HCL"
+        }
+
++ Response 204
+
+### Delete [DELETE]
+
+Delete a policy with the given ID. Any identities bound to this
+policy will immediately become "deny all" despite already being
+authenticated.
+
++ Response 204
+
+# Group Mounts
+
+Logical backends are mounted at _mount points_, similar to
+filesystems. This allows you to mount the "aws" logical backend
+at the "aws-us-east" path, so all access is at `/aws-us-east/keys/foo`
+for example. This enables multiple logical backends to be enabled.
+
+## Mounts [/sys/mounts]
+### List all mounts [GET]
+
+Lists all the active mount points.
+
++ Response 200 (application/json)
+
+        {
+            "aws": {
+                "type": "aws",
+                "description": "AWS"
+            },
+            "pg": {
+                "type": "postgresql",
+                "description": "PostgreSQL dynamic users"
+            }
+        }
+
+## Single Mount [/sys/mounts/{path}]
+### New Mount [POST]
+
+Mount a logical backend to a new path.
+
+Configuration for this new backend is done via the normal
+read/write mechanism once it is mounted.
+
++ Request (application/json)
+
+        {
+            "type": "aws",
+            "description": "EU AWS tokens"
+        }
+
++ Response 204
+
+### Unmount [DELETE]
+
+Unmount a mount point.
+
++ Response 204
+
+## Remount [/sys/remount]
+### Remount [POST]
+
+Move an already-mounted backend to a new path.
+
++ Request (application/json)
+
+        {
+            "from": "aws",
+            "to": "aws-east"
+        }
+
++ Response 204
+
+# Group Audit Backends
+
+Audit backends are responsible for shuttling the audit logs that
+Vault generates to a durable system for future querying. By default,
+audit logs are not stored anywhere.
+
+## Audit Backends [/sys/audit]
+### List Enabled Audit Backends [GET]
+
+List all the enabled audit backends
+
++ Response 200 (application/json)
+
+        {
+            "file": {
+                "type": "file",
+                "description": "Send audit logs to a file",
+                "options": {}
+            }
+        }
+
+## Single Audit Backend [/sys/audit/{path}]
+
++ Parameters
+    + path (required, string) ... The path where the audit backend is mounted
+
+### Enable [PUT]
+
+Enable an audit backend.
+
++ Request (application/json)
+
+        {
+            "type": "file",
+            "description": "send to a file",
+            "options": {
+                "path": "/var/log/vault.audit.log"
+            }
+        }
+
++ Response 204
+
+### Disable [DELETE]
+
+Disable an audit backend.
+
++ Request (application/json)
+
++ Response 204
+
+# Group Secrets
+
+## Generic [/{mount}/{path}]
+
+This group documents the general format of reading and writing
+to Vault. The exact structure of the keyspace is defined by the
+logical backends in use, so documentation related to
+a specific backend should be referenced for details on what keys
+and routes are expected.
+
+The path for examples are `/prefix/path`, but in practice
+these will be defined by the backends that are mounted. For
+example, reading an AWS key might be at the `/aws/root` path.
+These paths are defined by the logical backends.
+
++ Parameters
+    + mount (required, string) ... The mount point for the
+      logical backend. Example: `aws`.
+    + path (optional, string) ... The path within the backend
+      to read or write data.
+
+### Read [GET]
+
+Read data from vault.
+
+The data read from the vault can either be a secret or
+arbitrary configuration data. The type of data returned
+depends on the path, and is defined by the logical backend.
+
+If the return value is a secret, then the return structure
+is a mixture of arbitrary key/value along with the following
+fields which are guaranteed to exist:
+
+- `lease_id` (string) - A unique ID used for renewal and
+  revocation.
+
+- `renewable` (bool) - If true, then this key can be renewed.
+  If a key can't be renewed, then a new key must be requested
+  after the lease duration period.
+
+- `lease_duration` (int) - The time in seconds that a secret is
+  valid for before it must be renewed.
+
+- `lease_duration_max` (int) - The maximum amount of time in
+  seconds that a secret is valid for. This will always be
+  greater than or equal to `lease_duration`. The difference
+  between this and `lease_duration` is an overlap window
+  where multiple keys may be valid.
+
+If the return value is not a secret, then the return structure
+is an arbitrary JSON object.
+
++ Response 200 (application/json)
+
+        {
+            "lease_id": "UUID",
+            "lease_duration": 3600,
+            "key": "value"
+        }
+
+### Write [PUT]
+
+Write data to vault.
+
+The behavior and arguments to the write are defined by
+the logical backend.
+
++ Request (application/json)
+
+        {
+            "key": "value"
+        }
+
++ Response 204
+
+# Group Lease Management
+
+## Renew Key [/sys/renew/{id}]
+
++ Parameters
+    + id (required, string) ... The `lease_id` of the secret
+      to renew.
+
+### Renew [PUT]
+
++ Response 200 (application/json)
+
+        {
+            "lease_id": "...",
+            "lease_duration": 3600,
+            "access_key": "foo",
+            "secret_key": "bar"
+        }
+
+## Revoke Key [/sys/revoke/{id}]
+
++ Parameters
+    + id (required, string) ... The `lease_id` of the secret
+      to revoke.
+
+### Revoke [PUT]
+
++ Response 204
+
+# Group Backend: AWS
+
+## Root Key [/aws/root]
+### Set the Key [PUT]
+
+Set the root key that the logical backend will use to create
+new secrets, IAM policies, etc.
+
++ Request (application/json)
+
+        {
+            "access_key": "key",
+            "secret_key": "key",
+            "region": "us-east-1"
+        }
+
++ Response 204
+
+## Policies [/aws/policies]
+### List Policies [GET]
+
+List all the policies that can be used to create keys.
+
++ Response 200 (application/json)
+
+        [{
+            "name": "root",
+            "description": "Root access"
+        }, {
+            "name": "web-deploy",
+            "description": "Enough permissions to deploy the web app."
+        }]
+
+## Single Policy [/aws/policies/{name}]
+
++ Parameters
+    + name (required, string) ... Name of the policy.
+
+### Read [GET]
+
+Read a policy.
+
++ Response 200 (application/json)
+
+        {
+            "policy": "base64-encoded policy"
+        }
+
+### Upsert [PUT]
+
+Create or update a policy.
+
++ Request (application/json)
+
+        {
+            "policy": "base64-encoded policy"
+        }
+
++ Response 204
+
+### Delete [DELETE]
+
+Delete the policy with the given name.
+
++ Response 204
+
+## Generate Access Keys [/aws/keys/{policy}]
+### Create [GET]
+
+This generates a new keypair for the given policy.
+
++ Parameters
+    + policy (required, string) ... The policy under which to create
+      the key pair.
+
++ Response 200 (application/json)
+
+        {
+            "lease_id": "...",
+            "lease_duration": 3600,
+            "access_key": "foo",
+            "secret_key": "bar"
+        }