Vault

Author: gabriel

.gitignore

@@ -1 +1,2 @@
-.vuepress/dist
+.vuepress/dist
+node_modules

.vuepress/config.js

@@ -2,6 +2,9 @@ module.exports = {
   title: "keys.pub",
   description:
     "Cryptographic key management, saltpack, noise, sigchains, user identities, signing, encryption",
+  extendMarkdown: (md) => {
+    md.use(require("markdown-it-footnote"));
+  },
   head: [
     [
       "link",
@@ -145,9 +148,11 @@ module.exports = {
         collapsable: false,
         path: "/docs/restapi-index",
         children: [
+          "/docs/restapi/auth",
+          "/docs/restapi/errors",
           "/docs/restapi/user",
           "/docs/restapi/sigchain",
-          "/docs/restapi/errors",
+          "/docs/restapi/vault",
         ],
       },
       {
@@ -169,9 +174,9 @@ module.exports = {
           "/docs/specs/auth",
           "/docs/specs/keys",
           "/docs/specs/kid",
-          "/docs/specs/keyring",
           "/docs/specs/sigchain",
           "/docs/specs/user",
+          "/docs/specs/vault",
           "/docs/specs/wormhole",
         ],
       },

docs/restapi/auth.md

@@ -0,0 +1,51 @@
+# Authorization
+
+Some requests require an Authorization header which includes a signature of the HTTP request.
+
+The signature should be specified with an `Authorization` header include the (EdX25519) key identifier and signature bytes (base64 encoded) in the format `{KID}:{Signature}`.
+
+For example,
+
+```text
+kex1nh4jwl3zy0xz8m7eaxvd6uluqwfg3tt2k0rvdlsa6f2jeckvfrtsfd6jh8:pJ/x7hzEcqPZ9cWGmX4UBB3Jh0csSP+7yDScIqI6SPiz9MKedySmQZlxFYSMZMNPKZPyYLVgQeU6NPK7YivJCg==
+```
+
+The bytes to sign are `{Method},{URL},{ContentHash}`.
+
+The Method is the HTTP method (GET, PUT, POST, DELETE, HEAD).
+The URL must be in a canonical form (parameters must be in alphabetical order).
+The ContentHash is the base64 encoded SHA256 hash of the HTTP body (or empty string if no body content).
+
+The URL must include a timestamp (`ts`) and a nonce (`nonce`) parameter.
+The nonce is only allowed to be used once and the timestamp needs to be within 30 minutes of the current time. The server keeps track of nonce values up to an hour.
+
+For example a vault GET request:
+
+BytesToSign:
+
+```text
+GET,https://keys.pub/vault/kex1nh4jwl3zy0xz8m7eaxvd6uluqwfg3tt2k0rvdlsa6f2jeckvfrtsfd6jh8?nonce=pFrY3aZiyYzaHjFF1YlyfZfHxG9QuQwXFv3iUoIQUj9&ts=1595367948129,
+```
+
+cURL:
+
+```shell
+curl -H "Authorization: kex1nh4jwl3zy0xz8m7eaxvd6uluqwfg3tt2k0rvdlsa6f2jeckvfrtsfd6jh8:pJ/x7hzEcqPZ9cWGmX4UBB3Jh0csSP+7yDScIqI6SPiz9MKedySmQZlxFYSMZMNPKZPyYLVgQeU6NPK7YivJCg==" \
+  "https://keys.pub/vault/kex1nh4jwl3zy0xz8m7eaxvd6uluqwfg3tt2k0rvdlsa6f2jeckvfrtsfd6jh8?nonce=pFrY3aZiyYzaHjFF1YlyfZfHxG9QuQwXFv3iUoIQUj9&ts=1595367948129"
+```
+
+Or a vault POST request:
+
+BytesToSign:
+
+```text
+POST,https://keys.pub/vault/kex1cze367q786xuf0xy9gt5g32n8ldpv9753aprn0zwpl5ql0xmu74qcs0mk4?nonce=bzTYFeAcYQH48MXv64B6tOCs1s4SmlAUOyiwSvCJSE6&ts=1595368769675,QcjV+e8ZP1QQ0CCyM3Gxf9JteKCzL5t/hdjB10VVlZY=
+```
+
+cURL:
+
+```shell
+curl -H "Authorization: kex1cze367q786xuf0xy9gt5g32n8ldpv9753aprn0zwpl5ql0xmu74qcs0mk4:lwQ/qB7qDayiK4opnN8ODWAD6TeZcNWhGF0JvMtNgPFpXLMrm7o5QyyIQpXuYVH/dO+Xw7CuryHDsHbMHV0iDA==" -d "[{\"data\":\"dGVzdGluZzE=\"},{\"data\":\"dGVzdGluZzI=\"}]" "https://keys.pub/vault/kex1cze367q786xuf0xy9gt5g32n8ldpv9753aprn0zwpl5ql0xmu74qcs0mk4?nonce=bzTYFeAcYQH48MXv64B6tOCs1s4SmlAUOyiwSvCJSE6&ts=1595368769675"
+```
+
+The [github.com/keys-pub/keys-ext/http/api](https://pkg.go.dev/github.com/keys-pub/keys-ext/http/api) package can create a signed http.Request object, see [api.NewRequest](https://pkg.go.dev/github.com/keys-pub/keys-ext/http/api?tab=doc#pkg-examples).

docs/restapi/errors.md

@@ -20,3 +20,4 @@ The API returns errors in the format:
 | 409  | Resource already exists.                         |
 | 413  | Entity too large, if request body was too large. |
 | 429  | Too many requests, if you hit a request limit.   |
+| 500  | Internal server error.                           |

docs/restapi/sigchain.md

@@ -4,7 +4,7 @@ The _keys.pub_ server provides an API for publishing and accessing [sigchains](/
 
 ## GET /sigchain/:kid
 
-Get a sigchain for a user public key.
+Get a sigchain for a key.
 
 ```shell
 curl https://keys.pub/sigchain/kex1mnseg28xu6g3j4wur7hqwk8ag3fu3pmr2t5lync26xmgff0dtryqupf80c

docs/restapi/vault.md

@@ -0,0 +1,55 @@
+# Vault
+
+A vault is an append only log of data. Data can be requested from an index into this log.
+Vault [requests must be signed](/docs/restapi/auth.md) with the EdX25519 key associated with the vault.
+
+The data itself is not verified in an way, it is stored just as it is received.
+It is up to the clients to encrypt this data (typically using the same EdX25519 key used for signing).
+
+This API is used by the clients to (optionally) backup and sync vault items.
+
+## GET /vault/:kid
+
+Get vault.
+
+| Request | Description              |
+| ------- | ------------------------ |
+| idx     | Index to start at.       |
+| limit   | Limit number of results. |
+
+Requires [Authorization](/docs/restapi/auth.md).
+
+```shell
+https://keys.pub/vault/kex16jvh9cc6na54xwpjs3ztlxdsj6q3scl65lwxxj72m6cadewm404qts0jw9
+```
+
+Returns vault items with a timestamp and index. The timestamp included is when the server received the data.
+
+```json
+{
+  "vault": [
+    { "data": "dGVzdGluZzE=", "idx": 1, "ts": 1595285756121 },
+    { "data": "dGVzdGluZzI=", "idx": 2, "ts": 1595285756152 }
+  ],
+  "idx": 2
+}
+```
+
+## POST /vault/:kid
+
+Requires [Authorization](/docs/restapi/auth.md).
+
+Save items to a vault. The server can process up to 500 items at once.
+
+The request body is a JSON array of data objects.
+
+```json
+[{ "data": "dGVzdGluZzE=" }, { "data": "dGVzdGluZzI=" }]
+```
+
+## DELETE /vault/:kid
+
+Requires [Authorization](/docs/restapi/auth.md).
+
+Remove all data associated with a vault.
+Subsequent requests (GET, POST, PUT) to the vault will return a 404.

docs/specs/keyring.md

@@ -0,0 +1,20 @@
+# Vault
+
+::: warning
+This documentation is in progress.
+:::
+
+A vault is an append only encrypted log used to store secrets.
+
+The format for the vault is designed to track changes and (optionally) for syncing to a remote server.
+
+## Master Key
+
+Vault items are encrypted[^1] with a master key (32 byte secret key) which can be unlocked by provisioned passwords or hardware security keys.
+
+## API Key
+
+If a vault is synced to the server, data is also encrypted with a vault API (EdX25519) key. This key is also used to sign (and authorize) requests to the server (via the [Vault API](/docs/restapi/vault.md)).
+This API key is derived from the master key (using HKDF with a random 32 byte salt).
+
+[^1]: Provisioning info required to unlock the vault, such as salt values, are **NOT** encrypted.

docs/specs/vault.md

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "markdown-it-footnote": "^3.0.2"
+  }
+}

package.json

@@ -0,0 +1,8 @@
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1
+
+
+markdown-it-footnote@^3.0.2:
+  version "3.0.2"
+  resolved "https://registry.yarnpkg.com/markdown-it-footnote/-/markdown-it-footnote-3.0.2.tgz#1575ee7a093648d4e096aa33386b058d92ac8bc1"
+  integrity sha512-JVW6fCmZWjvMdDQSbOT3nnOQtd9iAXmw7hTSh26+v42BnvXeVyGMDBm5b/EZocMed2MbCAHiTX632vY0FyGB8A==