Software APIs
hardened_memory.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_BASE_HARDENED_MEMORY_H_
6#define OPENTITAN_SW_DEVICE_LIB_BASE_HARDENED_MEMORY_H_
7
8/**
9 * @file
10 * @brief Hardened memory operations for constant power buffer manipulation.
11 */
12
13#include <stddef.h>
14#include <stdint.h>
15
18#include "sw/device/lib/crypto/impl/status.h"
19
20#ifdef __cplusplus
21extern "C" {
22#endif // __cplusplus
23
24/**
25 * Expects some external implementation of randomness to be linked.
26 *
27 * @return A fresh random word.
28 */
29extern uint32_t hardened_memshred_random_word(void);
30
31/**
32 * Copies 32-bit words between non-overlapping regions.
33 *
34 * Unlike `memcpy()`, this function has important differences:
35 * - It is significantly slower, since it mitigates power-analysis attacks.
36 * - It performs operations on 32-bit words, rather than bytes.
37 *
38 * Input pointers *MUST* be 32-bit aligned, although they do not need to
39 * actually point to memory declared as `uint32_t` per the C aliasing rules.
40 * Internally, this function is careful to not dereference its operands
41 * directly, and instead uses dedicated load/store intrinsics.
42 *
43 * @param dest The destination of the copy.
44 * @param src The source of the copy.
45 * @param word_len The number of words to copy.
46 * @return OK or error.
47 */
48status_t hardened_memcpy(uint32_t *OT_RESTRICT dest,
49 const uint32_t *OT_RESTRICT src, size_t word_len);
50
51/**
52 * Fills a 32-bit aligned region of memory with random data.
53 *
54 * Unlike `memset()`, this function has important differences:
55 * - It is significantly slower, since it mitigates power-analysis attacks.
56 * - It performs operations on 32-bit words, rather than bytes.
57 * - A fill value cannot be specified.
58 *
59 * Input pointers *MUST* be 32-bit aligned, although they do not need to
60 * actually point to memory declared as `uint32_t` per the C aliasing rules.
61 * Internally, this function is careful to not dereference its operands
62 * directly, and instead uses dedicated load/store intrinsics.
63 *
64 * @param dest The destination of the set.
65 * @param word_len The number of words to write.
66 */
67void hardened_memshred(uint32_t *dest, size_t word_len);
68
69/**
70 * Compare two potentially-overlapping 32-bit aligned regions of memory for
71 * equality.
72 *
73 * Unlike `memcmp()`, this function has important differences:
74 * - It is significantly slower, since it mitigates power-analysis attacks.
75 * - It performs operations on 32-bit words, rather than bytes.
76 * - It only computes equality, not lexicographic ordering, which would be even
77 * slower.
78 * - It returns a `hardened_bool_t`.
79 * - It is constant-time.
80 *
81 * Input pointers *MUST* be 32-bit aligned, although they do not need to
82 * actually point to memory declared as `uint32_t` per the C aliasing rules.
83 * Internally, this function is careful to not dereference its operands
84 * directly, and instead uses dedicated load/store intrinsics.
85 *
86 * @param lhs The first buffer to compare.
87 * @param rhs The second buffer to compare.
88 * @param word_len The number of words to compare.
89 */
90hardened_bool_t hardened_memeq(const uint32_t *lhs, const uint32_t *rhs,
91 size_t word_len);
92
93/**
94 * Constant time memeq implementation that can also handle non 32-bit aligned
95 * buffers.
96 *
97 * SCA protection is provided by choosing a random start index for the
98 * comparison.
99 *
100 * CAUTION! This function is not considered as secure as `hardened_memeq` due to
101 * the byte-sized memory accesses vs. 32b word accesses.
102 *
103 * @param lhs The first buffer to compare.
104 * @param rhs The second buffer to compare.
105 * @param word_len The number of bytes to compare.
106 */
107hardened_bool_t consttime_memeq_byte(const void *lhs, const void *rhs,
108 size_t len);
109
110/**
111 * Combines two word buffers with XOR and store the result in the dest. buffer.
112 *
113 * Performs dest = ((rand ^ x) ^ y) ^ rand
114 *
115 * Callers should ensure the entropy complex is up before calling this
116 * function. The implementation uses random-order hardening primitives for
117 * side-channel defense. Moreover, calles should ensure that the dest. buffer
118 * is different from the source buffers.
119 *
120 * @param x Pointer to the first operand.
121 * @param y Pointer to the second operand.
122 * @param word_len Length in words of each operand.
123 * @param dest[out] Pointer to the output buffer.
124 * @return OK or error.
125 */
126status_t hardened_xor(const uint32_t *OT_RESTRICT x,
127 const uint32_t *OT_RESTRICT y, size_t word_len,
128 uint32_t *OT_RESTRICT dest);
129
130/**
131 * Combines two word buffers with XOR in-place.
132 *
133 * Callers should ensure the entropy complex is up before calling this
134 * function. The implementation uses random-order hardening primitives for
135 * side-channel defense.
136 *
137 * @param[in,out] x Pointer to the first operand (modified in-place).
138 * @param y Pointer to the second operand.
139 * @param word_len Length in words of each operand.
140 * @return OK or error.
141 */
143 const uint32_t *OT_RESTRICT y, size_t word_len);
144
145/**
146 * Copy memory between non-overlapping regions with a randomized byte traversal.
147 *
148 * CAUTION! This function is not considered as secure as `hardened_memcpy` due
149 * to the byte-sized memory accesses vs. 32b word accesses. After this function,
150 * a `consttime_memeq_byte(src, dest, byte_len)` should follow to check if the
151 * bytecopy was successful (see lowRISC/opentitan#8815). Switch the function
152 * arguments as shown in the example to also cover faults directly on the
153 * pointers.
154 *
155 * @param dest the region to copy to.
156 * @param src the region to copy from.
157 * @param byte_len, the number of bytes to copy.
158 * @return Result of the operation (OK or error).
159 */
161 const void *OT_RESTRICT src, size_t byte_len);
162
163/**
164 * In-place XOR of two non-overlapping memory regions with a randomized byte
165 * traversal.
166 *
167 * CAUTION! This function is not considered as secure as `hardened_xor_in_place`
168 * due to the byte-sized memory accesses vs. 32b word accesses.
169 *
170 * @param x Pointer to the first operand (modified in-place).
171 * @param y Pointer to the second operand.
172 * @param byte_len, the number of bytes to XOR.
173 * @return Result of the operation (OK or error).
174 */
176 const void *OT_RESTRICT y,
177 size_t byte_len);
178
179/**
180 * Combines two word buffers with ADD and store the result in the dest. buffer.
181 *
182 * Warning: Only limited SCA hardening measures are applied due to the nature of
183 * arithmetic operations. guaranteed. The function is hardened against fault
184 * injections.
185 *
186 * This mimics the OTBN `add`.
187 *
188 * @param x Pointer to the first operand.
189 * @param y Pointer to the second operand.
190 * @param word_len Length in words of each operand.
191 * @param dest[out] Pointer to the output buffer.
192 * @return OK or error.
193 */
194status_t hardened_add(const uint32_t *OT_RESTRICT x,
195 const uint32_t *OT_RESTRICT y, size_t word_len,
196 uint32_t *OT_RESTRICT dest);
197
198/**
199 * Combines two word buffers with SUB and store the result in the dest. buffer.
200 *
201 * Warning: the side-channel protection of this function call can not be
202 * guaranteed.
203 * The function is hardened against fault injections.
204 *
205 * This mimics the OTBN `sub`.
206 *
207 * @param x Pointer to the first operand.
208 * @param y Pointer to the second operand.
209 * @param word_len Length in words of each operand.
210 * @param dest[out] Pointer to the output buffer.
211 * @return OK or error.
212 */
213status_t hardened_sub(const uint32_t *OT_RESTRICT x,
214 const uint32_t *OT_RESTRICT y, size_t word_len,
215 uint32_t *OT_RESTRICT dest);
216
217/**
218 * Perform a modular subtraction of two multi-word values.
219 *
220 * It computes (x - y) mod n. The values are expected to follow a
221 * little-endian layout.
222 *
223 * Warning: the side-channel protection of this function call can not be
224 * guaranteed. The function is hardened against fault injections and is
225 * constant time in the value being reduced.
226 *
227 * In order to have this function constant time, it conditionally adds n only
228 * once.
229 * This function mimics OTBN's subm.
230 *
231 * @param x Pointer to the first operand.
232 * @param y Pointer to the second operand.
233 * @param n Pointer to the multi-word modulus.
234 * @param word_len Length in words of each operand and the modulus.
235 * @param[out] dest Pointer to the multi-word result.
236 * @return OK or error.
237 */
238status_t hardened_sub_mod(const uint32_t *OT_RESTRICT x,
239 const uint32_t *OT_RESTRICT y,
240 const uint32_t *OT_RESTRICT n, size_t word_len,
241 uint32_t *OT_RESTRICT dest);
242
243/**
244 * Perform a modular addition of two multi-word values.
245 *
246 * It computes (x + y) mod n. The values are expected to follow a
247 * little-endian layout.
248 *
249 * Warning: the side-channel protection of this function call can not be
250 * guaranteed. The function is hardened against fault injections and is
251 * constant time in the value being reduced.
252 *
253 * In order to have this function constant time, it conditionally subtracts n
254 * only once.
255 * This function mimics OTBN's addm.
256 *
257 * @param x Pointer to the first operand.
258 * @param y Pointer to the second operand.
259 * @param n Pointer to the multi-word modulus.
260 * @param word_len Length in words of each operand and the modulus.
261 * @param[out] dest Pointer to the multi-word result.
262 * @return OK or error.
263 */
264status_t hardened_add_mod(const uint32_t *OT_RESTRICT x,
265 const uint32_t *OT_RESTRICT y,
266 const uint32_t *OT_RESTRICT n, size_t word_len,
267 uint32_t *OT_RESTRICT dest);
268
269/**
270 * Perform a range check whether the value is larger than zero and smaller than
271 * N. Namely, it checks whether 0 < value < N. Values are expected to follow
272 * little-endian layout.
273 *
274 * Warning: the side-channel protection of this function call can not be
275 * guaranteed.
276 * The function is hardened against fault injections and is constant time.
277 *
278 * @param value Pointer to the value to check.
279 * @param N Pointer to the upper limit of the range.
280 * @param word_len Length in words of value and N.
281 * @return OK or error.
282 */
283status_t hardened_range_check(const uint32_t *value, const uint32_t *N,
284 size_t word_len);
285
286/**
287 * Perform a modular reduction of a multi-word value by a multi-word modulus.
288 *
289 * It checks whether value % n. The value is expected to follow a
290 * little-endian layout.
291 *
292 * Warning: the side-channel protection of this function call can not be
293 * guaranteed. The function is hardened against fault injections and is
294 * constant time in the value being reduced.
295 *
296 * @param value Pointer to the value to check.
297 * @param n Pointer to the multi-word modulus.
298 * @param word_len Length in words of value.
299 * @param[out] result Pointer to the multi-word result.
300 * @return OK or error.
301 */
302status_t hardened_mod_reduce(const uint32_t *value, const uint32_t *n,
303 size_t word_len, uint32_t *result);
304
305#ifdef __cplusplus
306} // extern "C"
307#endif // __cplusplus
308
309#endif // OPENTITAN_SW_DEVICE_LIB_BASE_HARDENED_MEMORY_H_