blob: 43fbb6350f09c086f2766b96e7afd43c62b94efe [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 */
Gilles Peskine071d1442023-11-02 20:49:34 +010026#if defined(MBEDTLS_TEST_HAVE_ASAN)
27# 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
64/** Poison a memory area so that any attempt to read or write from it will
65 * cause a runtime failure.
66 *
67 * The behavior is undefined if any part of the memory area is invalid.
68 */
69void mbedtls_test_memory_poison(const unsigned char *ptr, size_t size);
70#define MBEDTLS_TEST_MEMORY_POISON(ptr, size) \
71 mbedtls_test_memory_poison(ptr, size)
72
73/** Undo the effect of mbedtls_test_memory_poison().
74 *
75 * This is a no-op if the given area is entirely valid, unpoisoned memory.
76 *
77 * The behavior is undefined if any part of the memory area is invalid,
78 * or if the memory area contains a mixture of poisoned and unpoisoned parts.
79 */
80void mbedtls_test_memory_unpoison(const unsigned char *ptr, size_t size);
81#define MBEDTLS_TEST_MEMORY_UNPOISON(ptr, size) \
82 mbedtls_test_memory_unpoison(ptr, size)
83
84#else /* MBEDTLS_TEST_MEMORY_CAN_POISON */
Gilles Peskine014d89b2023-11-22 18:13:46 +010085#define MBEDTLS_TEST_MEMORY_POISON(ptr, size) ((void) (ptr), (void) (size))
86#define MBEDTLS_TEST_MEMORY_UNPOISON(ptr, size) ((void) (ptr), (void) (size))
Gilles Peskine071d1442023-11-02 20:49:34 +010087#endif /* MBEDTLS_TEST_MEMORY_CAN_POISON */
88
Gilles Peskine87270e52023-11-02 17:14:01 +010089#endif /* TEST_MEMORY_H */