Debian Codegraph @

Modules/_hacl/Hacl_Hash_Blake2b.h

raw
1 /* MIT License
2 *
3 * Copyright (c) 2016-2022 INRIA, CMU and Microsoft Corporation
4 * Copyright (c) 2022-2023 HACL* Contributors
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25
26 #ifndef Hacl_Hash_Blake2b_H
27 #define Hacl_Hash_Blake2b_H
28
29 #if defined(__cplusplus)
30 extern "C" {
31 #endif
32
33 #include <string.h>
34 #include "python_hacl_namespaces.h"
35 #include "krml/internal/types.h"
36 #include "krml/lowstar_endianness.h"
37 #include "krml/internal/target.h"
38
39 #include "Hacl_Streaming_Types.h"
40
41 typedef struct Hacl_Hash_Blake2b_blake2_params_s
42 {
43 uint8_t digest_length;
44 uint8_t key_length;
45 uint8_t fanout;
46 uint8_t depth;
47 uint32_t leaf_length;
48 uint64_t node_offset;
49 uint8_t node_depth;
50 uint8_t inner_length;
51 uint8_t *salt;
52 uint8_t *personal;
53 }
54 Hacl_Hash_Blake2b_blake2_params;
55
56 typedef struct Hacl_Hash_Blake2b_index_s
57 {
58 uint8_t key_length;
59 uint8_t digest_length;
60 bool last_node;
61 }
62 Hacl_Hash_Blake2b_index;
63
64 #define HACL_HASH_BLAKE2B_BLOCK_BYTES (128U)
65
66 #define HACL_HASH_BLAKE2B_OUT_BYTES (64U)
67
68 #define HACL_HASH_BLAKE2B_KEY_BYTES (64U)
69
70 #define HACL_HASH_BLAKE2B_SALT_BYTES (16U)
71
72 #define HACL_HASH_BLAKE2B_PERSONAL_BYTES (16U)
73
74 typedef struct Hacl_Hash_Blake2b_block_state_t_s Hacl_Hash_Blake2b_block_state_t;
75
76 typedef struct Hacl_Hash_Blake2b_state_t_s Hacl_Hash_Blake2b_state_t;
77
78 /**
79 General-purpose allocation function that gives control over all
80 Blake2 parameters, including the key. Further resettings of the state SHALL be
81 done with `reset_with_params_and_key`, and SHALL feature the exact same values
82 for the `key_length` and `digest_length` fields as passed here. In other words,
83 once you commit to a digest and key length, the only way to change these
84 parameters is to allocate a new object.
85
86 The caller must satisfy the following requirements.
87 - The length of the key k MUST match the value of the field key_length in the
88 parameters.
89 - The key_length must not exceed 32 for S, 64 for B.
90 - The digest_length must not exceed 32 for S, 64 for B.
91
92 */
93 Hacl_Hash_Blake2b_state_t
94 *Hacl_Hash_Blake2b_malloc_with_params_and_key(
95 Hacl_Hash_Blake2b_blake2_params *p,
96 bool last_node,
97 uint8_t *k
98 );
99
100 /**
101 Specialized allocation function that picks default values for all
102 parameters, except for the key_length. Further resettings of the state SHALL be
103 done with `reset_with_key`, and SHALL feature the exact same key length `kk` as
104 passed here. In other words, once you commit to a key length, the only way to
105 change this parameter is to allocate a new object.
106
107 The caller must satisfy the following requirements.
108 - The key_length must not exceed 32 for S, 64 for B.
109
110 */
111 Hacl_Hash_Blake2b_state_t *Hacl_Hash_Blake2b_malloc_with_key(uint8_t *k, uint8_t kk);
112
113 /**
114 Specialized allocation function that picks default values for all
115 parameters, and has no key. Effectively, this is what you want if you intend to
116 use Blake2 as a hash function. Further resettings of the state SHALL be done with `reset`.
117 */
118 Hacl_Hash_Blake2b_state_t *Hacl_Hash_Blake2b_malloc(void);
119
120 /**
121 General-purpose re-initialization function with parameters and
122 key. You cannot change digest_length, key_length, or last_node, meaning those values in
123 the parameters object must be the same as originally decided via one of the
124 malloc functions. All other values of the parameter can be changed. The behavior
125 is unspecified if you violate this precondition.
126 */
127 void
128 Hacl_Hash_Blake2b_reset_with_key_and_params(
129 Hacl_Hash_Blake2b_state_t *s,
130 Hacl_Hash_Blake2b_blake2_params *p,
131 uint8_t *k
132 );
133
134 /**
135 Specialized-purpose re-initialization function with no parameters,
136 and a key. The key length must be the same as originally decided via your choice
137 of malloc function. All other parameters are reset to their default values. The
138 original call to malloc MUST have set digest_length to the default value. The
139 behavior is unspecified if you violate this precondition.
140 */
141 void Hacl_Hash_Blake2b_reset_with_key(Hacl_Hash_Blake2b_state_t *s, uint8_t *k);
142
143 /**
144 Specialized-purpose re-initialization function with no parameters
145 and no key. This is what you want if you intend to use Blake2 as a hash
146 function. The key length and digest length must have been set to their
147 respective default values via your choice of malloc function (always true if you
148 used `malloc`). All other parameters are reset to their default values. The
149 behavior is unspecified if you violate this precondition.
150 */
151 void Hacl_Hash_Blake2b_reset(Hacl_Hash_Blake2b_state_t *s);
152
153 /**
154 Update function; 0 = success, 1 = max length exceeded
155 */
156 Hacl_Streaming_Types_error_code
157 Hacl_Hash_Blake2b_update(Hacl_Hash_Blake2b_state_t *state, uint8_t *chunk, uint32_t chunk_len);
158
159 /**
160 Digest function. This function expects the `output` array to hold
161 at least `digest_length` bytes, where `digest_length` was determined by your
162 choice of `malloc` function. Concretely, if you used `malloc` or
163 `malloc_with_key`, then the expected length is 32 for S, or 64 for B (default
164 digest length). If you used `malloc_with_params_and_key`, then the expected
165 length is whatever you chose for the `digest_length` field of your parameters.
166 For convenience, this function returns `digest_length`. When in doubt, callers
167 can pass an array of size HACL_BLAKE2B_32_OUT_BYTES, then use the return value
168 to see how many bytes were actually written.
169 */
170 uint8_t Hacl_Hash_Blake2b_digest(Hacl_Hash_Blake2b_state_t *s, uint8_t *dst);
171
172 Hacl_Hash_Blake2b_index Hacl_Hash_Blake2b_info(Hacl_Hash_Blake2b_state_t *s);
173
174 /**
175 Free state function when there is no key
176 */
177 void Hacl_Hash_Blake2b_free(Hacl_Hash_Blake2b_state_t *state);
178
179 /**
180 Copying. This preserves all parameters.
181 */
182 Hacl_Hash_Blake2b_state_t *Hacl_Hash_Blake2b_copy(Hacl_Hash_Blake2b_state_t *state);
183
184 /**
185 Write the BLAKE2b digest of message `input` using key `key` into `output`.
186
187 @param output Pointer to `output_len` bytes of memory where the digest is written to.
188 @param output_len Length of the to-be-generated digest with 1 <= `output_len` <= 64.
189 @param input Pointer to `input_len` bytes of memory where the input message is read from.
190 @param input_len Length of the input message.
191 @param key Pointer to `key_len` bytes of memory where the key is read from.
192 @param key_len Length of the key. Can be 0.
193 */
194 void
195 Hacl_Hash_Blake2b_hash_with_key(
196 uint8_t *output,
197 uint32_t output_len,
198 uint8_t *input,
199 uint32_t input_len,
200 uint8_t *key,
201 uint32_t key_len
202 );
203
204 /**
205 Write the BLAKE2b digest of message `input` using key `key` and
206 parameters `params` into `output`. The `key` array must be of length
207 `params.key_length`. The `output` array must be of length
208 `params.digest_length`.
209 */
210 void
211 Hacl_Hash_Blake2b_hash_with_key_and_params(
212 uint8_t *output,
213 uint8_t *input,
214 uint32_t input_len,
215 Hacl_Hash_Blake2b_blake2_params params,
216 uint8_t *key
217 );
218
219 #if defined(__cplusplus)
220 }
221 #endif
222
223 #define Hacl_Hash_Blake2b_H_DEFINED
224 #endif /* Hacl_Hash_Blake2b_H */