1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
// Created by Ockam Developers
#ifndef RUST_VAULT_H
#define RUST_VAULT_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
typedef struct {
int64_t handle;
uint8_t vault_type;
} ockam_vault_t;
typedef uint64_t ockam_vault_secret_t;
typedef struct {
int32_t code;
const char *domain;
} ockam_vault_extern_error_t;
/**
* @enum ockam_vault_secret_t
* @brief Supported secret types for AES and Elliptic Curves.
*/
typedef enum {
OCKAM_VAULT_SECRET_TYPE_BUFFER = 0,
OCKAM_VAULT_SECRET_TYPE_AES_KEY,
OCKAM_VAULT_SECRET_TYPE_CURVE25519_PRIVATEKEY,
OCKAM_VAULT_SECRET_TYPE_P256_PRIVATEKEY,
} ockam_vault_secret_type_t;
/**
* @enum ockam_vault_secret_persistence_t
* @brief Types of secrets vault can handle.
*/
typedef enum {
OCKAM_VAULT_SECRET_EPHEMERAL = 0,
OCKAM_VAULT_SECRET_PERSISTENT = 1,
} ockam_vault_secret_persistence_t;
/**
* @struct ockam_vault_secret_attributes_t
* @brief Attributes for a specific ockam vault secret.
*/
typedef struct {
uint8_t type;
uint8_t persistence;
uint32_t length;
} ockam_vault_secret_attributes_t;
/**
* @brief Initialize the specified ockam vault object
* @param vault[out] The ockam vault object to initialize with the default vault.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_default_init(ockam_vault_t* vault);
/**
* @brief Compute a SHA-256 hash based on input data.
* @param vault[in] Vault object to use for SHA-256.
* @param input[in] Buffer containing data to run through SHA-256.
* @param input_length[in] Length of the data to run through SHA-256.
* @param digest[out] Buffer to place the resulting SHA-256 hash in. Must be 32 bytes.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_sha256(ockam_vault_t vault,
const uint8_t* input,
size_t input_length,
uint8_t* digest);
/**
* @brief Generate an ockam secret. Attributes struct must specify the configuration for the type of secret to
* generate. For EC keys and AES keys, length is ignored.
* @param vault[in] Vault object to use for generating a secret key.
* @param secret[out] Pointer to an ockam secret object to be populated with a handle to the secret
* @param attributes[in] Desired attribtes for the secret to be generated.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_secret_generate(ockam_vault_t vault,
ockam_vault_secret_t* secret,
ockam_vault_secret_attributes_t attributes);
/**
* @brief Import the specified data into the supplied ockam vault secret.
* @param vault[in] Vault object to use for generating a secret key.
* @param secret[out] Pointer to an ockam secret object to be populated with input data.
* @param attributes[in] Desired attributes for the secret being imported.
* @param input[in] Data to load into the supplied secret.
* @param input_length[in] Length of data to load into the secret.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_secret_import(ockam_vault_t vault,
ockam_vault_secret_t* secret,
ockam_vault_secret_attributes_t attributes,
const uint8_t* input,
size_t input_length);
/**
* @brief Export data from an ockam vault secret into the supplied output buffer.
* @param vault[in] Vault object to use for exporting secret data.
* @param secret[in] Ockam vault secret to export data from.
* @param output_buffer[out] Buffer to place the exported secret data in.
* @param output_buffer_size[in] Size of the output buffer.
* @param output_buffer_length[out] Amount of data placed in the output buffer.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_secret_export(ockam_vault_t vault,
ockam_vault_secret_t secret,
uint8_t* output_buffer,
size_t output_buffer_size,
size_t* output_buffer_length);
/**
* @brief Retrieve the public key from an ockam vault secret.
* @param vault[in] Vault object to use for exporting the public key
* @param secret[in] Ockam vault secret to export the public key for.
* @param output_buffer[out] Buffer to place the public key in.
* @param output_buffer_size[in] Size of the output buffer.
* @param output_buffer_length[out] Amount of data placed in the output buffer.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_secret_publickey_get(ockam_vault_t vault,
ockam_vault_secret_t secret,
uint8_t* output_buffer,
size_t output_buffer_size,
size_t* output_buffer_length);
/**
* @brief Retrieve the attributes for a specified secret
* @param vault[in] Vault object to use for retrieving ockam vault secret attributes.
* @param secret[in] Ockam vault secret to get attributes for.
* @param secret_attributes[out] Pointer to the attributes for the specified secret.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_secret_attributes_get(ockam_vault_t vault,
uint64_t secret,
ockam_vault_secret_attributes_t* attributes);
/**
* @brief Delete an ockam vault secret.
* @param vault[in] Vault object to use for deleting the ockam vault secret.
* @param secret[in] Ockam vault secret to delete.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_secret_destroy(ockam_vault_t vault, ockam_vault_secret_t secret);
/**
* @brief Perform an ECDH operation on the supplied ockam vault secret and peer_publickey. The result is another
* ockam vault secret of type unknown.
* @param vault[in] Vault object to use for encryption.
* @param privatekey[in] The ockam vault secret to use for the private key of ECDH.
* @param peer_publickey[in] Public key data to use for ECDH.
* @param peer_publickey_length[in] Length of the public key.
* @param shared_secret[out] Resulting shared secret from a sucessful ECDH operation. Invalid if ECDH failed.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_ecdh(ockam_vault_t vault,
ockam_vault_secret_t privatekey,
const uint8_t* peer_publickey,
size_t peer_publickey_length,
ockam_vault_secret_t* shared_secret);
/**
* @brief Perform an HMAC-SHA256 based key derivation function on the supplied salt and input key material.
* @param vault[in] Vault object to use for encryption.
* @param salt[in] Ockam vault secret containing the salt for HKDF.
* @param input_key_material[in] Ockam vault secret containing input key material to use for HKDF.
* @param derived_outputs_attributes[in] Attibutes of output secrets.
* @param derived_outputs_count[in] Length of outputs attributes array.
* @param derived_outputs[out] Array of ockam vault secrets resulting from HKDF.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_hkdf_sha256(ockam_vault_t vault,
ockam_vault_secret_t salt,
const ockam_vault_secret_t* input_key_material,
const ockam_vault_secret_attributes_t* derived_outputs_attributes,
uint8_t derived_outputs_count,
ockam_vault_secret_t* derived_outputs);
/**
* @brief Encrypt a payload using AES-GCM.
* @param vault[in] Vault object to use for encryption.
* @param key[in] Ockam secret key to use for encryption.
* @param nonce[in] Nonce value to use for encryption.
* @param additional_data[in] Additional data to use for encryption.
* @param additional_data_length[in] Length of the additional data.
* @param plaintext[in] Buffer containing plaintext data to encrypt.
* @param plaintext_length[in] Length of plaintext data to encrypt.
* @param ciphertext_and_tag[in] Buffer containing the generated ciphertext and tag data.
* @param ciphertext_and_tag_size[in] Size of the ciphertext + tag buffer. Must be plaintext_size + 16.
* @param ciphertext_and_tag_length[out] Amount of data placed in the ciphertext + tag buffer.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_aead_aes_gcm_encrypt(ockam_vault_t vault,
ockam_vault_secret_t key,
uint16_t nonce,
const uint8_t* additional_data,
size_t additional_data_length,
const uint8_t* plaintext,
size_t plaintext_length,
uint8_t* ciphertext_and_tag,
size_t ciphertext_and_tag_size,
size_t* ciphertext_and_tag_length);
/**
* @brief Decrypt a payload using AES-GCM.
* @param vault[in] Vault object to use for decryption.
* @param key[in] Ockam secret key to use for decryption.
* @param nonce[in] Nonce value to use for decryption.
* @param additional_data[in] Additional data to use for decryption.
* @param additional_data_length[in] Length of the additional data.
* @param ciphertext_and_tag[in] The ciphertext + tag data to decrypt.
* @param ciphertext_and_tag_length[in] Length of the ciphertext + tag data to decrypt.
* @param plaintext[out] Buffer to place the decrypted data in.
* @param plaintext_size[in] Size of the plaintext buffer. Must be ciphertext_tag_size - 16.
* @param plaintext_length[out] Amount of data placed in the plaintext buffer.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_aead_aes_gcm_decrypt(ockam_vault_t vault,
ockam_vault_secret_t key,
uint16_t nonce,
const uint8_t* additional_data,
size_t additional_data_length,
const uint8_t* ciphertext_and_tag,
size_t ciphertext_and_tag_length,
uint8_t* plaintext,
size_t plaintext_size,
size_t* plaintext_length);
/**
* @brief Deinitialize the specified ockam vault object
* @param vault[in] The ockam vault object to deinitialize.
* @return error.
*/
ockam_vault_extern_error_t ockam_vault_deinit(ockam_vault_t vault);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // RUST_VAULT_H