luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/api/SPEC.md
Jeff Mitchell e25b3ad344 Update documentation to be consistent with return codes 
Fixes #831
2015-12-10 10:26:40 -05:00

15 KiB
Raw Blame History

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 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. 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).

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"
  }