/* * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later */ /** * \file mps_common.h * * \brief Common functions and macros used by MPS */ #ifndef MBEDTLS_MPS_COMMON_H #define MBEDTLS_MPS_COMMON_H #include "mps_error.h" #include <stdio.h> /** * \name SECTION: MPS Configuration * * \{ */ /*! This flag controls whether the MPS-internal components * (reader, writer, Layer 1-3) perform validation of the * expected abstract state at the entry of API calls. * * Context: All MPS API functions impose assumptions/preconditions on the * context on which they operate. For example, every structure has a notion of * state integrity which is established by `xxx_init()` and preserved by any * calls to the MPS API which satisfy their preconditions and either succeed, * or fail with an error code which is explicitly documented to not corrupt * structure integrity (such as WANT_READ and WANT_WRITE); * apart from `xxx_init()` any function assumes state integrity as a * precondition (but usually more). If any of the preconditions is violated, * the function's behavior is entirely undefined. * In addition to state integrity, all MPS structures have a more refined * notion of abstract state that the API operates on. For example, all layers * have a notion of 'abstract read state' which indicates if incoming data has * been passed to the user, e.g. through mps_l2_read_start() for Layer 2 * or mps_l3_read() in Layer 3. After such a call, it doesn't make sense to * call these reading functions again until the incoming data has been * explicitly 'consumed', e.g. through mps_l2_read_consume() for Layer 2 or * mps_l3_read_consume() on Layer 3. However, even if it doesn't make sense, * it's a design choice whether the API should fail gracefully on such * non-sensical calls or not, and that's what this option is about: * * This option determines whether the expected abstract state * is part of the API preconditions or not: If the option is set, * then the abstract state is not part of the precondition and is * thus required to be validated by the implementation. If an unexpected * abstract state is encountered, the implementation must fail gracefully * with error #MBEDTLS_ERR_MPS_OPERATION_UNEXPECTED. * Conversely, if this option is not set, then the expected abstract state * is included in the preconditions of the respective API calls, and * an implementation's behaviour is undefined if the abstract state is * not as expected. * * For example: Enabling this makes mps_l2_read_done() fail if * no incoming record is currently open; disabling this would * lead to undefined behavior in this case. * * Comment this to remove state validation. */ #define MBEDTLS_MPS_STATE_VALIDATION /*! This flag enables/disables assertions on the internal state of MPS. * * Assertions are sanity checks that should never trigger when MPS * is used within the bounds of its API and preconditions. * * Enabling this increases security by limiting the scope of * potential bugs, but comes at the cost of increased code size. * * Note: So far, there is no guiding principle as to what * expected conditions merit an assertion, and which don't. * * Comment this to disable assertions. */ #define MBEDTLS_MPS_ENABLE_ASSERTIONS /*! This flag controls whether tracing for MPS should be enabled. */ //#define MBEDTLS_MPS_ENABLE_TRACE #if defined(MBEDTLS_MPS_STATE_VALIDATION) #define MBEDTLS_MPS_STATE_VALIDATE_RAW(cond, string) … #else /* MBEDTLS_MPS_STATE_VALIDATION */ #define MBEDTLS_MPS_STATE_VALIDATE_RAW … #endif /* MBEDTLS_MPS_STATE_VALIDATION */ #if defined(MBEDTLS_MPS_ENABLE_ASSERTIONS) #define MBEDTLS_MPS_ASSERT_RAW(cond, string) … #else /* MBEDTLS_MPS_ENABLE_ASSERTIONS */ #define MBEDTLS_MPS_ASSERT_RAW … #endif /* MBEDTLS_MPS_ENABLE_ASSERTIONS */ /* \} name SECTION: MPS Configuration */ /** * \name SECTION: Common types * * Various common types used throughout MPS. * \{ */ /** \brief The type of buffer sizes and offsets used in MPS structures. * * This is an unsigned integer type that should be large enough to * hold the length of any buffer or message processed by MPS. * * The reason to pick a value as small as possible here is * to reduce the size of MPS structures. * * \warning Care has to be taken when using a narrower type * than ::mbedtls_mps_size_t here because of * potential truncation during conversion. * * \warning Handshake messages in TLS may be up to 2^24 ~ 16Mb in size. * If mbedtls_mps_[opt_]stored_size_t is smaller than that, the * maximum handshake message is restricted accordingly. * * For now, we use the default type of size_t throughout, and the use of * smaller types or different types for ::mbedtls_mps_size_t and * ::mbedtls_mps_stored_size_t is not yet supported. * */ mbedtls_mps_stored_size_t; #define MBEDTLS_MPS_STORED_SIZE_MAX … /** \brief The type of buffer sizes and offsets used in the MPS API * and implementation. * * This must be at least as wide as ::mbedtls_stored_size_t but * may be chosen to be strictly larger if more suitable for the * target architecture. * * For example, in a test build for ARM Thumb, using uint_fast16_t * instead of uint16_t reduced the code size from 1060 Byte to 962 Byte, * so almost 10%. */ mbedtls_mps_size_t; #define MBEDTLS_MPS_SIZE_MAX … #if MBEDTLS_MPS_STORED_SIZE_MAX > MBEDTLS_MPS_SIZE_MAX #error "Misconfiguration of mbedtls_mps_size_t and mbedtls_mps_stored_size_t." #endif /* \} SECTION: Common types */ #endif /* MBEDTLS_MPS_COMMON_H */
Codebase Browser
godot