Keys

Supported Specs

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. Certain symmetric keys support key derivation (i.e., such as the ChaCha20 stream cipher). Other key specs, such as RSA, are provided for convenience and to achieve table-stakes feature-parity with industry-standard key management solutions such as AWS Key Management Service, Azure Key Vault, Hashicorp Vault, etc.

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	2048, 3072 and 4096-bit RSASSA-PSS and RSASSA-PKCS1-V1_5-SIGN for sign/verify operations; RSAES_OAEP_SHA_256 for encrypt/decrypt operations

Asymmetric

Key Spec	Description
babyJubJub	a twisted Edwards elliptic curve designed for zk-SNARK circuits
BIP39	BIP39 hierarchical deterministic (HD) wallet for deriving secp256k1 keys
C25519	elliptic curve designed for Diffie-Hellman (ECDH) key exchange
Ed25519	EdDSA signature scheme using SHA-512 (SHA-2)
RSA	2048, 3072 and 4096-bit PSS and PKCS for sign/verify operations OAEPSHA256 for encrypt/decrypt operations
secp256k1	elliptic curve used with ECDSA (i.e., ETH, BTC)

Additional information about keys can be found on the Keys services page.

List Keys

GET https://vault.provide.services/api/v1/vaults/:id/keys

Returns a list of keys in a specified

Vault

Path Parameters

Name	Type	Description
id	string	id of host Vault containing the desired keys

Headers

Name	Type	Description
authorization	string	bearer scoped to an Application , Organization or User

200

[
    {
        "id": "ee745730-a804-482b-ae36-d6b80d61d4d7",
        "created_at": "2021-08-17T01:41:48.792826Z",
        "vault_id": "5fd0ad08-ccc5-4c76-a8a5-0de66fa4efd2",
        "type": "symmetric",
        "usage": "encrypt/decrypt",
        "spec": "AES-256-GCM",
        "name": "master0",
        "description": "AES-256-GCM master key for vault 5fd0ad08-ccc5-4c76-a8a5-0de66fa4efd2"
    },
    {
        "id": "f18aa69c-4f4c-4cd0-a0f1-c65375f4486f",
        "created_at": "2021-08-17T01:42:00.424679Z",
        "vault_id": "5fd0ad08-ccc5-4c76-a8a5-0de66fa4efd2",
        "type": "symmetric",
        "usage": "encrypt/decrypt",
        "spec": "ChaCha20",
        "name": "private chat",
        "description": "this is a secure channel"
    }
]

Delete Key

DELETE https://vault.provide.services/api/v1/vaults/:id/keys/:key_id

Deletes a specified key

Path Parameters

Name	Type	Description
key_id	string	id of key to be deleted
id	string	id of host Vault

Headers

Name	Type	Description
authorization	string	bearer scoped to an Application , Organization or User

200

Derive Key

POST https://vault.provide.services/api/v1/vaults/:id/keys/:key_id/derive

Derives a specified key; derivation of keys is currently restricted to

Chacha20

spec keys.

Path Parameters

Name	Type	Description
key_id	string	id of key to be used for derivation
id	string	id of target host Vault

Headers

Name	Type	Description
authorization	string	bearer scoped to an Application , Organization or User

Request Body

Name	Type	Description
context	string	machine-readable string describing the key derivation context
description	string	brief description for key to be derived
name	string	name for key to be derived
nonce	string	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

200

Encrypt

POST https://vault.provide.services/api/v1/vaults/:id/keys/:key_id/encrypt

Encrypts data using a specified key

Path Parameters

Name	Type	Description
id	string	id of Vault hosting specified key
key_id	string	id of key to be used for encryption

Headers

Name	Type	Description
authorization	string	bearer scoped to an Application , Organization or User

Request Body

Name	Type	Description
data	string	data to be encrypted

200

{
    "data": "b90e56f5cdd0d619ef78df3d8ab85e0651211e4926967bd915e7cc3d124247ced395dc2fa97b882448ae069b5950147f944ebddc869c02742948728109ece39e104cd4ee82b6992e8a1636bfc8d8f502862db19bc2cbc3"
}

Decrypt

POST https://vault.provide.services/api/v1/vaults/:id/keys/:key_id/decrypt

Decrypts data using a specified key

Path Parameters

Name	Type	Description
id	string	id of Vault hosting specified key
key_id	string	id of key to be used for decryption

Headers

Name	Type	Description
authorization	string	bearer scoped to an Application , Organization or User

Request Body

Name	Type	Description
data	string	data to be decrypted

200

{
    "data": "This data will be encrypted. If you can read it then it has been decrypted."
}