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 7 * 8 * Licensed under the Apache License, Version 2.0 (the "License"); you may 9 * not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 16 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 21 #ifndef PSA_EXERCISE_KEY_H 22 #define PSA_EXERCISE_KEY_H 23 24 #include "test/helpers.h" 25 #include "test/psa_crypto_helpers.h" 26 27 #include <psa/crypto.h> 28 29 /** \def KNOWN_SUPPORTED_HASH_ALG 30 * 31 * A hash algorithm that is known to be supported. 32 * 33 * This is used in some smoke tests. 34 */ 35 #if defined(PSA_WANT_ALG_MD2) 36 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD2 37 #elif defined(PSA_WANT_ALG_MD4) 38 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD4 39 #elif defined(PSA_WANT_ALG_MD5) 40 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD5 41 /* MBEDTLS_RIPEMD160_C omitted. This is necessary for the sake of 42 * exercise_signature_key() because Mbed TLS doesn't support RIPEMD160 43 * in RSA PKCS#1v1.5 signatures. A RIPEMD160-only configuration would be 44 * implausible anyway. */ 45 #elif defined(PSA_WANT_ALG_SHA_1) 46 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_1 47 #elif defined(PSA_WANT_ALG_SHA_256) 48 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_256 49 #elif defined(PSA_WANT_ALG_SHA_384) 50 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_384 51 #elif defined(PSA_WANT_ALG_SHA_512) 52 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_512 53 #elif defined(PSA_WANT_ALG_SHA3_256) 54 #define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA3_256 55 #else 56 #undef KNOWN_SUPPORTED_HASH_ALG 57 #endif 58 59 /** \def KNOWN_MBEDTLS_SUPPORTED_HASH_ALG 60 * 61 * A hash algorithm that is known to be supported by Mbed TLS APIs. 62 * 63 * This is used in some smoke tests where the hash algorithm is used as 64 * part of another algorithm like a signature algorithm and the hashing is 65 * completed through an Mbed TLS hash API, not the PSA one. 66 */ 67 #if defined(MBEDTLS_MD2_C) 68 #define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_MD2 69 #elif defined(MBEDTLS_MD4_C) 70 #define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_MD4 71 #elif defined(MBEDTLS_MD5_C) 72 #define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_MD5 73 /* MBEDTLS_RIPEMD160_C omitted. This is necessary for the sake of 74 * exercise_signature_key() because Mbed TLS doesn't support RIPEMD160 75 * in RSA PKCS#1v1.5 signatures. A RIPEMD160-only configuration would be 76 * implausible anyway. */ 77 #elif defined(MBEDTLS_SHA1_C) 78 #define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_SHA_1 79 #elif defined(MBEDTLS_SHA256_C) 80 #define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_SHA_256 81 #elif defined(MBEDTLS_SHA512_C) 82 #define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_SHA_512 83 #else 84 #undef KNOWN_MBEDLTS_SUPPORTED_HASH_ALG 85 #endif 86 87 /** \def KNOWN_SUPPORTED_BLOCK_CIPHER 88 * 89 * A block cipher that is known to be supported. 90 * 91 * For simplicity's sake, stick to block ciphers with 16-byte blocks. 92 */ 93 #if defined(MBEDTLS_AES_C) 94 #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_AES 95 #elif defined(MBEDTLS_ARIA_C) 96 #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_ARIA 97 #elif defined(MBEDTLS_CAMELLIA_C) 98 #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_CAMELLIA 99 #undef KNOWN_SUPPORTED_BLOCK_CIPHER 100 #endif 101 102 /** \def KNOWN_SUPPORTED_MAC_ALG 103 * 104 * A MAC mode that is known to be supported. 105 * 106 * It must either be HMAC with #KNOWN_SUPPORTED_HASH_ALG or 107 * a block cipher-based MAC with #KNOWN_SUPPORTED_BLOCK_CIPHER. 108 * 109 * This is used in some smoke tests. 110 */ 111 #if defined(KNOWN_SUPPORTED_HASH_ALG) && defined(PSA_WANT_ALG_HMAC) 112 #define KNOWN_SUPPORTED_MAC_ALG ( PSA_ALG_HMAC( KNOWN_SUPPORTED_HASH_ALG ) ) 113 #define KNOWN_SUPPORTED_MAC_KEY_TYPE PSA_KEY_TYPE_HMAC 114 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CMAC_C) 115 #define KNOWN_SUPPORTED_MAC_ALG PSA_ALG_CMAC 116 #define KNOWN_SUPPORTED_MAC_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER 117 #else 118 #undef KNOWN_SUPPORTED_MAC_ALG 119 #undef KNOWN_SUPPORTED_MAC_KEY_TYPE 120 #endif 121 122 /** \def KNOWN_SUPPORTED_BLOCK_CIPHER_ALG 123 * 124 * A cipher algorithm and key type that are known to be supported. 125 * 126 * This is used in some smoke tests. 127 */ 128 #if defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CTR) 129 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CTR 130 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CBC) 131 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CBC_NO_PADDING 132 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CFB) 133 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CFB 134 #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_OFB) 135 #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_OFB 136 #else 137 #undef KNOWN_SUPPORTED_BLOCK_CIPHER_ALG 138 #endif 139 #if defined(KNOWN_SUPPORTED_BLOCK_CIPHER_ALG) 140 #define KNOWN_SUPPORTED_CIPHER_ALG KNOWN_SUPPORTED_BLOCK_CIPHER_ALG 141 #define KNOWN_SUPPORTED_CIPHER_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER 142 #elif defined(MBEDTLS_RC4_C) 143 #define KNOWN_SUPPORTED_CIPHER_ALG PSA_ALG_RC4 144 #define KNOWN_SUPPORTED_CIPHER_KEY_TYPE PSA_KEY_TYPE_RC4 145 #else 146 #undef KNOWN_SUPPORTED_CIPHER_ALG 147 #undef KNOWN_SUPPORTED_CIPHER_KEY_TYPE 148 #endif 149 150 /** Convenience function to set up a key derivation. 151 * 152 * In case of failure, mark the current test case as failed. 153 * 154 * The inputs \p input1 and \p input2 are, in order: 155 * - HKDF: salt, info. 156 * - TKS 1.2 PRF, TLS 1.2 PSK-to-MS: seed, label. 157 * 158 * \param operation The operation object to use. 159 * It must be in the initialized state. 160 * \param key The key to use. 161 * \param alg The algorithm to use. 162 * \param input1 The first input to pass. 163 * \param input1_length The length of \p input1 in bytes. 164 * \param input2 The first input to pass. 165 * \param input2_length The length of \p input2 in bytes. 166 * \param capacity The capacity to set. 167 * 168 * \return \c 1 on success, \c 0 on failure. 169 */ 170 int mbedtls_test_psa_setup_key_derivation_wrap( 171 psa_key_derivation_operation_t* operation, 172 mbedtls_svc_key_id_t key, 173 psa_algorithm_t alg, 174 const unsigned char* input1, size_t input1_length, 175 const unsigned char* input2, size_t input2_length, 176 size_t capacity ); 177 178 /** Perform a key agreement using the given key pair against its public key 179 * using psa_raw_key_agreement(). 180 * 181 * The result is discarded. The purpose of this function is to smoke-test a key. 182 * 183 * In case of failure, mark the current test case as failed. 184 * 185 * \param alg A key agreement algorithm compatible with \p key. 186 * \param key A key that allows key agreement with \p alg. 187 * 188 * \return \c 1 on success, \c 0 on failure. 189 */ 190 psa_status_t mbedtls_test_psa_raw_key_agreement_with_self( 191 psa_algorithm_t alg, 192 mbedtls_svc_key_id_t key ); 193 194 /** Perform a key agreement using the given key pair against its public key 195 * using psa_key_derivation_raw_key(). 196 * 197 * The result is discarded. The purpose of this function is to smoke-test a key. 198 * 199 * In case of failure, mark the current test case as failed. 200 * 201 * \param operation An operation that has been set up for a key 202 * agreement algorithm that is compatible with 203 * \p key. 204 * \param key A key pair object that is suitable for a key 205 * agreement with \p operation. 206 * 207 * \return \c 1 on success, \c 0 on failure. 208 */ 209 psa_status_t mbedtls_test_psa_key_agreement_with_self( 210 psa_key_derivation_operation_t *operation, 211 mbedtls_svc_key_id_t key ); 212 213 /** Perform sanity checks on the given key representation. 214 * 215 * If any of the checks fail, mark the current test case as failed. 216 * 217 * The checks depend on the key type. 218 * - All types: check the export size against maximum-size macros. 219 * - DES: parity bits. 220 * - RSA: check the ASN.1 structure and the size and parity of the integers. 221 * - ECC private or public key: exact representation length. 222 * - Montgomery public key: first byte. 223 * 224 * \param type The key type. 225 * \param bits The key size in bits. 226 * \param exported A buffer containing the key representation. 227 * \param exported_length The length of \p exported in bytes. 228 * 229 * \return \c 1 if all checks passed, \c 0 on failure. 230 */ 231 int mbedtls_test_psa_exported_key_sanity_check( 232 psa_key_type_t type, size_t bits, 233 const uint8_t *exported, size_t exported_length ); 234 235 /** Do smoke tests on a key. 236 * 237 * Perform one of each operation indicated by \p alg (decrypt/encrypt, 238 * sign/verify, or derivation) that is permitted according to \p usage. 239 * \p usage and \p alg should correspond to the expected policy on the 240 * key. 241 * 242 * Export the key if permitted by \p usage, and check that the output 243 * looks sensible. If \p usage forbids export, check that 244 * \p psa_export_key correctly rejects the attempt. If the key is 245 * asymmetric, also check \p psa_export_public_key. 246 * 247 * If the key fails the tests, this function calls the test framework's 248 * `mbedtls_test_fail` function and returns false. Otherwise this function 249 * returns true. Therefore it should be used as follows: 250 * ``` 251 * if( ! exercise_key( ... ) ) goto exit; 252 * ``` 253 * 254 * \param key The key to exercise. It should be capable of performing 255 * \p alg. 256 * \param usage The usage flags to assume. 257 * \param alg The algorithm to exercise. 258 * 259 * \retval 0 The key failed the smoke tests. 260 * \retval 1 The key passed the smoke tests. 261 */ 262 int mbedtls_test_psa_exercise_key( mbedtls_svc_key_id_t key, 263 psa_key_usage_t usage, 264 psa_algorithm_t alg ); 265 266 psa_key_usage_t mbedtls_test_psa_usage_to_exercise( psa_key_type_t type, 267 psa_algorithm_t alg ); 268 269 #endif /* PSA_EXERCISE_KEY_H */ 270
