Skip to content

Latest commit

 

History

History
559 lines (393 loc) · 16.2 KB

http-api.md

File metadata and controls

559 lines (393 loc) · 16.2 KB
Raw

HTTP API

It is assumed the GPG backend is mounted at the /gpg path in Vault. Since it is possible to mount secret backends at any location, please update your API calls accordingly.

Unless otherwise specified, when we say "key" here, assume that it is a master key (which may contain zero or more subkeys).

Master Keys

Create Key

This endpoint creates a new named master key. If a master key already exists with this name, this endpoint will not overwrite it; it must be deleted first.

Method Path Produces
POST /gpg/keys/:name 204 (empty body)

Parameters

  • name (string: <required>) – Specifies the name of the key to create. This is specified as part of the URL.

  • generate (bool: true) – Specifies if a key should be generated by Vault or if a key is being passed from another service.

  • real_name (string: "") – Specifies the real name of the identity associated with the master key to create. Must not contain any of "()<>\x00". Only used if generate is true.

  • email (string: "") – Specifies the email of the identity associated with the master key to create. Must not contain any of "()<>\x00". Only used if generate is true.

  • comment (string: "") – Specifies the comment of the identity associated with the master key to create. Must not contain any of "()<>\x00". Only used if generate is true.

  • key (string: <required - if generate is false>) – Specifies the ASCII-armored GPG private key to use. Only used if generate is false.

  • key_bits (int: 2048) – Specifies the number of bits of the generated master key to use. Only used if generate is true.

  • expires (int: 31536000) – Specifies the number of seconds from the creation time (now) after which the master key and encryption subkey expire. If the number is zero, then they never expire.

  • exportable (bool: false) – Specifies if the raw key is exportable. Note that this will apply to all subkeys, too.

Sample Payload

