include/openssl/macros.h

   1 /*
   2  * Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
   3  *
   4  * Licensed under the Apache License 2.0 (the "License").  You may not use
   5  * this file except in compliance with the License.  You can obtain a copy
   6  * in the file LICENSE in the source distribution or at
   7  * https://www.openssl.org/source/license.html
   8  */
   9
  10 #ifndef OPENSSL_MACROS_H
  11 # define OPENSSL_MACROS_H
  12 # pragma once
  13
  14 #include <openssl/opensslconf.h>
  15 #include <openssl/opensslv.h>
  16
  17
  18 /* Helper macros for CPP string composition */
  19 # define OPENSSL_MSTR_HELPER(x) #x
  20 # define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)
  21
  22 /*
  23  * Sometimes OPENSSL_NO_xxx ends up with an empty file and some compilers
  24  * don't like that.  This will hopefully silence them.
  25  */
  26 # define NON_EMPTY_TRANSLATION_UNIT static void *dummy = &dummy;
  27
  28 /*
  29  * Generic deprecation macro
  30  *
  31  * If OPENSSL_SUPPRESS_DEPRECATED is defined, then OSSL_DEPRECATED and
  32  * OSSL_DEPRECATED_FOR become no-ops
  33  */
  34 # ifndef OSSL_DEPRECATED
  35 #  undef OSSL_DEPRECATED_FOR
  36 #  ifndef OPENSSL_SUPPRESS_DEPRECATED
  37 #   if defined(_MSC_VER)
  38      /*
  39       * MSVC supports __declspec(deprecated) since MSVC 2003 (13.10),
  40       * and __declspec(deprecated(message)) since MSVC 2005 (14.00)
  41       */
  42 #    if _MSC_VER >= 1400
  43 #     define OSSL_DEPRECATED(since) \
  44           __declspec(deprecated("Since OpenSSL " # since))
  45 #     define OSSL_DEPRECATED_FOR(since, message) \
  46           __declspec(deprecated("Since OpenSSL " # since ";" message))
  47 #    elif _MSC_VER >= 1310
  48 #     define OSSL_DEPRECATED(since) __declspec(deprecated)
  49 #     define OSSL_DEPRECATED_FOR(since, message) __declspec(deprecated)
  50 #    endif
  51 #   elif defined(__GNUC__)
  52      /*
  53       * According to GCC documentation, deprecations with message appeared in
  54       * GCC 4.5.0
  55       */
  56 #    if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
  57 #     define OSSL_DEPRECATED(since) \
  58           __attribute__((deprecated("Since OpenSSL " # since)))
  59 #     define OSSL_DEPRECATED_FOR(since, message) \
  60           __attribute__((deprecated("Since OpenSSL " # since ";" message)))
  61 #    elif __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ > 0)
  62 #     define OSSL_DEPRECATED(since) __attribute__((deprecated))
  63 #     define OSSL_DEPRECATED_FOR(since, message) __attribute__((deprecated))
  64 #    endif
  65 #   elif defined(__SUNPRO_C)
  66 #    if (__SUNPRO_C >= 0x5130)
  67 #     define OSSL_DEPRECATED(since) __attribute__ ((deprecated))
  68 #     define OSSL_DEPRECATED_FOR(since, message) __attribute__ ((deprecated))
  69 #    endif
  70 #   endif
  71 #  endif
  72 # endif
  73
  74 /*
  75  * Still not defined?  Then define no-op macros. This means these macros
  76  * are unsuitable for use in a typedef.
  77  */
  78 # ifndef OSSL_DEPRECATED
  79 #  define OSSL_DEPRECATED(since)                extern
  80 #  define OSSL_DEPRECATED_FOR(since, message)   extern
  81 # endif
  82
  83 /*
  84  * Applications should use -DOPENSSL_API_COMPAT=<version> to suppress the
  85  * declarations of functions deprecated in or before <version>.  If this is
  86  * undefined, the value of the macro OPENSSL_CONFIGURED_API (defined in
  87  * <openssl/opensslconf.h>) is the default.
  88  *
  89  * For any version number up until version 1.1.x, <version> is expected to be
  90  * the calculated version number 0xMNNFFPPSL.
  91  * For version numbers 3.0 and on, <version> is expected to be a computation
  92  * of the major and minor numbers in decimal using this formula:
  93  *
  94  *     MAJOR * 10000 + MINOR * 100
  95  *
  96  * So version 3.0 becomes 30000, version 3.2 becomes 30200, etc.
  97  */
  98
  99 /*
 100  * We use the OPENSSL_API_COMPAT value to define API level macros.  These
 101  * macros are used to enable or disable features at that API version boundary.
 102  */
 103
 104 # ifdef OPENSSL_API_LEVEL
 105 #  error "OPENSSL_API_LEVEL must not be defined by application"
 106 # endif
 107
 108 /*
 109  * We figure out what API level was intended by simple numeric comparison.
 110  * The lowest old style number we recognise is 0x00908000L, so we take some
 111  * safety margin and assume that anything below 0x00900000L is a new style
 112  * number.  This allows new versions up to and including v943.71.83.
 113  */
 114 # ifdef OPENSSL_API_COMPAT
 115 #  if OPENSSL_API_COMPAT < 0x900000L
 116 #   define OPENSSL_API_LEVEL (OPENSSL_API_COMPAT)
 117 #  else
 118 #   define OPENSSL_API_LEVEL                            \
 119            (((OPENSSL_API_COMPAT >> 28) & 0xF) * 10000  \
 120             + ((OPENSSL_API_COMPAT >> 20) & 0xFF) * 100 \
 121             + ((OPENSSL_API_COMPAT >> 12) & 0xFF))
 122 #  endif
 123 # endif
 124
 125 /*
 126  * If OPENSSL_API_COMPAT wasn't given, we use default numbers to set
 127  * the API compatibility level.
 128  */
 129 # ifndef OPENSSL_API_LEVEL
 130 #  if OPENSSL_CONFIGURED_API > 0
 131 #   define OPENSSL_API_LEVEL (OPENSSL_CONFIGURED_API)
 132 #  else
 133 #   define OPENSSL_API_LEVEL \
 134            (OPENSSL_VERSION_MAJOR * 10000 + OPENSSL_VERSION_MINOR * 100)
 135 #  endif
 136 # endif
 137
 138 # if OPENSSL_API_LEVEL > OPENSSL_CONFIGURED_API
 139 #  error "The requested API level higher than the configured API compatibility level"
 140 # endif
 141
 142 /*
 143  * Check of sane values.
 144  */
 145 /* Can't go higher than the current version. */
 146 # if OPENSSL_API_LEVEL > (OPENSSL_VERSION_MAJOR * 10000 + OPENSSL_VERSION_MINOR * 100)
 147 #  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
 148 # endif
 149 /* OpenSSL will have no version 2.y.z */
 150 # if OPENSSL_API_LEVEL < 30000 && OPENSSL_API_LEVEL >= 20000
 151 #  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
 152 # endif
 153 /* Below 0.9.8 is unacceptably low */
 154 # if OPENSSL_API_LEVEL < 908
 155 #  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
 156 # endif
 157
 158 /*
 159  * Define macros for deprecation and simulated removal purposes.
 160  *
 161  * The macros OSSL_DEPRECATEDIN_{major}_{minor} are always defined for
 162  * all OpenSSL versions we care for.  They can be used as attributes
 163  * in function declarations where appropriate.
 164  *
 165  * The macros OPENSSL_NO_DEPRECATED_{major}_{minor} are defined for
 166  * all OpenSSL versions up to or equal to the version given with
 167  * OPENSSL_API_COMPAT.  They are used as guards around anything that's
 168  * deprecated up to that version, as an effect of the developer option
 169  * 'no-deprecated'.
 170  */
 171
 172 # undef OPENSSL_NO_DEPRECATED_3_1
 173 # undef OPENSSL_NO_DEPRECATED_3_0
 174 # undef OPENSSL_NO_DEPRECATED_1_1_1
 175 # undef OPENSSL_NO_DEPRECATED_1_1_0
 176 # undef OPENSSL_NO_DEPRECATED_1_0_2
 177 # undef OPENSSL_NO_DEPRECATED_1_0_1
 178 # undef OPENSSL_NO_DEPRECATED_1_0_0
 179 # undef OPENSSL_NO_DEPRECATED_0_9_8
 180
 181 # if OPENSSL_API_LEVEL >= 30100
 182 #  ifndef OPENSSL_NO_DEPRECATED
 183 #   define OSSL_DEPRECATEDIN_3_1                OSSL_DEPRECATED(3.1)
 184 #   define OSSL_DEPRECATEDIN_3_1_FOR(msg)       OSSL_DEPRECATED_FOR(3.1, msg)
 185 #  else
 186 #   define OPENSSL_NO_DEPRECATED_3_1
 187 #  endif
 188 # else
 189 #  define OSSL_DEPRECATEDIN_3_1
 190 #  define OSSL_DEPRECATEDIN_3_1_FOR(msg)
 191 # endif
 192 # if OPENSSL_API_LEVEL >= 30000
 193 #  ifndef OPENSSL_NO_DEPRECATED
 194 #   define OSSL_DEPRECATEDIN_3_0                OSSL_DEPRECATED(3.0)
 195 #   define OSSL_DEPRECATEDIN_3_0_FOR(msg)       OSSL_DEPRECATED_FOR(3.0, msg)
 196 #  else
 197 #   define OPENSSL_NO_DEPRECATED_3_0
 198 #  endif
 199 # else
 200 #  define OSSL_DEPRECATEDIN_3_0
 201 #  define OSSL_DEPRECATEDIN_3_0_FOR(msg)
 202 # endif
 203 # if OPENSSL_API_LEVEL >= 10101
 204 #  ifndef OPENSSL_NO_DEPRECATED
 205 #   define OSSL_DEPRECATEDIN_1_1_1              OSSL_DEPRECATED(1.1.1)
 206 #   define OSSL_DEPRECATEDIN_1_1_1_FOR(msg)     OSSL_DEPRECATED_FOR(1.1.1, msg)
 207 #  else
 208 #   define OPENSSL_NO_DEPRECATED_1_1_1
 209 #  endif
 210 # else
 211 #  define OSSL_DEPRECATEDIN_1_1_1
 212 #  define OSSL_DEPRECATEDIN_1_1_1_FOR(msg)
 213 # endif
 214 # if OPENSSL_API_LEVEL >= 10100
 215 #  ifndef OPENSSL_NO_DEPRECATED
 216 #   define OSSL_DEPRECATEDIN_1_1_0              OSSL_DEPRECATED(1.1.0)
 217 #   define OSSL_DEPRECATEDIN_1_1_0_FOR(msg)     OSSL_DEPRECATED_FOR(1.1.0, msg)
 218 #  else
 219 #   define OPENSSL_NO_DEPRECATED_1_1_0
 220 #  endif
 221 # else
 222 #  define OSSL_DEPRECATEDIN_1_1_0
 223 #  define OSSL_DEPRECATEDIN_1_1_0_FOR(msg)
 224 # endif
 225 # if OPENSSL_API_LEVEL >= 10002
 226 #  ifndef OPENSSL_NO_DEPRECATED
 227 #   define OSSL_DEPRECATEDIN_1_0_2              OSSL_DEPRECATED(1.0.2)
 228 #   define OSSL_DEPRECATEDIN_1_0_2_FOR(msg)     OSSL_DEPRECATED_FOR(1.0.2, msg)
 229 #  else
 230 #   define OPENSSL_NO_DEPRECATED_1_0_2
 231 #  endif
 232 # else
 233 #  define OSSL_DEPRECATEDIN_1_0_2
 234 #  define OSSL_DEPRECATEDIN_1_0_2_FOR(msg)
 235 # endif
 236 # if OPENSSL_API_LEVEL >= 10001
 237 #  ifndef OPENSSL_NO_DEPRECATED
 238 #   define OSSL_DEPRECATEDIN_1_0_1              OSSL_DEPRECATED(1.0.1)
 239 #   define OSSL_DEPRECATEDIN_1_0_1_FOR(msg)     OSSL_DEPRECATED_FOR(1.0.1, msg)
 240 #  else
 241 #   define OPENSSL_NO_DEPRECATED_1_0_1
 242 #  endif
 243 # else
 244 #  define OSSL_DEPRECATEDIN_1_0_1
 245 #  define OSSL_DEPRECATEDIN_1_0_1_FOR(msg)
 246 # endif
 247 # if OPENSSL_API_LEVEL >= 10000
 248 #  ifndef OPENSSL_NO_DEPRECATED
 249 #   define OSSL_DEPRECATEDIN_1_0_0              OSSL_DEPRECATED(1.0.0)
 250 #   define OSSL_DEPRECATEDIN_1_0_0_FOR(msg)     OSSL_DEPRECATED_FOR(1.0.0, msg)
 251 #  else
 252 #   define OPENSSL_NO_DEPRECATED_1_0_0
 253 #  endif
 254 # else
 255 #  define OSSL_DEPRECATEDIN_1_0_0
 256 #  define OSSL_DEPRECATEDIN_1_0_0_FOR(msg)
 257 # endif
 258 # if OPENSSL_API_LEVEL >= 908
 259 #  ifndef OPENSSL_NO_DEPRECATED
 260 #   define OSSL_DEPRECATEDIN_0_9_8              OSSL_DEPRECATED(0.9.8)
 261 #   define OSSL_DEPRECATEDIN_0_9_8_FOR(msg)     OSSL_DEPRECATED_FOR(0.9.8, msg)
 262 #  else
 263 #   define OPENSSL_NO_DEPRECATED_0_9_8
 264 #  endif
 265 # else
 266 #  define OSSL_DEPRECATEDIN_0_9_8
 267 #  define OSSL_DEPRECATEDIN_0_9_8_FOR(msg)
 268 # endif
 269
 270 /*
 271  * Make our own variants of __FILE__ and __LINE__, depending on configuration
 272  */
 273
 274 # ifndef OPENSSL_FILE
 275 #  ifdef OPENSSL_NO_FILENAMES
 276 #   define OPENSSL_FILE ""
 277 #   define OPENSSL_LINE 0
 278 #  else
 279 #   define OPENSSL_FILE __FILE__
 280 #   define OPENSSL_LINE __LINE__
 281 #  endif
 282 # endif
 283
 284 /*
 285  * __func__ was standardized in C99, so for any compiler that claims
 286  * to implement that language level or newer, we assume we can safely
 287  * use that symbol.
 288  *
 289  * GNU C also provides __FUNCTION__ since version 2, which predates
 290  * C99.  We can, however, only use this if __STDC_VERSION__ exists,
 291  * as it's otherwise not allowed according to ISO C standards (C90).
 292  * (compiling with GNU C's -pedantic tells us so)
 293  *
 294  * If none of the above applies, we check if the compiler is MSVC,
 295  * and use __FUNCTION__ if that's the case.
 296  */
 297 # ifndef OPENSSL_FUNC
 298 #  if defined(__STDC_VERSION__)
 299 #   if __STDC_VERSION__ >= 199901L
 300 #    define OPENSSL_FUNC __func__
 301 #   elif defined(__GNUC__) && __GNUC__ >= 2
 302 #    define OPENSSL_FUNC __FUNCTION__
 303 #   endif
 304 #  elif defined(_MSC_VER)
 305 #    define OPENSSL_FUNC __FUNCTION__
 306 #  endif
 307 /*
 308  * If all these possibilities are exhausted, we give up and use a
 309  * static string.
 310  */
 311 #  ifndef OPENSSL_FUNC
 312 #   define OPENSSL_FUNC "(unknown function)"
 313 #  endif
 314 # endif
 315
 316 # ifndef OSSL_CRYPTO_ALLOC
 317 #  if defined(__GNUC__)
 318 #   define OSSL_CRYPTO_ALLOC __attribute__((__malloc__))
 319 #  elif defined(_MSC_VER)
 320 #   define OSSL_CRYPTO_ALLOC __declspec(restrict)
 321 #  else
 322 #   define OSSL_CRYPTO_ALLOC
 323 #  endif
 324 # endif
 325
 326 #endif  /* OPENSSL_MACROS_H */