Ockam logo
Product
OverviewCloud SDKEdge SDKEmbedded SDKRegistryRouter
Contact us

Vault Interface

This document specifies the vault interface design

The interface can be looked in two pieces, the vault interface functions and vault interface secrets. The secrets can hold a variety of keys such as elliptic curve private and public keys, shared secrets and AES keys. The vault interface functions perform a number of cryptographic operations, sometimes using the vault interface secrets.

Description

Vault Interface Functions

1/**
2 * @brief Generate a random number of desired size.
3 * @param vault[in] Vault object to use for random number generation.
4 * @param buffer[out] Buffer containing data to run through SHA-256.
5 * @param buffer_size[in] Size of the data to run through SHA-256.
6 * @return OCKAM_ERROR_NONE on success.
7 */
8ockam_error_t ockam_vault_random_bytes_generate(ockam_vault_t* vault, uint8_t* buffer, size_t buffer_size);
9
10/**
11 * @brief Compute a SHA-256 hash based on input data.
12 * @param vault[in] Vault object to use for SHA-256.
13 * @param input[in] Buffer containing data to run through SHA-256.
14 * @param input_length[in] Length of the data to run through SHA-256.
15 * @param digest[out] Buffer to place the resulting SHA-256 hash in.
16 * @param digest_size[in] Size of the digest buffer. Must be 32 bytes.
17 * @param digest_length[out] Amount of data placed in the digest buffer.
18 * @return OCKAM_ERROR_NONE on success.
19 */
20ockam_error_t ockam_vault_sha256(ockam_vault_t* vault,
21 const uint8_t* input,
22 size_t input_length,
23 uint8_t* digest,
24 size_t digest_size,
25 size_t* digest_length);
26
27/**
28 * @brief Perform an ECDH operation on the supplied ockam vault secret and peer_publickey. The result is another
29 * ockam vault secret of type unknown.
30 * @param vault[in] Vault object to use for encryption.
31 * @param privatekey[in] The ockam vault secret to use for the private key of ECDH.
32 * @param peer_publickey[in] Public key data to use for ECDH.
33 * @param peer_publickey_length[in] Length of the public key.
34 * @param shared_secret[out] Resulting shared secret from a sucessful ECDH operation. Invalid if ECDH failed.
35 * @return OCKAM_ERROR_NONE on success.
36 */
37ockam_error_t ockam_vault_ecdh(ockam_vault_t* vault,
38 ockam_vault_secret_t* privatekey,
39 const uint8_t* peer_publickey,
40 size_t peer_publickey_length,
41 ockam_vault_secret_t* shared_secret);
42
43/**
44 * @brief Perform an HMAC-SHA256 based key derivation function on the supplied salt and input key material.
45 * @param vault[in] Vault object to use for encryption.
46 * @param salt[in] Ockam vault secret containing the salt for HKDF.
47 * @param input_key_material[in] Ockam vault secret containing input key material to use for HKDF.
48 * @param derived_outputs_count[in] Total number of keys to generate.
49 * @param derived_outputs[out] Array of ockam vault secrets resulting from HKDF.
50 * @return OCKAM_ERROR_NONE on success.
51 */
52ockam_error_t ockam_vault_hkdf_sha256(ockam_vault_t* vault,
53 ockam_vault_secret_t* salt,
54 ockam_vault_secret_t* input_key_material,
55 uint8_t derived_outputs_count,
56 ockam_vault_secret_t* derived_outputs);
57
58/**
59 * @brief Encrypt a payload using AES-GCM.
60 * @param vault[in] Vault object to use for encryption.
61 * @param key[in] Ockam secret key to use for encryption.
62 * @param nonce[in] Nonce value to use for encryption.
63 * @param additional_data[in] Additional data to use for encryption.
64 * @param additional_data_length[in] Length of the additional data.
65 * @param plaintext[in] Buffer containing plaintext data to encrypt.
66 * @param plaintext_length[in] Length of plaintext data to encrypt.
67 * @param ciphertext_and_tag[in] Buffer containing the generated ciphertext and tag data.
68 * @param ciphertext_and_tag_size[in] Size of the ciphertext + tag buffer. Must be plaintext_size + 16.
69 * @param ciphertext_and_tag_length[out] Amount of data placed in the ciphertext + tag buffer.
70 * @return OCKAM_ERROR_NONE on success.
71 */
72ockam_error_t ockam_vault_aead_aes_gcm_encrypt(ockam_vault_t* vault,
73 ockam_vault_secret_t* key,
74 uint16_t nonce,
75 const uint8_t* additional_data,
76 size_t additional_data_length,
77 const uint8_t* plaintext,
78 size_t plaintext_length,
79 uint8_t* ciphertext_and_tag,
80 size_t ciphertext_and_tag_size,
81 size_t* ciphertext_and_tag_length);
82
83/**
84 * @brief Decrypt a payload using AES-GCM.
85 * @param vault[in] Vault object to use for decryption.
86 * @param key[in] Ockam secret key to use for decryption.
87 * @param nonce[in] Nonce value to use for decryption.
88 * @param additional_data[in] Additional data to use for decryption.
89 * @param additional_data_length[in] Length of the additional data.
90 * @param ciphertext_and_tag[in] The ciphertext + tag data to decrypt.
91 * @param ciphertext_and_tag_length[in] Length of the ciphertext + tag data to decrypt.
92 * @param plaintext[out] Buffer to place the decrypted data in.
93 * @param plaintext_size[in] Size of the plaintext buffer. Must be ciphertext_tag_size - 16.
94 * @param plaintext_length[out] Amount of data placed in the plaintext buffer.
95 * @return OCKAM_ERROR_NONE on success.
96 */
97ockam_error_t ockam_vault_aead_aes_gcm_decrypt(ockam_vault_t* vault,
98 ockam_vault_secret_t* key,
99 uint16_t nonce,
100 const uint8_t* additional_data,
101 size_t additional_data_length,
102 const uint8_t* ciphertext_and_tag,
103 size_t ciphertext_and_tag_length,
104 uint8_t* plaintext,
105 size_t plaintext_size,
106 size_t* plaintext_length);

