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
16
#include "
sw/device/lib/base/hardened.h
"
17
#include "
sw/device/lib/base/macros.h
"
18
#include "sw/device/lib/crypto/impl/status.h"
19
20
#ifdef __cplusplus
21
extern
"C"
{
22
#endif
// __cplusplus
23
24
/**
25
* Expects some external implementation of randomness to be linked.
26
*
27
* @return A fresh random word.
28
*/
29
extern
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
*/
48
status_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
*/
67
void
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
*/
90
hardened_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
*/
107
hardened_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
*/
126
status_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
*/
142
status_t
hardened_xor_in_place
(uint32_t *
OT_RESTRICT
x,
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
*/
160
status_t
randomized_bytecopy
(
void
*
OT_RESTRICT
dest,
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
*/
175
status_t
randomized_bytexor_in_place
(
void
*
OT_RESTRICT
x,
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
*/
194
status_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
*/
213
status_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
*/
238
status_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
*/
264
status_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
*/
283
status_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
*/
302
status_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_
sw
device
lib
base
hardened_memory.h
Return to
OpenTitan Documentation