diff options
Diffstat (limited to 'vendor/github.com/hashicorp/vault/api/SPEC.md')
| -rw-r--r-- | vendor/github.com/hashicorp/vault/api/SPEC.md | 611 |
1 files changed, 0 insertions, 611 deletions
diff --git a/vendor/github.com/hashicorp/vault/api/SPEC.md b/vendor/github.com/hashicorp/vault/api/SPEC.md deleted file mode 100644 index 15345f3..0000000 --- a/vendor/github.com/hashicorp/vault/api/SPEC.md +++ /dev/null @@ -1,611 +0,0 @@ -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" - } |