Gilles Peskine | 66e7b90 | 2021-02-12 23:40:58 +0100 | [diff] [blame] | 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 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 29 | /** \def KNOWN_SUPPORTED_HASH_ALG |
| 30 | * |
| 31 | * A hash algorithm that is known to be supported. |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 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 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 59 | /** \def KNOWN_SUPPORTED_BLOCK_CIPHER |
| 60 | * |
| 61 | * A block cipher that is known to be supported. |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 62 | * |
| 63 | * For simplicity's sake, stick to block ciphers with 16-byte blocks. |
| 64 | */ |
| 65 | #if defined(MBEDTLS_AES_C) |
| 66 | #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_AES |
| 67 | #elif defined(MBEDTLS_ARIA_C) |
| 68 | #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_ARIA |
| 69 | #elif defined(MBEDTLS_CAMELLIA_C) |
| 70 | #define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_CAMELLIA |
| 71 | #undef KNOWN_SUPPORTED_BLOCK_CIPHER |
| 72 | #endif |
| 73 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 74 | /** \def KNOWN_SUPPORTED_MAC_ALG |
| 75 | * |
| 76 | * A MAC mode that is known to be supported. |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 77 | * |
| 78 | * It must either be HMAC with #KNOWN_SUPPORTED_HASH_ALG or |
| 79 | * a block cipher-based MAC with #KNOWN_SUPPORTED_BLOCK_CIPHER. |
| 80 | * |
| 81 | * This is used in some smoke tests. |
| 82 | */ |
| 83 | #if defined(KNOWN_SUPPORTED_HASH_ALG) && defined(PSA_WANT_ALG_HMAC) |
| 84 | #define KNOWN_SUPPORTED_MAC_ALG ( PSA_ALG_HMAC( KNOWN_SUPPORTED_HASH_ALG ) ) |
| 85 | #define KNOWN_SUPPORTED_MAC_KEY_TYPE PSA_KEY_TYPE_HMAC |
| 86 | #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CMAC_C) |
| 87 | #define KNOWN_SUPPORTED_MAC_ALG PSA_ALG_CMAC |
| 88 | #define KNOWN_SUPPORTED_MAC_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER |
| 89 | #else |
| 90 | #undef KNOWN_SUPPORTED_MAC_ALG |
| 91 | #undef KNOWN_SUPPORTED_MAC_KEY_TYPE |
| 92 | #endif |
| 93 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 94 | /** \def KNOWN_SUPPORTED_BLOCK_CIPHER_ALG |
| 95 | * |
| 96 | * A cipher algorithm and key type that are known to be supported. |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 97 | * |
| 98 | * This is used in some smoke tests. |
| 99 | */ |
| 100 | #if defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CTR) |
| 101 | #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CTR |
| 102 | #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CBC) |
| 103 | #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CBC_NO_PADDING |
| 104 | #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CFB) |
| 105 | #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CFB |
| 106 | #elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_OFB) |
| 107 | #define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_OFB |
| 108 | #else |
| 109 | #undef KNOWN_SUPPORTED_BLOCK_CIPHER_ALG |
| 110 | #endif |
| 111 | #if defined(KNOWN_SUPPORTED_BLOCK_CIPHER_ALG) |
| 112 | #define KNOWN_SUPPORTED_CIPHER_ALG KNOWN_SUPPORTED_BLOCK_CIPHER_ALG |
| 113 | #define KNOWN_SUPPORTED_CIPHER_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER |
| 114 | #elif defined(MBEDTLS_RC4_C) |
| 115 | #define KNOWN_SUPPORTED_CIPHER_ALG PSA_ALG_RC4 |
| 116 | #define KNOWN_SUPPORTED_CIPHER_KEY_TYPE PSA_KEY_TYPE_RC4 |
| 117 | #else |
| 118 | #undef KNOWN_SUPPORTED_CIPHER_ALG |
| 119 | #undef KNOWN_SUPPORTED_CIPHER_KEY_TYPE |
| 120 | #endif |
| 121 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 122 | /** Convenience function to set up a key derivation. |
| 123 | * |
| 124 | * In case of failure, mark the current test case as failed. |
| 125 | * |
| 126 | * The inputs \p input1 and \p input2 are, in order: |
| 127 | * - HKDF: salt, info. |
| 128 | * - TKS 1.2 PRF, TLS 1.2 PSK-to-MS: seed, label. |
| 129 | * |
| 130 | * \param operation The operation object to use. |
| 131 | * It must be in the initialized state. |
| 132 | * \param key The key to use. |
| 133 | * \param alg The algorithm to use. |
| 134 | * \param input1 The first input to pass. |
| 135 | * \param input1_length The length of \p input1 in bytes. |
Gilles Peskine | 5a7702e | 2021-02-23 13:40:19 +0100 | [diff] [blame] | 136 | * \param input2 The first input to pass. |
| 137 | * \param input2_length The length of \p input2 in bytes. |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 138 | * \param capacity The capacity to set. |
| 139 | * |
| 140 | * \return \c 1 on success, \c 0 on failure. |
| 141 | */ |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 142 | int mbedtls_test_psa_setup_key_derivation_wrap( |
| 143 | psa_key_derivation_operation_t* operation, |
| 144 | mbedtls_svc_key_id_t key, |
| 145 | psa_algorithm_t alg, |
Gilles Peskine | 5c2665b | 2021-02-14 01:22:56 +0100 | [diff] [blame] | 146 | const unsigned char* input1, size_t input1_length, |
| 147 | const unsigned char* input2, size_t input2_length, |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 148 | size_t capacity ); |
| 149 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 150 | /** Perform a key agreement using the given key pair against its public key |
| 151 | * using psa_raw_key_agreement(). |
| 152 | * |
| 153 | * The result is discarded. The purpose of this function is to smoke-test a key. |
| 154 | * |
| 155 | * In case of failure, mark the current test case as failed. |
| 156 | * |
| 157 | * \param alg A key agreement algorithm compatible with \p key. |
| 158 | * \param key A key that allows key agreement with \p alg. |
| 159 | * |
| 160 | * \return \c 1 on success, \c 0 on failure. |
| 161 | */ |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 162 | psa_status_t mbedtls_test_psa_raw_key_agreement_with_self( |
| 163 | psa_algorithm_t alg, |
| 164 | mbedtls_svc_key_id_t key ); |
| 165 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 166 | /** Perform a key agreement using the given key pair against its public key |
| 167 | * using psa_key_derivation_raw_key(). |
| 168 | * |
| 169 | * The result is discarded. The purpose of this function is to smoke-test a key. |
| 170 | * |
| 171 | * In case of failure, mark the current test case as failed. |
| 172 | * |
Gilles Peskine | 5a7702e | 2021-02-23 13:40:19 +0100 | [diff] [blame] | 173 | * \param operation An operation that has been set up for a key |
| 174 | * agreement algorithm that is compatible with |
| 175 | * \p key. |
| 176 | * \param key A key pair object that is suitable for a key |
| 177 | * agreement with \p operation. |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 178 | * |
| 179 | * \return \c 1 on success, \c 0 on failure. |
| 180 | */ |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 181 | psa_status_t mbedtls_test_psa_key_agreement_with_self( |
| 182 | psa_key_derivation_operation_t *operation, |
| 183 | mbedtls_svc_key_id_t key ); |
| 184 | |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 185 | /** Perform sanity checks on the given key representation. |
| 186 | * |
| 187 | * If any of the checks fail, mark the current test case as failed. |
| 188 | * |
| 189 | * The checks depend on the key type. |
| 190 | * - All types: check the export size against maximum-size macros. |
| 191 | * - DES: parity bits. |
| 192 | * - RSA: check the ASN.1 structure and the size and parity of the integers. |
| 193 | * - ECC private or public key: exact representation length. |
| 194 | * - Montgomery public key: first byte. |
| 195 | * |
| 196 | * \param type The key type. |
Gilles Peskine | 5a7702e | 2021-02-23 13:40:19 +0100 | [diff] [blame] | 197 | * \param bits The key size in bits. |
| 198 | * \param exported A buffer containing the key representation. |
| 199 | * \param exported_length The length of \p exported in bytes. |
Gilles Peskine | e50b578 | 2021-02-14 01:13:55 +0100 | [diff] [blame] | 200 | * |
| 201 | * \return \c 1 if all checks passed, \c 0 on failure. |
| 202 | */ |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 203 | int mbedtls_test_psa_exported_key_sanity_check( |
| 204 | psa_key_type_t type, size_t bits, |
Gilles Peskine | 5c2665b | 2021-02-14 01:22:56 +0100 | [diff] [blame] | 205 | const uint8_t *exported, size_t exported_length ); |
Gilles Peskine | e78b002 | 2021-02-13 00:41:11 +0100 | [diff] [blame] | 206 | |
| 207 | /** Do smoke tests on a key. |
| 208 | * |
| 209 | * Perform one of each operation indicated by \p alg (decrypt/encrypt, |
| 210 | * sign/verify, or derivation) that is permitted according to \p usage. |
| 211 | * \p usage and \p alg should correspond to the expected policy on the |
| 212 | * key. |
| 213 | * |
| 214 | * Export the key if permitted by \p usage, and check that the output |
| 215 | * looks sensible. If \p usage forbids export, check that |
| 216 | * \p psa_export_key correctly rejects the attempt. If the key is |
| 217 | * asymmetric, also check \p psa_export_public_key. |
| 218 | * |
| 219 | * If the key fails the tests, this function calls the test framework's |
| 220 | * `mbedtls_test_fail` function and returns false. Otherwise this function |
| 221 | * returns true. Therefore it should be used as follows: |
| 222 | * ``` |
| 223 | * if( ! exercise_key( ... ) ) goto exit; |
| 224 | * ``` |
| 225 | * |
| 226 | * \param key The key to exercise. It should be capable of performing |
| 227 | * \p alg. |
| 228 | * \param usage The usage flags to assume. |
| 229 | * \param alg The algorithm to exercise. |
| 230 | * |
| 231 | * \retval 0 The key failed the smoke tests. |
| 232 | * \retval 1 The key passed the smoke tests. |
| 233 | */ |
| 234 | int mbedtls_test_psa_exercise_key( mbedtls_svc_key_id_t key, |
| 235 | psa_key_usage_t usage, |
| 236 | psa_algorithm_t alg ); |
| 237 | |
| 238 | psa_key_usage_t mbedtls_test_psa_usage_to_exercise( psa_key_type_t type, |
| 239 | psa_algorithm_t alg ); |
Gilles Peskine | 66e7b90 | 2021-02-12 23:40:58 +0100 | [diff] [blame] | 240 | |
| 241 | #endif /* PSA_EXERCISE_KEY_H */ |