Botan 3.9.0
Crypto and TLS for C&
mem_ops.h
Go to the documentation of this file.
1/*
2* Memory Operations
3* (C) 1999-2009,2012,2015 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_MEMORY_OPS_H_
9#define BOTAN_MEMORY_OPS_H_
10
11#include <botan/assert.h>
12#include <botan/concepts.h>
13#include <botan/types.h>
14#include <array>
15#include <cstring>
16#include <ranges>
17#include <span>
18#include <type_traits>
19#include <vector>
20
22
23/*
24The header mem_ops.h previously included the contents of allocator.h
25
26Library code should always include allocator.h to see these
27declarations; however when we are not building the library continue to
28include the header here to avoid breaking application code.
29*/
30#if !defined(BOTAN_IS_BEING_BUILT)
31 #include <botan/allocator.h>
32#endif
33
34namespace Botan {
35
36/**
37* Scrub memory contents in a way that a compiler should not elide,
38* using some system specific technique. Note that this function might
39* not zero the memory (for example, in some hypothetical
40* implementation it might combine the memory contents with the output
41* of a system PRNG), but if you can detect any difference in behavior
42* at runtime then the clearing is side-effecting and you can just
43* use `clear_mem`.
44*
45* Use this function to scrub memory just before deallocating it, or on
46* a stack buffer before returning from the function.
47*
48* @param ptr a pointer to memory to scrub
49* @param n the number of bytes pointed to by ptr
50*/
51BOTAN_PUBLIC_API(2, 0) void secure_scrub_memory(void* ptr, size_t n);
52
53/**
54* Scrub memory contents in a way that a compiler should not elide,
55* using some system specific technique. Note that this function might
56* not zero the memory.
57*
58* @param data the data region to be scrubbed
59*/
60void secure_scrub_memory(ranges::contiguous_output_range auto&& data) {
61 secure_scrub_memory(std::ranges::data(data), ranges::size_bytes(data));
62}
63
64/**
65* Memory comparison, input insensitive
66* @param x a pointer to an array
67* @param y a pointer to another array
68* @param len the number of Ts in x and y
69* @return 0xFF iff x[i] == y[i] forall i in [0...n) or 0x00 otherwise
70*/
71BOTAN_DEPRECATED("This function is deprecated, use constant_time_compare()")
72BOTAN_PUBLIC_API(2, 9) uint8_t ct_compare_u8(const uint8_t x[], const uint8_t y[], size_t len);
73
74/**
75 * Memory comparison, input insensitive
76 * @param x a range of bytes
77 * @param y another range of bytes
78 * @return true iff x and y have equal lengths and x[i] == y[i] forall i in [0...n)
79 */
80BOTAN_PUBLIC_API(3, 3) bool constant_time_compare(std::span<const uint8_t> x, std::span<const uint8_t> y);
81
82/**
83* Memory comparison, input insensitive
84* @param x a pointer to an array
85* @param y a pointer to another array
86* @param len the number of Ts in x and y
87* @return true iff x[i] == y[i] forall i in [0...n)
88*/
89inline bool constant_time_compare(const uint8_t x[], const uint8_t y[], size_t len) {
90 // simply assumes that *x and *y point to len allocated bytes at least
91 return constant_time_compare({x, len}, {y, len});
92}
93
94/**
95* Zero out some bytes. Warning: use secure_scrub_memory instead if the
96* memory is about to be freed or otherwise the compiler thinks it can
97* elide the writes.
98*
99* @param ptr a pointer to memory to zero
100* @param bytes the number of bytes to zero in ptr
101*/
102inline constexpr void clear_bytes(void* ptr, size_t bytes) {
103 if(bytes > 0) {
104 std::memset(ptr, 0, bytes);
105 }
106}
107
108/**
109* Zero memory before use. This simply calls memset and should not be
110* used in cases where the compiler cannot see the call as a
111* side-effecting operation (for example, if calling clear_mem before
112* deallocating memory, the compiler would be allowed to omit the call
113* to memset entirely under the as-if rule.)
114*
115* @param ptr a pointer to an array of Ts to zero
116* @param n the number of Ts pointed to by ptr
117*/
118template <typename T>
119inline constexpr void clear_mem(T* ptr, size_t n) {
120 clear_bytes(ptr, sizeof(T) * n);
121}
122
123/**
124* Zero memory before use. This simply calls memset and should not be
125* used in cases where the compiler cannot see the call as a
126* side-effecting operation.
127*
128* @param mem a contiguous range of Ts to zero
129*/
130template <ranges::contiguous_output_range R>
131inline constexpr void clear_mem(R&& mem) // NOLINT(*-missing-std-forward)
132 requires std::is_trivially_copyable_v<std::ranges::range_value_t<R>>
133{
134 clear_bytes(std::ranges::data(mem), ranges::size_bytes(mem));
135}
136
137/**
138* Copy memory
139* @param out the destination array
140* @param in the source array
141* @param n the number of elements of in/out
142*/
143template <typename T>
144 requires std::is_trivial_v<std::decay_t<T>>
145inline constexpr void copy_mem(T* out, const T* in, size_t n) {
146 BOTAN_ASSERT_IMPLICATION(n > 0, in != nullptr && out != nullptr, "If n > 0 then args are not null");
147
148 if(in != nullptr && out != nullptr && n > 0) {
149 std::memmove(out, in, sizeof(T) * n);
150 }
151}
152
153/**
154* Copy memory
155* @param out the destination array
156* @param in the source array
157*/
158template <ranges::contiguous_output_range OutR, ranges::contiguous_range InR>
159 requires std::is_same_v<std::ranges::range_value_t<OutR>, std::ranges::range_value_t<InR>> &&
160 std::is_trivially_copyable_v<std::ranges::range_value_t<InR>>
161inline constexpr void copy_mem(OutR&& out /* NOLINT(*-std-forward) */, const InR& in) {
163 if(std::is_constant_evaluated()) {
164 std::copy(std::ranges::begin(in), std::ranges::end(in), std::ranges::begin(out));
165 } else if(ranges::size_bytes(out) > 0) {
166 std::memmove(std::ranges::data(out), std::ranges::data(in), ranges::size_bytes(out));
167 }
168}
169
170/**
171 * Copy a range of a trivially copyable type into another range of trivially
172 * copyable type of matching byte length.
173 */
174template <ranges::contiguous_output_range ToR, ranges::contiguous_range FromR>
175 requires std::is_trivially_copyable_v<std::ranges::range_value_t<FromR>> &&
176 std::is_trivially_copyable_v<std::ranges::range_value_t<ToR>>
177inline constexpr void typecast_copy(ToR&& out /* NOLINT(*-std-forward) */, const FromR& in) {
179 std::memcpy(std::ranges::data(out), std::ranges::data(in), ranges::size_bytes(out));
180}
181
182/**
183 * Copy a range of trivially copyable type into an instance of trivially
184 * copyable type with matching length.
185 */
186template <typename ToT, ranges::contiguous_range FromR>
187 requires std::is_trivially_copyable_v<std::ranges::range_value_t<FromR>> && std::is_trivially_copyable_v<ToT> &&
188 (!std::ranges::range<ToT>)
189inline constexpr void typecast_copy(ToT& out, const FromR& in) {
190 typecast_copy(std::span<ToT, 1>(&out, 1), in);
191}
192
193/**
194 * Copy an instance of trivially copyable type into a range of trivially
195 * copyable type with matching length.
196 */
197template <ranges::contiguous_output_range ToR, typename FromT>
198 requires std::is_trivially_copyable_v<FromT> &&
199 (!std::ranges::range<FromT>) && std::is_trivially_copyable_v<std::ranges::range_value_t<ToR>>
200inline constexpr void typecast_copy(ToR&& out /* NOLINT(*-std-forward) */, const FromT& in) {
201 typecast_copy(out, std::span<const FromT, 1>(&in, 1));
202}
203
204/**
205 * Create a trivial type by bit-casting a range of trivially copyable type with
206 * matching length into it.
207 */
208template <typename ToT, ranges::contiguous_range FromR>
209 requires std::is_default_constructible_v<ToT> && std::is_trivially_copyable_v<ToT> &&
210 std::is_trivially_copyable_v<std::ranges::range_value_t<FromR>>
211inline constexpr ToT typecast_copy(const FromR& src) {
212 ToT dst; // NOLINT(*-member-init)
213 typecast_copy(dst, src);
214 return dst;
215}
216
217// TODO: deprecate and replace
218template <typename T>
219inline constexpr void typecast_copy(uint8_t out[], T in[], size_t N)
220 requires std::is_trivially_copyable_v<T>
221{
222 // asserts that *in and *out point to the correct amount of memory
223 typecast_copy(std::span<uint8_t>(out, sizeof(T) * N), std::span<const T>(in, N));
224}
225
226// TODO: deprecate and replace
227template <typename T>
228inline constexpr void typecast_copy(T out[], const uint8_t in[], size_t N)
229 requires std::is_trivial_v<T>
230{
231 // asserts that *in and *out point to the correct amount of memory
232 typecast_copy(std::span<T>(out, N), std::span<const uint8_t>(in, N * sizeof(T)));
233}
234
235// TODO: deprecate and replace
236template <typename T>
237inline constexpr void typecast_copy(uint8_t out[], const T& in) {
238 // asserts that *out points to the correct amount of memory
239 typecast_copy(std::span<uint8_t, sizeof(T)>(out, sizeof(T)), in);
240}
241
242// TODO: deprecate and replace
243template <typename T>
244 requires std::is_trivial_v<std::decay_t<T>>
245inline constexpr void typecast_copy(T& out, const uint8_t in[]) {
246 // asserts that *in points to the correct amount of memory
247 typecast_copy(out, std::span<const uint8_t, sizeof(T)>(in, sizeof(T)));
248}
249
250// TODO: deprecate and replace
251template <typename To>
252 requires std::is_trivial_v<To>
253inline constexpr To typecast_copy(const uint8_t src[]) noexcept {
254 // asserts that *src points to the correct amount of memory
255 return typecast_copy<To>(std::span<const uint8_t, sizeof(To)>(src, sizeof(To)));
256}
257
258#if !defined(BOTAN_IS_BEING_BUILT)
259/**
260* Set memory to a fixed value
261* @param ptr a pointer to an array of bytes
262* @param n the number of Ts pointed to by ptr
263* @param val the value to set each byte to
264*/
265BOTAN_DEPRECATED("This function is deprecated") inline constexpr void set_mem(uint8_t* ptr, size_t n, uint8_t val) {
266 if(n > 0) {
267 std::memset(ptr, val, n);
268 }
269}
270#endif
271
272#if !defined(BOTAN_IS_BEING_BUILT)
273inline const uint8_t* cast_char_ptr_to_uint8(const char* s) {
274 return reinterpret_cast<const uint8_t*>(s);
275}
276
277inline uint8_t* cast_char_ptr_to_uint8(char* s) {
278 return reinterpret_cast<uint8_t*>(s);
279}
280#endif
281
282inline const char* cast_uint8_ptr_to_char(const uint8_t* b) {
283 return reinterpret_cast<const char*>(b);
284}
285
286inline char* cast_uint8_ptr_to_char(uint8_t* b) {
287 return reinterpret_cast<char*>(b);
288}
289
290#if !defined(BOTAN_IS_BEING_BUILT)
291/**
292* Memory comparison, input insensitive
293* @param p1 a pointer to an array
294* @param p2 a pointer to another array
295* @param n the number of Ts in p1 and p2
296* @return true iff p1[i] == p2[i] forall i in [0...n)
297*/
298template <typename T>
299BOTAN_DEPRECATED("This function is deprecated")
300inline bool same_mem(const T* p1, const T* p2, size_t n) {
301 volatile T difference = 0;
302
303 for(size_t i = 0; i != n; ++i) {
304 difference = difference | (p1[i] ^ p2[i]);
305 }
306
307 return difference == 0;
308}
309#endif
310
311#if !defined(BOTAN_IS_BEING_BUILT)
312
313template <typename T, typename Alloc>
314BOTAN_DEPRECATED("The buffer_insert functions are deprecated")
315size_t buffer_insert(std::vector<T, Alloc>& buf, size_t buf_offset, const T input[], size_t input_length) {
316 BOTAN_ASSERT_NOMSG(buf_offset <= buf.size());
317 const size_t to_copy = std::min(input_length, buf.size() - buf_offset);
318 if(to_copy > 0) {
319 copy_mem(&buf[buf_offset], input, to_copy);
320 }
321 return to_copy;
322}
323
324template <typename T, typename Alloc, typename Alloc2>
325BOTAN_DEPRECATED("The buffer_insert functions are deprecated")
326size_t buffer_insert(std::vector<T, Alloc>& buf, size_t buf_offset, const std::vector<T, Alloc2>& input) {
327 BOTAN_ASSERT_NOMSG(buf_offset <= buf.size());
328 const size_t to_copy = std::min(input.size(), buf.size() - buf_offset);
329 if(to_copy > 0) {
330 copy_mem(&buf[buf_offset], input.data(), to_copy);
331 }
332 return to_copy;
333}
334
335#endif
336
337/**
338* XOR arrays. Postcondition out[i] = in[i] ^ out[i] forall i = 0...length
339* @param out the input/output range
340* @param in the read-only input range
341*/
342inline constexpr void xor_buf(ranges::contiguous_output_range<uint8_t> auto&& out,
345
346 std::span<uint8_t> o(out);
347 std::span<const uint8_t> i(in);
348
349 for(; o.size_bytes() >= 32; o = o.subspan(32), i = i.subspan(32)) {
350 auto x = typecast_copy<std::array<uint64_t, 4>>(o.template first<32>());
351 const auto y = typecast_copy<std::array<uint64_t, 4>>(i.template first<32>());
352
353 x[0] ^= y[0];
354 x[1] ^= y[1];
355 x[2] ^= y[2];
356 x[3] ^= y[3];
357
358 typecast_copy(o.template first<32>(), x);
359 }
360
361 for(size_t off = 0; off != o.size_bytes(); ++off) {
362 o[off] ^= i[off];
363 }
364}
365
366/**
367* XOR arrays. Postcondition out[i] = in1[i] ^ in2[i] forall i = 0...length
368* @param out the output range
369* @param in1 the first input range
370* @param in2 the second input range
371*/
372inline constexpr void xor_buf(ranges::contiguous_output_range<uint8_t> auto&& out,
376
377 std::span o{out};
378 std::span i1{in1};
379 std::span i2{in2};
380
381 for(; o.size_bytes() >= 32; o = o.subspan(32), i1 = i1.subspan(32), i2 = i2.subspan(32)) {
382 auto x = typecast_copy<std::array<uint64_t, 4>>(i1.template first<32>());
383 const auto y = typecast_copy<std::array<uint64_t, 4>>(i2.template first<32>());
384
385 x[0] ^= y[0];
386 x[1] ^= y[1];
387 x[2] ^= y[2];
388 x[3] ^= y[3];
389
390 typecast_copy(o.template first<32>(), x);
391 }
392
393 for(size_t off = 0; off != o.size_bytes(); ++off) {
394 o[off] = i1[off] ^ i2[off];
395 }
396}
397
398/**
399* XOR arrays. Postcondition out[i] = in[i] ^ out[i] forall i = 0...length
400* @param out the input/output buffer
401* @param in the read-only input buffer
402* @param length the length of the buffers
403*/
404inline void xor_buf(uint8_t out[], const uint8_t in[], size_t length) {
405 // simply assumes that *out and *in point to "length" allocated bytes at least
406 xor_buf(std::span{out, length}, std::span{in, length});
407}
408
409/**
410* XOR arrays. Postcondition out[i] = in[i] ^ in2[i] forall i = 0...length
411* @param out the output buffer
412* @param in the first input buffer
413* @param in2 the second input buffer
414* @param length the length of the three buffers
415*/
416inline void xor_buf(uint8_t out[], const uint8_t in[], const uint8_t in2[], size_t length) {
417 // simply assumes that *out, *in, and *in2 point to "length" allocated bytes at least
418 xor_buf(std::span{out, length}, std::span{in, length}, std::span{in2, length});
419}
420
421// TODO: deprecate and replace, use .subspan()
422inline void xor_buf(std::span<uint8_t> out, std::span<const uint8_t> in, size_t n) {
423 BOTAN_ARG_CHECK(out.size() >= n, "output span is too small");
424 BOTAN_ARG_CHECK(in.size() >= n, "input span is too small");
425 xor_buf(out.first(n), in.first(n));
426}
427
428// TODO: deprecate and replace, use .subspan()
429template <typename Alloc>
430void xor_buf(std::vector<uint8_t, Alloc>& out, const uint8_t* in, size_t n) {
431 BOTAN_ARG_CHECK(out.size() >= n, "output vector is too small");
432 // simply assumes that *in points to "n" allocated bytes at least
433 xor_buf(std::span{out}.first(n), std::span{in, n});
434}
435
436// TODO: deprecate and replace
437template <typename Alloc, typename Alloc2>
438void xor_buf(std::vector<uint8_t, Alloc>& out, const uint8_t* in, const std::vector<uint8_t, Alloc2>& in2, size_t n) {
439 BOTAN_ARG_CHECK(out.size() >= n, "output vector is too small");
440 BOTAN_ARG_CHECK(in2.size() >= n, "input vector is too small");
441 // simply assumes that *in points to "n" allocated bytes at least
442 xor_buf(std::span{out}.first(n), std::span{in, n}, std::span{in2}.first(n));
443}
444
445template <typename Alloc, typename Alloc2>
446std::vector<uint8_t, Alloc>& operator^=(std::vector<uint8_t, Alloc>& out, const std::vector<uint8_t, Alloc2>& in) {
447 if(out.size() < in.size()) {
448 out.resize(in.size());
449 }
450
451 xor_buf(std::span{out}.first(in.size()), in);
452 return out;
453}
454
455} // namespace Botan
456
457#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_FUTURE_INTERNAL_HEADER(hdr)
Definition api.h:98
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:75
#define BOTAN_ASSERT_IMPLICATION(expr1, expr2, msg)
Definition assert.h:101
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
constexpr size_t size_bytes(const spanable_range auto &r)
Definition concepts.h:94
constexpr void assert_equal_byte_lengths(const R0 &r0, const Rs &... rs)
Definition concepts.h:128
size_t buffer_insert(std::vector< T, Alloc > &buf, size_t buf_offset, const T input[], size_t input_length)
Definition mem_ops.h:315
constexpr void copy_mem(T *out, const T *in, size_t n)
Definition mem_ops.h:145
constexpr void set_mem(uint8_t *ptr, size_t n, uint8_t val)
Definition mem_ops.h:265
constexpr void clear_bytes(void *ptr, size_t bytes)
Definition mem_ops.h:102
void secure_scrub_memory(void *ptr, size_t n)
Definition mem_utils.cpp:24
uint8_t ct_compare_u8(const uint8_t x[], const uint8_t y[], size_t len)
Definition mem_ops.cpp:13
std::vector< uint8_t, Alloc > & operator^=(std::vector< uint8_t, Alloc > &out, const std::vector< uint8_t, Alloc2 > &in)
Definition mem_ops.h:446
constexpr void xor_buf(ranges::contiguous_output_range< uint8_t > auto &&out, ranges::contiguous_range< uint8_t > auto &&in)
Definition mem_ops.h:342
bool same_mem(const T *p1, const T *p2, size_t n)
Definition mem_ops.h:300
const char * cast_uint8_ptr_to_char(const uint8_t *b)
Definition mem_ops.h:282
constexpr void typecast_copy(ToR &&out, const FromR &in)
Definition mem_ops.h:177
bool constant_time_compare(std::span< const uint8_t > x, std::span< const uint8_t > y)
Definition mem_ops.cpp:17
constexpr void clear_mem(T *ptr, size_t n)
Definition mem_ops.h:119
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition mem_ops.h:273