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