{
  "real_name": "John Doe",
  "email": "[email protected]",
  "key_bits": 4096
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/keys/my-key

Sample Payload

{
  "key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nlQOYBFmZe5wBCACx8caRJ+M8mKCrS7FdJ5kTdjApbvsx3ccPwvAQhtT2pIYkU\/ec\n...\naUNPVQgd7AF+MIuana8p6KeAXGS3fpiF4vIM0VoeWfEiO9rzdG0ilm16E61r9A==\n=+776\n-----END PGP PRIVATE KEY BLOCK-----\n"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/keys/my-imported-key

Read Key

This endpoint returns information about a named master key.

Method Path Produces
GET /gpg/keys/:name 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the key to read. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.example.com/v1/gpg/keys/my-key

Sample response

{
  "data": {
    "exportable": false,
    "fingerprint": "b0b7e7ca0e4ba1a631d15196ef3331150a45bc4d",
    "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\nxsBNBFmZ6QQBCAC5QSHMKe6M9S2G9REo3sJuDPX2lm4ZMULXCvwcVekPYyUFWYI8\n...\nnTruSryJ4xYCydiJ1xkTedrkVxhh7hJKHA==\n=4fdy\n-----END PGP PUBLIC KEY BLOCK-----"
  }
}

List Keys

This endpoint returns a list of keys. Only the key names are returned.

Method Path Produces
LIST /gpg/keys 200 application/json

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://vault.example.com/v1/gpg/keys

Sample response

{
  "data": {
    "keys": ["foo", "bar"]
  }
}

Delete Key

This endpoint deletes a named master key.

Method Path Produces
DELETE /gpg/keys/:name 204 (empty body)

Parameters

  • name (string: <required>) – Specifies the name of the key to delete. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://vault.example.com/v1/gpg/keys/my-key

Export Key

This endpoint returns the named master key ASCII-armored. The key must be exportable to support this operation.

Method Path Produces
GET /gpg/export/:name 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the key to export. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.example.com/v1/gpg/export/my-key

Sample response

{
  "data": {
    "name": "my-key",
    "key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n\nxcLYBFmZ7JwBCACxsatS8MKxvKpMspkl7ck4vvgZvijBu0sx7Z0+0QDAj8ej5gfK\n...\nYsnjj4QHSRbwJVs/WSIiAj39EyD+bQZDDDFqg62pUA==\n=j7B6\n-----END PGP PRIVATE KEY BLOCK-----"
  }
}

Sign Data

This endpoint returns the signature of the given data using the named master key and the specified hash algorithm.

Method Path Produces
POST /gpg/sign/:name(/:algorithm) 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the key to use for signing. This is specified as part of the URL.

  • algorithm (string: "sha2-256") – Specifies the hash algorithm to use. This can also be specified as part of the URL. Valid algorithms are:

    • sha2-224
    • sha2-256
    • sha2-384
    • sha2-512

  • format (string: "base64") – Specifies the encoding format for the returned signature. Valid encoding format are:

    • base64
    • ascii-armor

  • expires (int: 31536000) – Specifies the number of seconds from the creation time (now) after which the signature expires. If the number is zero, then the signature never expires.

  • input (string: <required>) – Specifies the base64 encoded input data.

Sample payload

{
  "input": "QWxwYWNhCg=="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/sign/my-key/sha2-512

Sample response

{
  "data": {
    "signature": "wsBcBAABCgAQBQJZme+7CRBr/Ej4JtFtLAAA8QcIACLtMWlH5860njpQsJZDIzH3T4mz2397lsd9/hsFDAQXEimuLKWmNdJsTEWXKGx1fvW+r6LEPs8HOLdzOMz2tq6M0WvgzHeWOFdEYmCapUlS68m0GnSFHIAFkq2fMVFHdTTmiLNuZwd+meEPL48hUO8QoGZLhS9IO+xOIisJWP+YIfiZBhmqhz0nVX3CnIzDZWAeJCE9TFGPHjFVNHXKN/IA+pdY4ntU1VOxmKCDqtu6qOrFR3ZghJBrDpDqiMHYmnJZ2AGPDVPKoAorvrLkR7eXNX71yRcutqohqS+xt6nGak2OF7UKwgj5bjk1y44lROFi8aVW4LEX7Jmt+2qwWBg="
  }
}

Verify Signed Data

This endpoint returns whether the provided signature is valid for the given data.

Method Path Produces
POST /gpg/verify/:name 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the key to use for signing. This is specified as part of the URL.

  • format (string: "base64") – Specifies the encoding format the signature uses. Valid encoding format are:

    • base64
    • ascii-armor

  • input (string: <required>) – Specifies the base64 encoded input data.

  • signature (string: "") – Specifies the signature output from the /gpg/sign function.

Sample payload

{
  "input": "QWxwYWNhCg==",
  "signature": "wsBcBAABCgAQBQJZme+7CRBr/Ej4JtFtLAAA8QcIACLtMWlH5860njpQsJZDIzH3T4mz2397lsd9/hsFDAQXEimuLKWmNdJsTEWXKGx1fvW+r6LEPs8HOLdzOMz2tq6M0WvgzHeWOFdEYmCapUlS68m0GnSFHIAFkq2fMVFHdTTmiLNuZwd+meEPL48hUO8QoGZLhS9IO+xOIisJWP+YIfiZBhmqhz0nVX3CnIzDZWAeJCE9TFGPHjFVNHXKN/IA+pdY4ntU1VOxmKCDqtu6qOrFR3ZghJBrDpDqiMHYmnJZ2AGPDVPKoAorvrLkR7eXNX71yRcutqohqS+xt6nGak2OF7UKwgj5bjk1y44lROFi8aVW4LEX7Jmt+2qwWBg="
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/verify/my-key

Sample response

{
  "data": {
    "valid": true
  }
}

Decrypt Data

This endpoint decrypts the provided ciphertext using the named master key.

Method Path Produces
POST /gpg/decrypt/:name 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the key to decrypt against. This is specified as part of the URL.

  • format (string: "base64") – Specifies the encoding format the ciphertext uses. Valid encoding format are:

    • base64
    • ascii-armor

  • ciphertext (string: <required>) – Specifies the ciphertext to decrypt.

  • signer_key (string: "") – Specifies the master key ASCII-armored of the signer. If present, the ciphertext must be signed and the signature valid otherwise the decryption fail.

Sample Payload

{
  "format": "ascii-armor",
  "ciphertext": "-----BEGIN PGP MESSAGE-----\n\nhQEMA923ECy\/uCBhAQf8DLagsnoLuM4AyKiTyvZ7uSQTkmOkwXwn1WWsxoKJkzdI\n...\ne8iwFg==\n=+yfj\n-----END PGP MESSAGE-----"
}

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/decrypt/my-key

Sample Response

{
  "data": {
    "plaintext": "QWxwYWNhcwo="
  }
}

Show Session Key

This endpoint decrypts and returns the session key of the provided ciphertext using the named master key.

Method Path Produces
POST /gpg/show-session-key/:name 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the key to decrypt against. This is specified as part of the URL.

  • format (string: "base64") – Specifies the encoding format the ciphertext uses. Valid encoding format are:

    • base64
    • ascii-armor

  • ciphertext (string: <required>) – Specifies the ciphertext to decrypt.

  • signer_key (string: "") – Specifies the master key ASCII-armored of the signer. If present, the ciphertext must be signed and the signature valid otherwise the decryption fail.

Sample Payload

{
  "format": "ascii-armor",
  "ciphertext": "-----BEGIN PGP MESSAGE-----\n\nhQEMA923ECy\/uCBhAQf8DLagsnoLuM4AyKiTyvZ7uSQTkmOkwXwn1WWsxoKJkzdI\n...\ne8iwFg==\n=+yfj\n-----END PGP MESSAGE-----"
}

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/show-session-key/my-key

Sample Response

{
  "data": {
    "session_key": "9:720D9B92D50D4F7C404C8C412BEB73B47E0A2FA2E822C13201A79D5A2694F9F5"
  }
}

Subkeys

Create Subkey

This endpoint creates, under the given master key, a new subkey with the specified key type, capabilities, as well as size, and returns the Key ID of the public key of this new subkey.

Method Path Produces
POST /gpg/keys/:name/subkeys/ 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the master key with which to associate the new subkey. This is specified as part of the URL.

  • key_type (string: "rsa") – Specifies the subkey type. Supported key types are: rsa.

  • capabilities ([...]string: ["sign"]) – Specifies the capabilities of the subkey. Supported capabilities (depending on the key_type) are: sign.

  • key_bits (int: 4096) – Specifies the number of bits of the generated subkey.

  • expires (int: 31536000) – Specifies the number of seconds from the creation time (now) after which the subkey expires. If the number is zero, then the subkey never expires.

Sample Payload

{
  "key_type": "rsa",
  "capabilities": ["sign"],
  "key_bits": 4096,
  "expires": 31536000
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.example.com/v1/gpg/keys/my-key/subkeys

Sample response

{
  "data": {
    "key_id": "6D0A9151F25B6B85"
  }
}

Read Subkey

This endpoint returns information, such as the key type, capabilities, and size, about the given subkey associated with the given master key.

Method Path Produces
GET /gpg/keys/:name/subkeys/:key_id 200 application/json

Parameters

  • name (string: <required>) – Specifies the name of the master key with which the subkey is associated. This is specified as part of the URL.

  • key_id (string: <required>) – Specifies the Key ID of the subkey. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    https://vault.example.com/v1/gpg/keys/my-key/subkeys/6D0A9151F25B6B85

Sample response

{
  "key_type": "rsa",
  "capabilities": ["sign"],
  "key_bits": 4096,
  "expires": 31536000
}

List Subkeys

This endpoint returns a list of subkeys associated with the GPG master key with the given name. Only Key IDs of public keys of subkeys are returned.

Method Path Produces
LIST /gpg/keys/:name/subkeys/ 200 application/json

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://vault.example.com/v1/gpg/keys/my-key/subkeys

Sample response

{
  "data": ["6D0A9151F25B6B85"]
}

Delete Subkey

This endpoint deletes the given subkey associated with the given master key.

Method Path Produces
DELETE /gpg/keys/:name/subkeys/:key_id 204 (empty body)

Parameters

  • name (string: <required>) – Specifies the name of the master key with which the subkey is associated. This is specified as part of the URL.

  • key_id (string: <required>) – Specifies the Key ID of the subkey. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://vault.example.com/v1/gpg/keys/my-key/subkeys/6D0A9151F25B6B85

Sign Data with Subkey

Use Sign Data to sign data with either the first unexpired signing subkey added to the master key, if any, or the master key itself (which is configured by default to be able to sign).

Verify Signed Data with Subkey

Use Verify Signed Data to verify data signed with a subkey.