1 /** Code to exercise a PSA key object, i.e. validate that it seems well-formed 2 * and can do what it is supposed to do. 3 */ 4 /* 5 * Copyright The Mbed TLS Contributors 6 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 7 */ 8 9 #ifndef PSA_EXERCISE_KEY_H 10 #define PSA_EXERCISE_KEY_H 11 12 #include "test/helpers.h" 13 #include "test/psa_crypto_helpers.h" 14 15 #include <psa/crypto.h> 16 17 /** \def KNOWN_SUPPORTED_HASH_ALG 18 * 19 * A hash algorithm that is known to be supported. 20 * 21 * This is used in some smoke tests. 22 */ 23 #if defined(PSA_WANT_ALG_MD5) 24 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD5 25 /* PSA_WANT_ALG_RIPEMD160 omitted. This is necessary for the sake of 26 * exercise_signature_key() because Mbed TLS doesn't support RIPEMD160 27 * in RSA PKCS#1v1.5 signatures. A RIPEMD160-only configuration would be 28 * implausible anyway. */ 29 #elif defined(PSA_WANT_ALG_SHA_1) 30 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_1 31 #elif defined(PSA_WANT_ALG_SHA_256) 32 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_256 33 #elif defined(PSA_WANT_ALG_SHA_384) 34 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_384 35 #elif defined(PSA_WANT_ALG_SHA_512) 36 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_512 37 #elif defined(PSA_WANT_ALG_SHA3_256) 38 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA3_256 39 #else 40 #undef KNOWN_SUPPORTED_HASH_ALG 41 #endif 42 43 /** \def KNOWN_SUPPORTED_BLOCK_CIPHER 44 * 45 * A block cipher that is known to be supported. 46 * 47 * For simplicity's sake, stick to block ciphers with 16-byte blocks. 48 */ 49 #if defined(MBEDTLS_AES_C) 50 #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_AES 51 #elif defined(MBEDTLS_ARIA_C) 52 #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_ARIA 53 #elif defined(MBEDTLS_CAMELLIA_C) 54 #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_CAMELLIA 55 #undef KNOWN_SUPPORTED_BLOCK_CIPHER 56 #endif 57 58 /** \def KNOWN_SUPPORTED_MAC_ALG 59 * 60 * A MAC mode that is known to be supported. 61 * 62 * It must either be HMAC with #KNOWN_SUPPORTED_HASH_ALG or 63 * a block cipher-based MAC with #KNOWN_SUPPORTED_BLOCK_CIPHER. 64 * 65 * This is used in some smoke tests. 66 */ 67 #if defined(KNOWN_SUPPORTED_HASH_ALG) && defined(PSA_WANT_ALG_HMAC) 68 #define KNOWN_SUPPORTED_MAC_ALG (PSA_ALG_HMAC(KNOWN_SUPPORTED_HASH_ALG)) 69 #define KNOWN_SUPPORTED_MAC_KEY_TYPE PSA_KEY_TYPE_HMAC 70 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CMAC_C) 71 #define KNOWN_SUPPORTED_MAC_ALG PSA_ALG_CMAC 72 #define KNOWN_SUPPORTED_MAC_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER 73 #else 74 #undef KNOWN_SUPPORTED_MAC_ALG 75 #undef KNOWN_SUPPORTED_MAC_KEY_TYPE 76 #endif 77 78 /** \def KNOWN_SUPPORTED_BLOCK_CIPHER_ALG 79 * 80 * A cipher algorithm and key type that are known to be supported. 81 * 82 * This is used in some smoke tests. 83 */ 84 #if defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CTR) 85 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CTR 86 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CBC) 87 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CBC_NO_PADDING 88 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CFB) 89 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CFB 90 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_OFB) 91 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_OFB 92 #else 93 #undef KNOWN_SUPPORTED_BLOCK_CIPHER_ALG 94 #endif 95 #if defined(KNOWN_SUPPORTED_BLOCK_CIPHER_ALG) 96 #define KNOWN_SUPPORTED_CIPHER_ALG KNOWN_SUPPORTED_BLOCK_CIPHER_ALG 97 #define KNOWN_SUPPORTED_CIPHER_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER 98 #else 99 #undef KNOWN_SUPPORTED_CIPHER_ALG 100 #undef KNOWN_SUPPORTED_CIPHER_KEY_TYPE 101 #endif 102 103 /** Convenience function to set up a key derivation. 104 * 105 * In case of failure, mark the current test case as failed. 106 * 107 * The inputs \p input1 and \p input2 are, in order: 108 * - HKDF: salt, info. 109 * - TKS 1.2 PRF, TLS 1.2 PSK-to-MS: seed, label. 110 * - PBKDF2: input cost, salt. 111 * 112 * \param operation The operation object to use. 113 * It must be in the initialized state. 114 * \param key The key to use. 115 * \param alg The algorithm to use. 116 * \param input1 The first input to pass. 117 * \param input1_length The length of \p input1 in bytes. 118 * \param input2 The first input to pass. 119 * \param input2_length The length of \p input2 in bytes. 120 * \param capacity The capacity to set. 121 * 122 * \return \c 1 on success, \c 0 on failure. 123 */ 124 int mbedtls_test_psa_setup_key_derivation_wrap( 125 psa_key_derivation_operation_t *operation, 126 mbedtls_svc_key_id_t key, 127 psa_algorithm_t alg, 128 const unsigned char *input1, size_t input1_length, 129 const unsigned char *input2, size_t input2_length, 130 size_t capacity); 131 132 /** Perform a key agreement using the given key pair against its public key 133 * using psa_raw_key_agreement(). 134 * 135 * The result is discarded. The purpose of this function is to smoke-test a key. 136 * 137 * In case of failure, mark the current test case as failed. 138 * 139 * \param alg A key agreement algorithm compatible with \p key. 140 * \param key A key that allows key agreement with \p alg. 141 * 142 * \return \c 1 on success, \c 0 on failure. 143 */ 144 psa_status_t mbedtls_test_psa_raw_key_agreement_with_self( 145 psa_algorithm_t alg, 146 mbedtls_svc_key_id_t key); 147 148 /** Perform a key agreement using the given key pair against its public key 149 * using psa_key_derivation_raw_key(). 150 * 151 * The result is discarded. The purpose of this function is to smoke-test a key. 152 * 153 * In case of failure, mark the current test case as failed. 154 * 155 * \param operation An operation that has been set up for a key 156 * agreement algorithm that is compatible with 157 * \p key. 158 * \param key A key pair object that is suitable for a key 159 * agreement with \p operation. 160 * 161 * \return \c 1 on success, \c 0 on failure. 162 */ 163 psa_status_t mbedtls_test_psa_key_agreement_with_self( 164 psa_key_derivation_operation_t *operation, 165 mbedtls_svc_key_id_t key); 166 167 /** Perform sanity checks on the given key representation. 168 * 169 * If any of the checks fail, mark the current test case as failed. 170 * 171 * The checks depend on the key type. 172 * - All types: check the export size against maximum-size macros. 173 * - DES: parity bits. 174 * - RSA: check the ASN.1 structure and the size and parity of the integers. 175 * - ECC private or public key: exact representation length. 176 * - Montgomery public key: first byte. 177 * 178 * \param type The key type. 179 * \param bits The key size in bits. 180 * \param exported A buffer containing the key representation. 181 * \param exported_length The length of \p exported in bytes. 182 * 183 * \return \c 1 if all checks passed, \c 0 on failure. 184 */ 185 int mbedtls_test_psa_exported_key_sanity_check( 186 psa_key_type_t type, size_t bits, 187 const uint8_t *exported, size_t exported_length); 188 189 /** Do smoke tests on a key. 190 * 191 * Perform one of each operation indicated by \p alg (decrypt/encrypt, 192 * sign/verify, or derivation) that is permitted according to \p usage. 193 * \p usage and \p alg should correspond to the expected policy on the 194 * key. 195 * 196 * Export the key if permitted by \p usage, and check that the output 197 * looks sensible. If \p usage forbids export, check that 198 * \p psa_export_key correctly rejects the attempt. If the key is 199 * asymmetric, also check \p psa_export_public_key. 200 * 201 * If the key fails the tests, this function calls the test framework's 202 * `mbedtls_test_fail` function and returns false. Otherwise this function 203 * returns true. Therefore it should be used as follows: 204 * ``` 205 * if( ! exercise_key( ... ) ) goto exit; 206 * ``` 207 * 208 * \param key The key to exercise. It should be capable of performing 209 * \p alg. 210 * \param usage The usage flags to assume. 211 * \param alg The algorithm to exercise. 212 * 213 * \retval 0 The key failed the smoke tests. 214 * \retval 1 The key passed the smoke tests. 215 */ 216 int mbedtls_test_psa_exercise_key(mbedtls_svc_key_id_t key, 217 psa_key_usage_t usage, 218 psa_algorithm_t alg); 219 220 psa_key_usage_t mbedtls_test_psa_usage_to_exercise(psa_key_type_t type, 221 psa_algorithm_t alg); 222 223 #endif /* PSA_EXERCISE_KEY_H */ 224
