mps_common.h (7273B)
1 /* 2 * Copyright The Mbed TLS Contributors 3 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 4 */ 5 6 /** 7 * \file mps_common.h 8 * 9 * \brief Common functions and macros used by MPS 10 */ 11 12 #ifndef MBEDTLS_MPS_COMMON_H 13 #define MBEDTLS_MPS_COMMON_H 14 15 #include "mps_error.h" 16 17 #include <stdio.h> 18 19 /** 20 * \name SECTION: MPS Configuration 21 * 22 * \{ 23 */ 24 25 /*! This flag controls whether the MPS-internal components 26 * (reader, writer, Layer 1-3) perform validation of the 27 * expected abstract state at the entry of API calls. 28 * 29 * Context: All MPS API functions impose assumptions/preconditions on the 30 * context on which they operate. For example, every structure has a notion of 31 * state integrity which is established by `xxx_init()` and preserved by any 32 * calls to the MPS API which satisfy their preconditions and either succeed, 33 * or fail with an error code which is explicitly documented to not corrupt 34 * structure integrity (such as WANT_READ and WANT_WRITE); 35 * apart from `xxx_init()` any function assumes state integrity as a 36 * precondition (but usually more). If any of the preconditions is violated, 37 * the function's behavior is entirely undefined. 38 * In addition to state integrity, all MPS structures have a more refined 39 * notion of abstract state that the API operates on. For example, all layers 40 * have a notion of 'abstract read state' which indicates if incoming data has 41 * been passed to the user, e.g. through mps_l2_read_start() for Layer 2 42 * or mps_l3_read() in Layer 3. After such a call, it doesn't make sense to 43 * call these reading functions again until the incoming data has been 44 * explicitly 'consumed', e.g. through mps_l2_read_consume() for Layer 2 or 45 * mps_l3_read_consume() on Layer 3. However, even if it doesn't make sense, 46 * it's a design choice whether the API should fail gracefully on such 47 * non-sensical calls or not, and that's what this option is about: 48 * 49 * This option determines whether the expected abstract state 50 * is part of the API preconditions or not: If the option is set, 51 * then the abstract state is not part of the precondition and is 52 * thus required to be validated by the implementation. If an unexpected 53 * abstract state is encountered, the implementation must fail gracefully 54 * with error #MBEDTLS_ERR_MPS_OPERATION_UNEXPECTED. 55 * Conversely, if this option is not set, then the expected abstract state 56 * is included in the preconditions of the respective API calls, and 57 * an implementation's behaviour is undefined if the abstract state is 58 * not as expected. 59 * 60 * For example: Enabling this makes mps_l2_read_done() fail if 61 * no incoming record is currently open; disabling this would 62 * lead to undefined behavior in this case. 63 * 64 * Comment this to remove state validation. 65 */ 66 #define MBEDTLS_MPS_STATE_VALIDATION 67 68 /*! This flag enables/disables assertions on the internal state of MPS. 69 * 70 * Assertions are sanity checks that should never trigger when MPS 71 * is used within the bounds of its API and preconditions. 72 * 73 * Enabling this increases security by limiting the scope of 74 * potential bugs, but comes at the cost of increased code size. 75 * 76 * Note: So far, there is no guiding principle as to what 77 * expected conditions merit an assertion, and which don't. 78 * 79 * Comment this to disable assertions. 80 */ 81 #define MBEDTLS_MPS_ENABLE_ASSERTIONS 82 83 /*! This flag controls whether tracing for MPS should be enabled. */ 84 //#define MBEDTLS_MPS_ENABLE_TRACE 85 86 #if defined(MBEDTLS_MPS_STATE_VALIDATION) 87 88 #define MBEDTLS_MPS_STATE_VALIDATE_RAW(cond, string) \ 89 do \ 90 { \ 91 if (!(cond)) \ 92 { \ 93 MBEDTLS_MPS_TRACE(MBEDTLS_MPS_TRACE_TYPE_ERROR, string); \ 94 MBEDTLS_MPS_TRACE_RETURN(MBEDTLS_ERR_MPS_OPERATION_UNEXPECTED); \ 95 } \ 96 } while (0) 97 98 #else /* MBEDTLS_MPS_STATE_VALIDATION */ 99 100 #define MBEDTLS_MPS_STATE_VALIDATE_RAW(cond, string) \ 101 do \ 102 { \ 103 (cond); \ 104 } while (0) 105 106 #endif /* MBEDTLS_MPS_STATE_VALIDATION */ 107 108 #if defined(MBEDTLS_MPS_ENABLE_ASSERTIONS) 109 110 #define MBEDTLS_MPS_ASSERT_RAW(cond, string) \ 111 do \ 112 { \ 113 if (!(cond)) \ 114 { \ 115 MBEDTLS_MPS_TRACE(MBEDTLS_MPS_TRACE_TYPE_ERROR, string); \ 116 MBEDTLS_MPS_TRACE_RETURN(MBEDTLS_ERR_MPS_INTERNAL_ERROR); \ 117 } \ 118 } while (0) 119 120 #else /* MBEDTLS_MPS_ENABLE_ASSERTIONS */ 121 122 #define MBEDTLS_MPS_ASSERT_RAW(cond, string) do {} while (0) 123 124 #endif /* MBEDTLS_MPS_ENABLE_ASSERTIONS */ 125 126 127 /* \} name SECTION: MPS Configuration */ 128 129 /** 130 * \name SECTION: Common types 131 * 132 * Various common types used throughout MPS. 133 * \{ 134 */ 135 136 /** \brief The type of buffer sizes and offsets used in MPS structures. 137 * 138 * This is an unsigned integer type that should be large enough to 139 * hold the length of any buffer or message processed by MPS. 140 * 141 * The reason to pick a value as small as possible here is 142 * to reduce the size of MPS structures. 143 * 144 * \warning Care has to be taken when using a narrower type 145 * than ::mbedtls_mps_size_t here because of 146 * potential truncation during conversion. 147 * 148 * \warning Handshake messages in TLS may be up to 2^24 ~ 16Mb in size. 149 * If mbedtls_mps_[opt_]stored_size_t is smaller than that, the 150 * maximum handshake message is restricted accordingly. 151 * 152 * For now, we use the default type of size_t throughout, and the use of 153 * smaller types or different types for ::mbedtls_mps_size_t and 154 * ::mbedtls_mps_stored_size_t is not yet supported. 155 * 156 */ 157 typedef size_t mbedtls_mps_stored_size_t; 158 #define MBEDTLS_MPS_STORED_SIZE_MAX (SIZE_MAX) 159 160 /** \brief The type of buffer sizes and offsets used in the MPS API 161 * and implementation. 162 * 163 * This must be at least as wide as ::mbedtls_stored_size_t but 164 * may be chosen to be strictly larger if more suitable for the 165 * target architecture. 166 * 167 * For example, in a test build for ARM Thumb, using uint_fast16_t 168 * instead of uint16_t reduced the code size from 1060 Byte to 962 Byte, 169 * so almost 10%. 170 */ 171 typedef size_t mbedtls_mps_size_t; 172 #define MBEDTLS_MPS_SIZE_MAX (SIZE_MAX) 173 174 #if MBEDTLS_MPS_STORED_SIZE_MAX > MBEDTLS_MPS_SIZE_MAX 175 #error "Misconfiguration of mbedtls_mps_size_t and mbedtls_mps_stored_size_t." 176 #endif 177 178 /* \} SECTION: Common types */ 179 180 181 #endif /* MBEDTLS_MPS_COMMON_H */