NAV Navbar
shell

Vault Key Management Service

The Vault service offers state-of-the-art key management with a focus on providing advanced privacy and messaging capabilities (i.e., zero-knowledge proofs, SNARK-friendly hash functions, double-ratchet algorithm, etc.) in a single enterprise-grade API.

This documentation is currently a work in progress!

Supported Curves & Specifications

This section describes the elliptic curves and key specifications which are currently supported by the API. Supported curves and key specs are defined with a type of either or symmetric or asymmetric and a corresponding usage of encrypt/decrypt or sign/verify. Certain symmetric keys support key derivation (i.e., such as the ChaCha20 stream cipher). Other key specs, such as RSA, are (or may) be provided for convenience and to more closely achieve parity with industry-standard key management solutions (i.e., such as AWS KMS).

Symmetric

Key Spec Description
AES-256-GCM default encryption for the master key of each Vault instance
ChaCha20 stream cipher useful with double-ratchet messaging algorithm
RSA not yet supported; 2048, 3072 and 4096-bit RSAES_OAEP_SHA_1 and RSAES_OAEP_SHA_256 encryption algorithms may be added

Asymmetric

Key Spec Description
babyJubJub a twisted Edwards elliptic curve designed for zk-SNARK circuits
C25519 elliptic curve designed for Diffie–Hellman (ECDH) key exchange
Ed25519 EdDSA signature scheme using SHA-512 (SHA-2)
RSA not yet supported; 2048, 3072 and 4096-bit support for various signing algorithms may be added
secp256k1 elliptic curve used with ECDSA (ETH/BTC)

List Vaults

curl -i \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
    https://ident.provide.services/api/v1/vaults
HTTP/2 200

Response JSON:

[
  {
    "id": "c464db5e-4f62-41fa-bf90-f66302a3b977",
    "created_at": "2020-04-22T05:58:47.901225+00:00",
    "name": "Acme Inc.",
    "description": "Organizational keystore",
    "master_key": null,
    "master_key_id": "66fbf21e-e8a7-45bf-9684-890fb1b6eedd"
  }
]

List Vault keystores for the authorized context.

List Keys

curl -i \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
    https://ident.provide.services/api/v1/vaults/a8bc01e2-08ae-415c-8c6d-f6f873a6a947/keys
HTTP/2 200

Response JSON:

[
  {
    "id": "32f4628e-a464-4dda-a01b-78235d1b68eb",
    "created_at": "2020-04-22T05:58:48.336197+00:00",
    "vault_id": "a8bc01e2-08ae-415c-8c6d-f6f873a6a947",
    "type": "asymmetric",
    "usage": "sign/verify",
    "spec": "secp256k1",
    "name": "org mainnet address",
    "description": "ethereum-compatible secp256k1 curve keypair; address: 0x9cf135972E70D20410F3B01273D07106EC308cFb",
    "public_key": "04624897f81851dcabba67c430d19657e843620e0e6fd2e9e52251f6a3d549d6488c37b1df727ecd8abe83d5b04344563a7c98192bdf79c77f0b37ab5b6e67e7df",
    "address": "0x9cf135972E70D20410F3B01273D07106EC308cFb"
  },
  {
    "id": "ba4440d1-7402-4d63-a119-3f1a36a699aa",
    "created_at": "2020-04-22T05:58:48.360966+00:00",
    "vault_id": "a8bc01e2-08ae-415c-8c6d-f6f873a6a947",
    "type": "asymmetric",
    "usage": "sign/verify",
    "spec": "babyJubJub",
    "name": "supply chain zk",
    "description": "twisted edwards curve keypair for zksnark commitment signing and verification",
    "public_key": "7cd092d7b7cacab6a7290ccc02a00db827e13408b883d8621e33892188d7d78f"
  },
  {
    "id": "715086ac-7ddd-4ba5-8601-300b2d05084a",
    "created_at": "2020-04-22T05:58:48.382641+00:00",
    "vault_id": "a8bc01e2-08ae-415c-8c6d-f6f873a6a947",
    "type": "asymmetric",
    "usage": "sign/verify",
    "spec": "Ed25519",
    "name": "ekho signing key",
    "description": "Ed25519 keypair",
    "public_key": "SBL252Q7YQOID3VFSHEJSHS75E4XBMYPQVWUGH7GT5HVPTI3CYVOIC6D"
  }
]

List keys in the specific Vault.

Generate a Key or Keypair

