git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/mbedtls/include/mbedtls/platform_util.h

   1 /**\r
   2  * \file platform_util.h\r
   3  *\r
   4  * \brief Common and shared functions used by multiple modules in the Mbed TLS\r
   5  *        library.\r
   6  */\r
   7 /*\r
   8  *  Copyright (C) 2018, Arm Limited, All Rights Reserved\r
   9  *  SPDX-License-Identifier: Apache-2.0\r
  10  *\r
  11  *  Licensed under the Apache License, Version 2.0 (the "License"); you may\r
  12  *  not use this file except in compliance with the License.\r
  13  *  You may obtain a copy of the License at\r
  14  *\r
  15  *  http://www.apache.org/licenses/LICENSE-2.0\r
  16  *\r
  17  *  Unless required by applicable law or agreed to in writing, software\r
  18  *  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT\r
  19  *  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  20  *  See the License for the specific language governing permissions and\r
  21  *  limitations under the License.\r
  22  *\r
  23  *  This file is part of Mbed TLS (https://tls.mbed.org)\r
  24  */\r
  25 #ifndef MBEDTLS_PLATFORM_UTIL_H\r
  26 #define MBEDTLS_PLATFORM_UTIL_H\r
  27 \r
  28 #if !defined(MBEDTLS_CONFIG_FILE)\r
  29 #include "config.h"\r
  30 #else\r
  31 #include MBEDTLS_CONFIG_FILE\r
  32 #endif\r
  33 \r
  34 #include <stddef.h>\r
  35 #if defined(MBEDTLS_HAVE_TIME_DATE)\r
  36 #include "platform_time.h"\r
  37 #include <time.h>\r
  38 #endif /* MBEDTLS_HAVE_TIME_DATE */\r
  39 \r
  40 #ifdef __cplusplus\r
  41 extern "C" {\r
  42 #endif\r
  43 \r
  44 #if defined(MBEDTLS_CHECK_PARAMS)\r
  45 \r
  46 #if defined(MBEDTLS_PARAM_FAILED)\r
  47 /** An alternative definition of MBEDTLS_PARAM_FAILED has been set in config.h.\r
  48  *\r
  49  * This flag can be used to check whether it is safe to assume that\r
  50  * MBEDTLS_PARAM_FAILED() will expand to a call to mbedtls_param_failed().\r
  51  */\r
  52 #define MBEDTLS_PARAM_FAILED_ALT\r
  53 #else /* MBEDTLS_PARAM_FAILED */\r
  54 #define MBEDTLS_PARAM_FAILED( cond ) \\r
  55     mbedtls_param_failed( #cond, __FILE__, __LINE__ )\r
  56 \r
  57 /**\r
  58  * \brief       User supplied callback function for parameter validation failure.\r
  59  *              See #MBEDTLS_CHECK_PARAMS for context.\r
  60  *\r
  61  *              This function will be called unless an alternative treatement\r
  62  *              is defined through the #MBEDTLS_PARAM_FAILED macro.\r
  63  *\r
  64  *              This function can return, and the operation will be aborted, or\r
  65  *              alternatively, through use of setjmp()/longjmp() can resume\r
  66  *              execution in the application code.\r
  67  *\r
  68  * \param failure_condition The assertion that didn't hold.\r
  69  * \param file  The file where the assertion failed.\r
  70  * \param line  The line in the file where the assertion failed.\r
  71  */\r
  72 void mbedtls_param_failed( const char *failure_condition,\r
  73                            const char *file,\r
  74                            int line );\r
  75 #endif /* MBEDTLS_PARAM_FAILED */\r
  76 \r
  77 /* Internal macro meant to be called only from within the library. */\r
  78 #define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret )  \\r
  79     do {                                            \\r
  80         if( !(cond) )                               \\r
  81         {                                           \\r
  82             MBEDTLS_PARAM_FAILED( cond );           \\r
  83             return( ret );                          \\r
  84         }                                           \\r
  85     } while( 0 )\r
  86 \r
  87 /* Internal macro meant to be called only from within the library. */\r
  88 #define MBEDTLS_INTERNAL_VALIDATE( cond )           \\r
  89     do {                                            \\r
  90         if( !(cond) )                               \\r
  91         {                                           \\r
  92             MBEDTLS_PARAM_FAILED( cond );           \\r
  93             return;                                 \\r
  94         }                                           \\r
  95     } while( 0 )\r
  96 \r
  97 #else /* MBEDTLS_CHECK_PARAMS */\r
  98 \r
  99 /* Internal macros meant to be called only from within the library. */\r
 100 #define MBEDTLS_INTERNAL_VALIDATE_RET( cond, ret )  do { } while( 0 )\r
 101 #define MBEDTLS_INTERNAL_VALIDATE( cond )           do { } while( 0 )\r
 102 \r
 103 #endif /* MBEDTLS_CHECK_PARAMS */\r
 104 \r
 105 /* Internal helper macros for deprecating API constants. */\r
 106 #if !defined(MBEDTLS_DEPRECATED_REMOVED)\r
 107 #if defined(MBEDTLS_DEPRECATED_WARNING)\r
 108 /* Deliberately don't (yet) export MBEDTLS_DEPRECATED here\r
 109  * to avoid conflict with other headers which define and use\r
 110  * it, too. We might want to move all these definitions here at\r
 111  * some point for uniformity. */\r
 112 #define MBEDTLS_DEPRECATED __attribute__((deprecated))\r
 113 MBEDTLS_DEPRECATED typedef char const * mbedtls_deprecated_string_constant_t;\r
 114 #define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL )       \\r
 115     ( (mbedtls_deprecated_string_constant_t) ( VAL ) )\r
 116 MBEDTLS_DEPRECATED typedef int mbedtls_deprecated_numeric_constant_t;\r
 117 #define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL )       \\r
 118     ( (mbedtls_deprecated_numeric_constant_t) ( VAL ) )\r
 119 #undef MBEDTLS_DEPRECATED\r
 120 #else /* MBEDTLS_DEPRECATED_WARNING */\r
 121 #define MBEDTLS_DEPRECATED_STRING_CONSTANT( VAL ) VAL\r
 122 #define MBEDTLS_DEPRECATED_NUMERIC_CONSTANT( VAL ) VAL\r
 123 #endif /* MBEDTLS_DEPRECATED_WARNING */\r
 124 #endif /* MBEDTLS_DEPRECATED_REMOVED */\r
 125 \r
 126 /**\r
 127  * \brief       Securely zeroize a buffer\r
 128  *\r
 129  *              The function is meant to wipe the data contained in a buffer so\r
 130  *              that it can no longer be recovered even if the program memory\r
 131  *              is later compromised. Call this function on sensitive data\r
 132  *              stored on the stack before returning from a function, and on\r
 133  *              sensitive data stored on the heap before freeing the heap\r
 134  *              object.\r
 135  *\r
 136  *              It is extremely difficult to guarantee that calls to\r
 137  *              mbedtls_platform_zeroize() are not removed by aggressive\r
 138  *              compiler optimizations in a portable way. For this reason, Mbed\r
 139  *              TLS provides the configuration option\r
 140  *              MBEDTLS_PLATFORM_ZEROIZE_ALT, which allows users to configure\r
 141  *              mbedtls_platform_zeroize() to use a suitable implementation for\r
 142  *              their platform and needs\r
 143  *\r
 144  * \param buf   Buffer to be zeroized\r
 145  * \param len   Length of the buffer in bytes\r
 146  *\r
 147  */\r
 148 void mbedtls_platform_zeroize( void *buf, size_t len );\r
 149 \r
 150 #if defined(MBEDTLS_HAVE_TIME_DATE)\r
 151 /**\r
 152  * \brief      Platform-specific implementation of gmtime_r()\r
 153  *\r
 154  *             The function is a thread-safe abstraction that behaves\r
 155  *             similarly to the gmtime_r() function from Unix/POSIX.\r
 156  *\r
 157  *             Mbed TLS will try to identify the underlying platform and\r
 158  *             make use of an appropriate underlying implementation (e.g.\r
 159  *             gmtime_r() for POSIX and gmtime_s() for Windows). If this is\r
 160  *             not possible, then gmtime() will be used. In this case, calls\r
 161  *             from the library to gmtime() will be guarded by the mutex\r
 162  *             mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is\r
 163  *             enabled. It is recommended that calls from outside the library\r
 164  *             are also guarded by this mutex.\r
 165  *\r
 166  *             If MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, then Mbed TLS will\r
 167  *             unconditionally use the alternative implementation for\r
 168  *             mbedtls_platform_gmtime_r() supplied by the user at compile time.\r
 169  *\r
 170  * \param tt     Pointer to an object containing time (in seconds) since the\r
 171  *               epoch to be converted\r
 172  * \param tm_buf Pointer to an object where the results will be stored\r
 173  *\r
 174  * \return      Pointer to an object of type struct tm on success, otherwise\r
 175  *              NULL\r
 176  */\r
 177 struct tm *mbedtls_platform_gmtime_r( const mbedtls_time_t *tt,\r
 178                                       struct tm *tm_buf );\r
 179 #endif /* MBEDTLS_HAVE_TIME_DATE */\r
 180 \r
 181 #ifdef __cplusplus\r
 182 }\r
 183 #endif\r
 184 \r
 185 #endif /* MBEDTLS_PLATFORM_UTIL_H */\r