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