include/openssl/macros.h

0001 /*
0002  * Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
0003  *
0004  * Licensed under the Apache License 2.0 (the "License").  You may not use
0005  * this file except in compliance with the License.  You can obtain a copy
0006  * in the file LICENSE in the source distribution or at
0007  * https://www.openssl.org/source/license.html
0008  */
0009
0010 #ifndef OPENSSL_MACROS_H
0011 # define OPENSSL_MACROS_H
0012 # pragma once
0013
0014 #include <openssl/opensslconf.h>
0015 #include <openssl/opensslv.h>
0016
0017
0018 /* Helper macros for CPP string composition */
0019 # define OPENSSL_MSTR_HELPER(x) #x
0020 # define OPENSSL_MSTR(x) OPENSSL_MSTR_HELPER(x)
0021
0022 /*
0023  * Sometimes OPENSSL_NO_xxx ends up with an empty file and some compilers
0024  * don't like that.  This will hopefully silence them.
0025  */
0026 # define NON_EMPTY_TRANSLATION_UNIT static void *dummy = &dummy;
0027
0028 /*
0029  * Generic deprecation macro
0030  *
0031  * If OPENSSL_SUPPRESS_DEPRECATED is defined, then OSSL_DEPRECATED and
0032  * OSSL_DEPRECATED_FOR become no-ops
0033  */
0034 # ifndef OSSL_DEPRECATED
0035 #  undef OSSL_DEPRECATED_FOR
0036 #  ifndef OPENSSL_SUPPRESS_DEPRECATED
0037 #   if defined(_MSC_VER)
0038      /*
0039       * MSVC supports __declspec(deprecated) since MSVC 2003 (13.10),
0040       * and __declspec(deprecated(message)) since MSVC 2005 (14.00)
0041       */
0042 #    if _MSC_VER >= 1400
0043 #     define OSSL_DEPRECATED(since) \
0044           __declspec(deprecated("Since OpenSSL " # since))
0045 #     define OSSL_DEPRECATED_FOR(since, message) \
0046           __declspec(deprecated("Since OpenSSL " # since ";" message))
0047 #    elif _MSC_VER >= 1310
0048 #     define OSSL_DEPRECATED(since) __declspec(deprecated)
0049 #     define OSSL_DEPRECATED_FOR(since, message) __declspec(deprecated)
0050 #    endif
0051 #   elif defined(__GNUC__)
0052      /*
0053       * According to GCC documentation, deprecations with message appeared in
0054       * GCC 4.5.0
0055       */
0056 #    if __GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 5)
0057 #     define OSSL_DEPRECATED(since) \
0058           __attribute__((deprecated("Since OpenSSL " # since)))
0059 #     define OSSL_DEPRECATED_FOR(since, message) \
0060           __attribute__((deprecated("Since OpenSSL " # since ";" message)))
0061 #    elif __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ > 0)
0062 #     define OSSL_DEPRECATED(since) __attribute__((deprecated))
0063 #     define OSSL_DEPRECATED_FOR(since, message) __attribute__((deprecated))
0064 #    endif
0065 #   elif defined(__SUNPRO_C)
0066 #    if (__SUNPRO_C >= 0x5130)
0067 #     define OSSL_DEPRECATED(since) __attribute__ ((deprecated))
0068 #     define OSSL_DEPRECATED_FOR(since, message) __attribute__ ((deprecated))
0069 #    endif
0070 #   endif
0071 #  endif
0072 # endif
0073
0074 /*
0075  * Still not defined?  Then define no-op macros. This means these macros
0076  * are unsuitable for use in a typedef.
0077  */
0078 # ifndef OSSL_DEPRECATED
0079 #  define OSSL_DEPRECATED(since)                extern
0080 #  define OSSL_DEPRECATED_FOR(since, message)   extern
0081 # endif
0082
0083 /*
0084  * Applications should use -DOPENSSL_API_COMPAT=<version> to suppress the
0085  * declarations of functions deprecated in or before <version>.  If this is
0086  * undefined, the value of the macro OPENSSL_CONFIGURED_API (defined in
0087  * <openssl/opensslconf.h>) is the default.
0088  *
0089  * For any version number up until version 1.1.x, <version> is expected to be
0090  * the calculated version number 0xMNNFFPPSL.
0091  * For version numbers 3.0 and on, <version> is expected to be a computation
0092  * of the major and minor numbers in decimal using this formula:
0093  *
0094  *     MAJOR * 10000 + MINOR * 100
0095  *
0096  * So version 3.0 becomes 30000, version 3.2 becomes 30200, etc.
0097  */
0098
0099 /*
0100  * We use the OPENSSL_API_COMPAT value to define API level macros.  These
0101  * macros are used to enable or disable features at that API version boundary.
0102  */
0103
0104 # ifdef OPENSSL_API_LEVEL
0105 #  error "OPENSSL_API_LEVEL must not be defined by application"
0106 # endif
0107
0108 /*
0109  * We figure out what API level was intended by simple numeric comparison.
0110  * The lowest old style number we recognise is 0x00908000L, so we take some
0111  * safety margin and assume that anything below 0x00900000L is a new style
0112  * number.  This allows new versions up to and including v943.71.83.
0113  */
0114 # ifdef OPENSSL_API_COMPAT
0115 #  if OPENSSL_API_COMPAT < 0x900000L
0116 #   define OPENSSL_API_LEVEL (OPENSSL_API_COMPAT)
0117 #  else
0118 #   define OPENSSL_API_LEVEL                            \
0119            (((OPENSSL_API_COMPAT >> 28) & 0xF) * 10000  \
0120             + ((OPENSSL_API_COMPAT >> 20) & 0xFF) * 100 \
0121             + ((OPENSSL_API_COMPAT >> 12) & 0xFF))
0122 #  endif
0123 # endif
0124
0125 /*
0126  * If OPENSSL_API_COMPAT wasn't given, we use default numbers to set
0127  * the API compatibility level.
0128  */
0129 # ifndef OPENSSL_API_LEVEL
0130 #  if OPENSSL_CONFIGURED_API > 0
0131 #   define OPENSSL_API_LEVEL (OPENSSL_CONFIGURED_API)
0132 #  else
0133 #   define OPENSSL_API_LEVEL \
0134            (OPENSSL_VERSION_MAJOR * 10000 + OPENSSL_VERSION_MINOR * 100)
0135 #  endif
0136 # endif
0137
0138 # if OPENSSL_API_LEVEL > OPENSSL_CONFIGURED_API
0139 #  error "The requested API level higher than the configured API compatibility level"
0140 # endif
0141
0142 /*
0143  * Check of sane values.
0144  */
0145 /* Can't go higher than the current version. */
0146 # if OPENSSL_API_LEVEL > (OPENSSL_VERSION_MAJOR * 10000 + OPENSSL_VERSION_MINOR * 100)
0147 #  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
0148 # endif
0149 /* OpenSSL will have no version 2.y.z */
0150 # if OPENSSL_API_LEVEL < 30000 && OPENSSL_API_LEVEL >= 20000
0151 #  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
0152 # endif
0153 /* Below 0.9.8 is unacceptably low */
0154 # if OPENSSL_API_LEVEL < 908
0155 #  error "OPENSSL_API_COMPAT expresses an impossible API compatibility level"
0156 # endif
0157
0158 /*
0159  * Define macros for deprecation and simulated removal purposes.
0160  *
0161  * The macros OSSL_DEPRECATEDIN_{major}_{minor} are always defined for
0162  * all OpenSSL versions we care for.  They can be used as attributes
0163  * in function declarations where appropriate.
0164  *
0165  * The macros OPENSSL_NO_DEPRECATED_{major}_{minor} are defined for
0166  * all OpenSSL versions up to or equal to the version given with
0167  * OPENSSL_API_COMPAT.  They are used as guards around anything that's
0168  * deprecated up to that version, as an effect of the developer option
0169  * 'no-deprecated'.
0170  */
0171
0172 # undef OPENSSL_NO_DEPRECATED_3_4
0173 # undef OPENSSL_NO_DEPRECATED_3_1
0174 # undef OPENSSL_NO_DEPRECATED_3_0
0175 # undef OPENSSL_NO_DEPRECATED_1_1_1
0176 # undef OPENSSL_NO_DEPRECATED_1_1_0
0177 # undef OPENSSL_NO_DEPRECATED_1_0_2
0178 # undef OPENSSL_NO_DEPRECATED_1_0_1
0179 # undef OPENSSL_NO_DEPRECATED_1_0_0
0180 # undef OPENSSL_NO_DEPRECATED_0_9_8
0181
0182 # if OPENSSL_API_LEVEL >= 30400
0183 #  ifndef OPENSSL_NO_DEPRECATED
0184 #   define OSSL_DEPRECATEDIN_3_4                OSSL_DEPRECATED(3.4)
0185 #   define OSSL_DEPRECATEDIN_3_4_FOR(msg)       OSSL_DEPRECATED_FOR(3.4, msg)
0186 #  else
0187 #   define OPENSSL_NO_DEPRECATED_3_4
0188 #  endif
0189 # else
0190 #  define OSSL_DEPRECATEDIN_3_4
0191 #  define OSSL_DEPRECATEDIN_3_4_FOR(msg)
0192 # endif
0193 # if OPENSSL_API_LEVEL >= 30100
0194 #  ifndef OPENSSL_NO_DEPRECATED
0195 #   define OSSL_DEPRECATEDIN_3_1                OSSL_DEPRECATED(3.1)
0196 #   define OSSL_DEPRECATEDIN_3_1_FOR(msg)       OSSL_DEPRECATED_FOR(3.1, msg)
0197 #  else
0198 #   define OPENSSL_NO_DEPRECATED_3_1
0199 #  endif
0200 # else
0201 #  define OSSL_DEPRECATEDIN_3_1
0202 #  define OSSL_DEPRECATEDIN_3_1_FOR(msg)
0203 # endif
0204 # if OPENSSL_API_LEVEL >= 30000
0205 #  ifndef OPENSSL_NO_DEPRECATED
0206 #   define OSSL_DEPRECATEDIN_3_0                OSSL_DEPRECATED(3.0)
0207 #   define OSSL_DEPRECATEDIN_3_0_FOR(msg)       OSSL_DEPRECATED_FOR(3.0, msg)
0208 #  else
0209 #   define OPENSSL_NO_DEPRECATED_3_0
0210 #  endif
0211 # else
0212 #  define OSSL_DEPRECATEDIN_3_0
0213 #  define OSSL_DEPRECATEDIN_3_0_FOR(msg)
0214 # endif
0215 # if OPENSSL_API_LEVEL >= 10101
0216 #  ifndef OPENSSL_NO_DEPRECATED
0217 #   define OSSL_DEPRECATEDIN_1_1_1              OSSL_DEPRECATED(1.1.1)
0218 #   define OSSL_DEPRECATEDIN_1_1_1_FOR(msg)     OSSL_DEPRECATED_FOR(1.1.1, msg)
0219 #  else
0220 #   define OPENSSL_NO_DEPRECATED_1_1_1
0221 #  endif
0222 # else
0223 #  define OSSL_DEPRECATEDIN_1_1_1
0224 #  define OSSL_DEPRECATEDIN_1_1_1_FOR(msg)
0225 # endif
0226 # if OPENSSL_API_LEVEL >= 10100
0227 #  ifndef OPENSSL_NO_DEPRECATED
0228 #   define OSSL_DEPRECATEDIN_1_1_0              OSSL_DEPRECATED(1.1.0)
0229 #   define OSSL_DEPRECATEDIN_1_1_0_FOR(msg)     OSSL_DEPRECATED_FOR(1.1.0, msg)
0230 #  else
0231 #   define OPENSSL_NO_DEPRECATED_1_1_0
0232 #  endif
0233 # else
0234 #  define OSSL_DEPRECATEDIN_1_1_0
0235 #  define OSSL_DEPRECATEDIN_1_1_0_FOR(msg)
0236 # endif
0237 # if OPENSSL_API_LEVEL >= 10002
0238 #  ifndef OPENSSL_NO_DEPRECATED
0239 #   define OSSL_DEPRECATEDIN_1_0_2              OSSL_DEPRECATED(1.0.2)
0240 #   define OSSL_DEPRECATEDIN_1_0_2_FOR(msg)     OSSL_DEPRECATED_FOR(1.0.2, msg)
0241 #  else
0242 #   define OPENSSL_NO_DEPRECATED_1_0_2
0243 #  endif
0244 # else
0245 #  define OSSL_DEPRECATEDIN_1_0_2
0246 #  define OSSL_DEPRECATEDIN_1_0_2_FOR(msg)
0247 # endif
0248 # if OPENSSL_API_LEVEL >= 10001
0249 #  ifndef OPENSSL_NO_DEPRECATED
0250 #   define OSSL_DEPRECATEDIN_1_0_1              OSSL_DEPRECATED(1.0.1)
0251 #   define OSSL_DEPRECATEDIN_1_0_1_FOR(msg)     OSSL_DEPRECATED_FOR(1.0.1, msg)
0252 #  else
0253 #   define OPENSSL_NO_DEPRECATED_1_0_1
0254 #  endif
0255 # else
0256 #  define OSSL_DEPRECATEDIN_1_0_1
0257 #  define OSSL_DEPRECATEDIN_1_0_1_FOR(msg)
0258 # endif
0259 # if OPENSSL_API_LEVEL >= 10000
0260 #  ifndef OPENSSL_NO_DEPRECATED
0261 #   define OSSL_DEPRECATEDIN_1_0_0              OSSL_DEPRECATED(1.0.0)
0262 #   define OSSL_DEPRECATEDIN_1_0_0_FOR(msg)     OSSL_DEPRECATED_FOR(1.0.0, msg)
0263 #  else
0264 #   define OPENSSL_NO_DEPRECATED_1_0_0
0265 #  endif
0266 # else
0267 #  define OSSL_DEPRECATEDIN_1_0_0
0268 #  define OSSL_DEPRECATEDIN_1_0_0_FOR(msg)
0269 # endif
0270 # if OPENSSL_API_LEVEL >= 908
0271 #  ifndef OPENSSL_NO_DEPRECATED
0272 #   define OSSL_DEPRECATEDIN_0_9_8              OSSL_DEPRECATED(0.9.8)
0273 #   define OSSL_DEPRECATEDIN_0_9_8_FOR(msg)     OSSL_DEPRECATED_FOR(0.9.8, msg)
0274 #  else
0275 #   define OPENSSL_NO_DEPRECATED_0_9_8
0276 #  endif
0277 # else
0278 #  define OSSL_DEPRECATEDIN_0_9_8
0279 #  define OSSL_DEPRECATEDIN_0_9_8_FOR(msg)
0280 # endif
0281
0282 /*
0283  * Make our own variants of __FILE__ and __LINE__, depending on configuration
0284  */
0285
0286 # ifndef OPENSSL_FILE
0287 #  ifdef OPENSSL_NO_FILENAMES
0288 #   define OPENSSL_FILE ""
0289 #   define OPENSSL_LINE 0
0290 #  else
0291 #   define OPENSSL_FILE __FILE__
0292 #   define OPENSSL_LINE __LINE__
0293 #  endif
0294 # endif
0295
0296 /*
0297  * __func__ was standardized in C99, so for any compiler that claims
0298  * to implement that language level or newer, we assume we can safely
0299  * use that symbol.
0300  *
0301  * GNU C also provides __FUNCTION__ since version 2, which predates
0302  * C99.  We can, however, only use this if __STDC_VERSION__ exists,
0303  * as it's otherwise not allowed according to ISO C standards (C90).
0304  * (compiling with GNU C's -pedantic tells us so)
0305  *
0306  * If none of the above applies, we check if the compiler is MSVC,
0307  * and use __FUNCTION__ if that's the case.
0308  */
0309 # ifndef OPENSSL_FUNC
0310 #  if defined(__STDC_VERSION__)
0311 #   if __STDC_VERSION__ >= 199901L
0312 #    define OPENSSL_FUNC __func__
0313 #   elif defined(__GNUC__) && __GNUC__ >= 2
0314 #    define OPENSSL_FUNC __FUNCTION__
0315 #   endif
0316 #  elif defined(_MSC_VER)
0317 #    define OPENSSL_FUNC __FUNCTION__
0318 #  endif
0319 /*
0320  * If all these possibilities are exhausted, we give up and use a
0321  * static string.
0322  */
0323 #  ifndef OPENSSL_FUNC
0324 #   define OPENSSL_FUNC "(unknown function)"
0325 #  endif
0326 # endif
0327
0328 # ifndef OSSL_CRYPTO_ALLOC
0329 #  if defined(__GNUC__)
0330 #   define OSSL_CRYPTO_ALLOC __attribute__((__malloc__))
0331 #  elif defined(_MSC_VER)
0332 #   define OSSL_CRYPTO_ALLOC __declspec(restrict)
0333 #  else
0334 #   define OSSL_CRYPTO_ALLOC
0335 #  endif
0336 # endif
0337
0338 #endif  /* OPENSSL_MACROS_H */