blob: 6d0f76478a3ad6127b22d4d30833638bceb7a647 [file] [log] [blame]
Gilles Peskine87270e52023-11-02 17:14:01 +01001/**
2 * \file memory.h
3 *
4 * \brief Helper macros and functions related to testing memory management.
5 */
6
7/*
8 * Copyright The Mbed TLS Contributors
9 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
10 */
11
12#ifndef TEST_MEMORY_H
13#define TEST_MEMORY_H
14
15#include "test/helpers.h"
16#include "mbedtls/platform.h"
17
Gilles Peskine071d1442023-11-02 20:49:34 +010018/** \def MBEDTLS_TEST_MEMORY_CAN_POISON
19 *
20 * This macro is defined if the tests are compiled with a method to mark
21 * memory as poisoned, which can be used to enforce some memory access
22 * policies.
23 *
David Horstmann756b4dc2024-01-10 14:33:17 +000024 * Support for the C11 thread_local keyword is also required.
25 *
Gilles Peskine071d1442023-11-02 20:49:34 +010026 * Currently, only Asan (Address Sanitizer) is supported.
27 */
David Horstmann756b4dc2024-01-10 14:33:17 +000028#if defined(MBEDTLS_TEST_HAVE_ASAN) && \
29 (__STDC_VERSION__ >= 201112L)
Gilles Peskine071d1442023-11-02 20:49:34 +010030# define MBEDTLS_TEST_MEMORY_CAN_POISON
31#endif
32
33/** \def MBEDTLS_TEST_MEMORY_POISON(buf, size)
34 *
35 * Poison a memory area so that any attempt to read or write from it will
36 * cause a runtime failure.
37 *
Gilles Peskine962c5da2023-11-02 22:44:32 +010038 * Depending on the implementation, this may poison a few bytes beyond the
39 * indicated region, but will never poison a separate object on the heap
40 * or a separate object with more than the alignment of a long long.
41 *
Gilles Peskine071d1442023-11-02 20:49:34 +010042 * The behavior is undefined if any part of the memory area is invalid.
43 *
44 * This is a no-op in builds without a poisoning method.
45 * See #MBEDTLS_TEST_MEMORY_CAN_POISON.
46 *
47 * \param buf Pointer to the beginning of the memory area to poison.
48 * \param size Size of the memory area in bytes.
49 */
50
51/** \def MBEDTLS_TEST_MEMORY_UNPOISON(buf, size)
52 *
53 * Undo the effect of #MBEDTLS_TEST_MEMORY_POISON.
54 *
55 * The behavior is undefined if any part of the memory area is invalid,
56 * or if the memory area contains a mixture of poisoned and unpoisoned parts.
57 *
58 * This is a no-op in builds without a poisoning method.
59 * See #MBEDTLS_TEST_MEMORY_CAN_POISON.
60 *
61 * \param buf Pointer to the beginning of the memory area to unpoison.
62 * \param size Size of the memory area in bytes.
63 */
64
65#if defined(MBEDTLS_TEST_MEMORY_CAN_POISON)
66
David Horstmann756b4dc2024-01-10 14:33:17 +000067/** Thread-local variable used to enable memory poisoning. This is set and
68 * unset in the test wrappers so that calls to PSA functions from the library
69 * do not poison memory.
70 */
David Horstmann6de58282024-01-17 14:23:20 +000071extern _Thread_local unsigned int mbedtls_test_memory_poisoning_count;
David Horstmann756b4dc2024-01-10 14:33:17 +000072
Gilles Peskine071d1442023-11-02 20:49:34 +010073/** Poison a memory area so that any attempt to read or write from it will
74 * cause a runtime failure.
75 *
76 * The behavior is undefined if any part of the memory area is invalid.
77 */
78void mbedtls_test_memory_poison(const unsigned char *ptr, size_t size);
79#define MBEDTLS_TEST_MEMORY_POISON(ptr, size) \
David Horstmann756b4dc2024-01-10 14:33:17 +000080 do { \
David Horstmann6de58282024-01-17 14:23:20 +000081 mbedtls_test_memory_poisoning_count++; \
David Horstmann756b4dc2024-01-10 14:33:17 +000082 mbedtls_test_memory_poison(ptr, size); \
83 } while (0)
Gilles Peskine071d1442023-11-02 20:49:34 +010084
85/** Undo the effect of mbedtls_test_memory_poison().
86 *
87 * This is a no-op if the given area is entirely valid, unpoisoned memory.
88 *
89 * The behavior is undefined if any part of the memory area is invalid,
90 * or if the memory area contains a mixture of poisoned and unpoisoned parts.
91 */
92void mbedtls_test_memory_unpoison(const unsigned char *ptr, size_t size);
93#define MBEDTLS_TEST_MEMORY_UNPOISON(ptr, size) \
David Horstmann756b4dc2024-01-10 14:33:17 +000094 do { \
95 mbedtls_test_memory_unpoison(ptr, size); \
David Horstmann6de58282024-01-17 14:23:20 +000096 mbedtls_test_memory_poisoning_count--; \
David Horstmann756b4dc2024-01-10 14:33:17 +000097 } while (0)
Gilles Peskine071d1442023-11-02 20:49:34 +010098
99#else /* MBEDTLS_TEST_MEMORY_CAN_POISON */
Gilles Peskine014d89b2023-11-22 18:13:46 +0100100#define MBEDTLS_TEST_MEMORY_POISON(ptr, size) ((void) (ptr), (void) (size))
101#define MBEDTLS_TEST_MEMORY_UNPOISON(ptr, size) ((void) (ptr), (void) (size))
Gilles Peskine071d1442023-11-02 20:49:34 +0100102#endif /* MBEDTLS_TEST_MEMORY_CAN_POISON */
103
Gilles Peskine87270e52023-11-02 17:14:01 +0100104#endif /* TEST_MEMORY_H */