Vault Interface Secrets

1/**
2 * @brief Generate an ockam secret. Attributes struct must specify the configuration for the type of secret to
3 * generate. For EC keys and AES keys, length is ignored.
4 * @param vault[in] Vault object to use for generating a secret key.
5 * @param secret[out] Pointer to an ockam secret object to be populated with the generated secret.
6 * @param attributes[in] Desired attribtes for the secret to be generated.
7 */
8ockam_error_t ockam_vault_secret_generate(ockam_vault_t* vault,
9 ockam_vault_secret_t* secret,
10 const ockam_vault_secret_attributes_t* attributes);
11
12/**
13 * @brief Import the specified data into the supplied ockam vault secret.
14 * @param vault[in] Vault object to use for generating a secret key.
15 * @param secret[out] Pointer to an ockam secret object to be populated with input data.
16 * @param attributes[in] Desired attribtes for the secret being imported.
17 * @param input[in] Data to load into the supplied secret.
18 * @param input_length[in] Length of data to load into the secret.
19 */
20
21ockam_error_t ockam_vault_secret_import(ockam_vault_t* vault,
22 ockam_vault_secret_t* secret,
23 const ockam_vault_secret_attributes_t* attributes,
24 const uint8_t* input,
25 size_t input_length);
26
27/**
28 * @brief Export data from an ockam vault secret into the supplied output buffer.
29 * @param vault[in] Vault object to use for exporting secret data.
30 * @param secret[in] Ockam vault secret to export data from.
31 * @param output_buffer[out] Buffer to place the exported secret data in.
32 * @param output_buffer_size[in] Size of the output buffer.
33 * @param output_buffer_length[out] Amount of data placed in the output buffer.
34 * @return OCKAM_ERROR_NONE on success.
35 */
36ockam_error_t ockam_vault_secret_export(ockam_vault_t* vault,
37 ockam_vault_secret_t* secret,
38 uint8_t* output_buffer,
39 size_t output_buffer_size,
40 size_t* output_buffer_length);
41
42/**
43 * @brief Retrieve the public key from an ockam vault secret.
44 * @param vault[in] Vault object to use for exporting the public key
45 * @param secret[in] Ockam vault secret to export the public key for.
46 * @param output_buffer[out] Buffer to place the public key in.
47 * @param output_buffer_size[in] Size of the output buffer.
48 * @param output_buffer_length[out] Amount of data placed in the output buffer.
49 * @return OCKAM_ERROR_NONE on success.
50 */
51ockam_error_t ockam_vault_secret_publickey_get(ockam_vault_t* vault,
52 ockam_vault_secret_t* secret,
53 uint8_t* output_buffer,
54 size_t output_buffer_size,
55 size_t* output_buffer_length);
56
57/**
58 * @brief Retrive the attributes for a specified secret
59 * @param vault[in] Vault object to use for retrieving ockam vault secret attributes.
60 * @param secret[in] Ockam vault secret to get attributes for.
61 * @param secret_attributes[out] Pointer to the attributes for the specified secret.
62 */
63ockam_error_t ockam_vault_secret_attributes_get(ockam_vault_t* vault,
64 ockam_vault_secret_t* secret,
65 ockam_vault_secret_attributes_t* attributes);
66
67/**
68 * @brief Set or change the type of secret. Note: EC secrets can not be changed.
69 * @param vault[in] Vault object to use for setting secret type.
70 * @param secret[in] Secret to change the type.
71 * @param type[in] Type of secret to change to.
72 */
73ockam_error_t
74ockam_vault_secret_type_set(ockam_vault_t* vault, ockam_vault_secret_t* secret, ockam_vault_secret_type_t type);
75
76/**
77 * @brief Delete an ockam vault secret.
78 * @param vault[in] Vault object to use for deleting the ockam vault secret.
79 * @param secret[in] Ockam vault secret to delete.
80 * @return OCKAM_ERROR_NONE on success.
81 */
82ockam_error_t ockam_vault_secret_destroy(ockam_vault_t* vault, ockam_vault_secret_t* secret);

Discussion

We’re discussing the Ockam vault interface in the following Github issue: #53

References

See the discussion.

Previous

Wire Protocol

Next

Secure Channels

On this page
  • Description
  • Vault Interface Functions
  • Vault Interface Secrets
  • Discussion
  • References
Edit this page
Star Ockam repo