blob: d4bbeec0d4fecfcf79811b742b1abe7ae5929ebf [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 *
24 * Currently, only Asan (Address Sanitizer) is supported.
25 */
David Horstmann7dfb6122024-01-23 15:35:20 +000026#if defined(MBEDTLS_TEST_HAVE_ASAN)
Gilles Peskine071d1442023-11-02 20:49:34 +010027# define MBEDTLS_TEST_MEMORY_CAN_POISON
28#endif
29
30/** \def MBEDTLS_TEST_MEMORY_POISON(buf, size)
31 *
32 * Poison a memory area so that any attempt to read or write from it will
33 * cause a runtime failure.
34 *
Gilles Peskine962c5da2023-11-02 22:44:32 +010035 * Depending on the implementation, this may poison a few bytes beyond the
36 * indicated region, but will never poison a separate object on the heap
37 * or a separate object with more than the alignment of a long long.
38 *
Gilles Peskine071d1442023-11-02 20:49:34 +010039 * The behavior is undefined if any part of the memory area is invalid.
40 *
41 * This is a no-op in builds without a poisoning method.
42 * See #MBEDTLS_TEST_MEMORY_CAN_POISON.
43 *
44 * \param buf Pointer to the beginning of the memory area to poison.
45 * \param size Size of the memory area in bytes.
46 */
47
48/** \def MBEDTLS_TEST_MEMORY_UNPOISON(buf, size)
49 *
50 * Undo the effect of #MBEDTLS_TEST_MEMORY_POISON.
51 *
52 * The behavior is undefined if any part of the memory area is invalid,
53 * or if the memory area contains a mixture of poisoned and unpoisoned parts.
54 *
55 * This is a no-op in builds without a poisoning method.
56 * See #MBEDTLS_TEST_MEMORY_CAN_POISON.
57 *
58 * \param buf Pointer to the beginning of the memory area to unpoison.
59 * \param size Size of the memory area in bytes.
60 */
61
62#if defined(MBEDTLS_TEST_MEMORY_CAN_POISON)
63
David Horstmann7dfb6122024-01-23 15:35:20 +000064/** Variable used to enable memory poisoning. This is set and unset in the
65 * test wrappers so that calls to PSA functions from the library do not
66 * poison memory.
David Horstmann756b4dc2024-01-10 14:33:17 +000067 */
David Horstmann7dfb6122024-01-23 15:35:20 +000068extern unsigned int mbedtls_test_memory_poisoning_count;
David Horstmann756b4dc2024-01-10 14:33:17 +000069
Gilles Peskine071d1442023-11-02 20:49:34 +010070/** Poison a memory area so that any attempt to read or write from it will
71 * cause a runtime failure.
72 *
73 * The behavior is undefined if any part of the memory area is invalid.
74 */
75void mbedtls_test_memory_poison(const unsigned char *ptr, size_t size);
76#define MBEDTLS_TEST_MEMORY_POISON(ptr, size) \
David Horstmann756b4dc2024-01-10 14:33:17 +000077 do { \
David Horstmann6de58282024-01-17 14:23:20 +000078 mbedtls_test_memory_poisoning_count++; \
David Horstmann756b4dc2024-01-10 14:33:17 +000079 mbedtls_test_memory_poison(ptr, size); \
80 } while (0)
Gilles Peskine071d1442023-11-02 20:49:34 +010081
82/** Undo the effect of mbedtls_test_memory_poison().
83 *
84 * This is a no-op if the given area is entirely valid, unpoisoned memory.
85 *
86 * The behavior is undefined if any part of the memory area is invalid,
87 * or if the memory area contains a mixture of poisoned and unpoisoned parts.
88 */
89void mbedtls_test_memory_unpoison(const unsigned char *ptr, size_t size);
90#define MBEDTLS_TEST_MEMORY_UNPOISON(ptr, size) \
David Horstmann756b4dc2024-01-10 14:33:17 +000091 do { \
92 mbedtls_test_memory_unpoison(ptr, size); \
David Horstmanne7bfbc22024-01-17 15:27:50 +000093 if (mbedtls_test_memory_poisoning_count != 0) { \
94 mbedtls_test_memory_poisoning_count--; \
95 } \
David Horstmann756b4dc2024-01-10 14:33:17 +000096 } while (0)
Gilles Peskine071d1442023-11-02 20:49:34 +010097
98#else /* MBEDTLS_TEST_MEMORY_CAN_POISON */
Gilles Peskine014d89b2023-11-22 18:13:46 +010099#define MBEDTLS_TEST_MEMORY_POISON(ptr, size) ((void) (ptr), (void) (size))
100#define MBEDTLS_TEST_MEMORY_UNPOISON(ptr, size) ((void) (ptr), (void) (size))
Gilles Peskine071d1442023-11-02 20:49:34 +0100101#endif /* MBEDTLS_TEST_MEMORY_CAN_POISON */
102
Gilles Peskine87270e52023-11-02 17:14:01 +0100103#endif /* TEST_MEMORY_H */