curl -i -XPOST \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
    https://ident.provide.services/api/v1/vaults/a7dd081d-8ad8-499e-a472-587f044c0039/keys \
    -d '{
      "type": "asymmetric",
      "usage": "sign/verify",
      "spec": "secp256k1",
      "name": "org mainnet wallet address",
      "description": "organization eth/stablecoin wallet"
    }'
HTTP/2 201

Response JSON:

{
  "id": "32f4628e-a464-4dda-a01b-78235d1b68eb",
  "created_at": "2020-04-22T05:58:48.336197+00:00",
  "vault_id": "a8bc01e2-08ae-415c-8c6d-f6f873a6a947",
  "type": "asymmetric",
  "usage": "sign/verify",
  "spec": "secp256k1",
  "name": "org mainnet wallet address",
  "description": "organization eth/stablecoin wallet",
  "public_key": "04624897f81851dcabba67c430d19657e843620e0e6fd2e9e52251f6a3d549d6488c37b1df727ecd8abe83d5b04344563a7c98192bdf79c77f0b37ab5b6e67e7df",
  "address": "0x9cf135972E70D20410F3B01273D07106EC308cFb"
}

Generate a new symmetric key or asymmetric keypair.

Importing key material is not yet supported.

Derive a Key

Documentation forthcoming.

curl -i \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
    https://ident.provide.services/api/v1/vaults/a7dd081d-8ad8-499e-a472-587f044c0039/keys/752176e2-f31f-4887-8267-12ba5769ddcb/derive \
    -d '{
      "nonce": 1,
      "context": "channel-6852386c-8a3d-41c6-aa0e-766a31a8faaf",
      "name": "private chat",
      "description": "this is a secure channel"
    }'
HTTP/2 201

Response JSON:

{
  "id": "f22449e7-ed17-4c42-a937-7bf299475af9",
  "created_at": "2020-04-22T13:44:12.613694+00:00",
  "vault_id": "a8bc01e2-08ae-415c-8c6d-f6f873a6a947",
  "type": "symmetric",
  "usage": "encrypt/decrypt",
  "spec": "ChaCha20",
  "name": "private chat",
  "description": "this is a secure channel"
}

Derive a Key. Returns 400 Bad Request if the attempted key derivation is based on a key which does not support derivation.

Request Parameters

Parameter Description
nonce random 32-bit integer or incrementing counter which must only be used once to avoid exposing the underlying secret; if not provided, a random 32-bit integer is used
context machine-readable string describing the key derivation context
name name for the derived key
description human-readable description of the derived key

Sign a Message

curl -i \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
    https://ident.provide.services/api/v1/vaults/a7dd081d-8ad8-499e-a472-587f044c0039/keys/752176e2-f31f-4887-8267-12ba5769ddcb/sign \
    -d '{
      "message": "hello world"
    }'
HTTP/2 200

Response JSON:

{
  "signature": "02a285b1a277f7602dc115a3bf627a8b7603a4a1be9a72b3ab0284878afe443d0023c6b618333ead186cfbf16180f2058727c5ee0e437a0fcff1d3966351d741"
}

Sign a message with a given Key.

Request Parameters

Parameter Description
message arbitrary message to sign

Verify a Signature

curl -i \
    -H 'Authorization: bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7fSwiZXhwIjpudWxsLCJpYXQiOjE1NTk4Nzg1NzQsImp0aSI6IjYzYTJkY2QzLWI5OTgtNDZjNC1hNzFkLTQ5MjU4YTBhYmEyMyIsInN1YiI6ImFwcGxpY2F0aW9uOmNiMjAzN2Y3LTc5ZmMtNDBmNC05NzIwLWFkYTYzNmRhNDE4MyJ9.0LsVj7oTF0KjwbcUhg9a-fQRWB7cGzKJxLIANeX2cWE' \
    https://ident.provide.services/api/v1/vaults/a7dd081d-8ad8-499e-a472-587f044c0039/keys/752176e2-f31f-4887-8267-12ba5769ddcb/verify \
    -d '{
      "message": "hello world",
      "signature": "02a285b1a277f7602dc115a3bf627a8b7603a4a1be9a72b3ab0284878afe443d0023c6b618333ead186cfbf16180f2058727c5ee0e437a0fcff1d3966351d741"
    }'
HTTP/2 200

Response JSON:

{
  "verified": true
}

Verify that a message was signed with a given Key.

Request Parameters

Parameter Description
message the original message
signature the signature to verify