diff options
Diffstat (limited to 'include/mbedtls/legacy_or_psa.h')
| -rw-r--r-- | include/mbedtls/legacy_or_psa.h | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/include/mbedtls/legacy_or_psa.h b/include/mbedtls/legacy_or_psa.h new file mode 100644 index 000000000..f872ddaf1 --- /dev/null +++ b/include/mbedtls/legacy_or_psa.h @@ -0,0 +1,215 @@ +/** + * Macros to express dependencies for code and tests that may use either the + * legacy API or PSA in various builds. This whole header file is currently + * for internal use only and both the header file and the macros it defines + * may change or be removed without notice. + */ +/* + * Copyright The Mbed TLS Contributors + * SPDX-License-Identifier: Apache-2.0 + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* + * Note: applications that are targeting a specific configuration do not need + * to use these macros; instead they should directly use the functions they + * know are available in their configuration. + * + * Note: code that is purely based on PSA Crypto (psa_xxx() functions) + * does not need to use these macros; instead it should use the relevant + * PSA_WANT_xxx macros. + * + * Note: code that is purely based on the legacy crypto APIs (mbedtls_xxx()) + * does not need to use these macros; instead it should use the relevant + * MBEDTLS_xxx macros. + * + * These macros are for code that wants to use <crypto feature> and will do so + * using <legacy API> or PSA depending on <condition>, where: + * - <crypto feature> will generally be an algorithm (SHA-256, ECDH) but may + * also be a key type (AES, RSA, EC) or domain parameters (elliptic curve); + * - <legacy API> will be either: + * - low-level module API (aes.h, sha256.h), or + * - an abstraction layer (md.h, cipher.h); + * - <condition> will be either: + * - depending on what's available in the build: + * legacy API used if available, PSA otherwise + * (this is done to ensure backwards compatibility); or + * - depending on whether MBEDTLS_USE_PSA_CRYPTO is defined. + * + * Examples: + * - TLS 1.2 will compute hashes using either mbedtls_md_xxx() (and + * mbedtls_sha256_xxx()) or psa_aead_xxx() depending on whether + * MBEDTLS_USE_PSA_CRYPTO is defined; + * - RSA PKCS#1 v2.1 will compute hashes (for padding) using either + * `mbedtls_md()` if it's available, or `psa_hash_compute()` otherwise; + * - PEM decoding of PEM-encrypted keys will compute MD5 hashes using either + * `mbedtls_md5_xxx()` if it's available, or `psa_hash_xxx()` otherwise. + * + * Note: the macros are essential to express test dependencies. Inside code, + * we could instead just use the equivalent pre-processor condition, but + * that's not possible in test dependencies where we need a single macro. + * Hopefully, using these macros in code will also help with consistency. + * + * The naming scheme for these macros is: + * MBEDTLS_HAS_feature_VIA_legacy_OR_PSA(_condition) + * where: + * - feature is expressed the same way as in PSA_WANT macros, for example: + * KEY_TYPE_AES, ALG_SHA_256, ECC_SECP_R1_256; + * - legacy is either LOWLEVEL or the name of the layer: MD, CIPHER; + * - condition is omitted if it's based on availability, else it's + * BASED_ON_USE_PSA. + * + * Coming back to the examples above: + * - TLS 1.2 will determine if it can use SHA-256 using + * MBEDTLS_HAS_ALG_SHA_256_VIA_MD_OR_PSA_BASED_ON_USE_PSA + * for the purposes of negotiation, and in test dependencies; + * - RSA PKCS#1 v2.1 tests that used SHA-256 will depend on + * MBEDTLS_HAS_ALG_SHA_256_VIA_MD_OR_PSA + * - PEM decoding code and its associated tests will depend on + * MBEDTLS_HAS_ALG_MD5_VIA_LOWLEVEL_OR_PSA + * + * Note: every time it's possible to use, say SHA-256, via the MD API, then + * it's also possible to use it via the low-level API. So, code that wants to + * use SHA-256 via both APIs only needs to depend on the MD macro. Also, it + * just so happens that all the code choosing which API to use based on + * MBEDTLS_USE_PSA_CRYPTO (X.509, TLS 1.2/shared), always uses the abstraction + * layer (sometimes in addition to the low-level API), so we don't need the + * MBEDTLS_HAS_feature_VIA_LOWLEVEL_OR_PSA_BASED_ON_USE_PSA macros. + * (PK, while obeying MBEDTLS_USE_PSA_CRYPTO, doesn't compute hashes itself, + * even less makes use of ciphers.) + * + * Note: the macros MBEDTLS_HAS_feature_VIA_LOWLEVEL_OR_PSA are the minimal + * condition for being able to use <feature> at all. As such, they should be + * used for guarding data about <feature>, such as OIDs or size. For example, + * OID values related to SHA-256 are only useful when SHA-256 can be used at + * least in some way. + */ + +#ifndef MBEDTLS_OR_PSA_HELPERS_H +#define MBEDTLS_OR_PSA_HELPERS_H + +#include "mbedtls/build_info.h" +#if defined(MBEDTLS_PSA_CRYPTO_C) +#include "psa/crypto.h" +#endif /* MBEDTLS_PSA_CRYPTO_C */ + +/* + * Hashes + */ + +/* Hashes using low-level or PSA based on availability */ +#if defined(MBEDTLS_MD5_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_MD5) ) +#define MBEDTLS_HAS_ALG_MD5_VIA_LOWLEVEL_OR_PSA +#endif +#if defined(MBEDTLS_RIPEMD160_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_RIPEMD160) ) +#define MBEDTLS_HAS_ALG_RIPEMD160_VIA_LOWLEVEL_OR_PSA +#endif +#if defined(MBEDTLS_SHA1_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_1) ) +#define MBEDTLS_HAS_ALG_SHA_1_VIA_LOWLEVEL_OR_PSA +#endif +#if defined(MBEDTLS_SHA224_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_224) ) +#define MBEDTLS_HAS_ALG_SHA_224_VIA_LOWLEVEL_OR_PSA +#endif +#if defined(MBEDTLS_SHA256_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_256) ) +#define MBEDTLS_HAS_ALG_SHA_256_VIA_LOWLEVEL_OR_PSA +#endif +#if defined(MBEDTLS_SHA384_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_384) ) +#define MBEDTLS_HAS_ALG_SHA_384_VIA_LOWLEVEL_OR_PSA +#endif +#if defined(MBEDTLS_SHA512_C) || \ + ( defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_512) ) +#define MBEDTLS_HAS_ALG_SHA_512_VIA_LOWLEVEL_OR_PSA +#endif + +/* Hashes using MD or PSA based on availability */ +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_MD5_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_MD5) ) +#define MBEDTLS_HAS_ALG_MD5_VIA_MD_OR_PSA +#endif +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_RIPEMD160_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_RIPEMD160) ) +#define MBEDTLS_HAS_ALG_RIPEMD160_VIA_MD_OR_PSA +#endif +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA1_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_1) ) +#define MBEDTLS_HAS_ALG_SHA_1_VIA_MD_OR_PSA +#endif +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA224_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_224) ) +#define MBEDTLS_HAS_ALG_SHA_224_VIA_MD_OR_PSA +#endif +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA256_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_256) ) +#define MBEDTLS_HAS_ALG_SHA_256_VIA_MD_OR_PSA +#endif +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA384_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_384) ) +#define MBEDTLS_HAS_ALG_SHA_384_VIA_MD_OR_PSA +#endif +#if ( defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA512_C) ) || \ + ( !defined(MBEDTLS_MD_C) && \ + defined(MBEDTLS_PSA_CRYPTO_C) && defined(PSA_WANT_ALG_SHA_512) ) +#define MBEDTLS_HAS_ALG_SHA_512_VIA_MD_OR_PSA +#endif + +/* Hashes using MD or PSA based on MBEDTLS_USE_PSA_CRYPTO */ +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_MD5_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_MD5) ) +#define MBEDTLS_HAS_ALG_MD5_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_RIPEMD160_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_RIPEMD160) ) +#define MBEDTLS_HAS_ALG_RIPEMD160_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA1_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_SHA_1) ) +#define MBEDTLS_HAS_ALG_SHA_1_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA224_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_SHA_224) ) +#define MBEDTLS_HAS_ALG_SHA_224_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA256_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_SHA_256) ) +#define MBEDTLS_HAS_ALG_SHA_256_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA384_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_SHA_384) ) +#define MBEDTLS_HAS_ALG_SHA_384_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif +#if ( !defined(MBEDTLS_USE_PSA_CRYPTO) && \ + defined(MBEDTLS_MD_C) && defined(MBEDTLS_SHA512_C) ) || \ + ( defined(MBEDTLS_USE_PSA_CRYPTO) && defined(PSA_WANT_ALG_SHA_512) ) +#define MBEDTLS_HAS_ALG_SHA_512_VIA_MD_OR_PSA_BASED_ON_USE_PSA +#endif + +#endif /* MBEDTLS_OR_PSA_HELPERS_H */ |