1 /* 2 * Helper functions for tests that use the PSA Crypto API. 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_CRYPTO_HELPERS_H 22 #define PSA_CRYPTO_HELPERS_H 23 24 #include "test/helpers.h" 25 26 #if defined(MBEDTLS_PSA_CRYPTO_C) 27 #include "test/psa_helpers.h" 28 #include <psa/crypto.h> 29 #endif 30 31 #if defined(MBEDTLS_USE_PSA_CRYPTO) 32 #include "mbedtls/psa_util.h" 33 #endif 34 35 #if defined(MBEDTLS_PSA_CRYPTO_C) 36 /** Initialize the PSA Crypto subsystem. */ 37 #define PSA_INIT() PSA_ASSERT(psa_crypto_init()) 38 39 /** Shut down the PSA Crypto subsystem and destroy persistent keys. 40 * Expect a clean shutdown, with no slots in use. 41 * 42 * If some key slots are still in use, record the test case as failed, 43 * but continue executing. This macro is suitable (and primarily intended) 44 * for use in the cleanup section of test functions. 45 * 46 * \note Persistent keys must be recorded with #TEST_USES_KEY_ID before 47 * creating them. 48 */ 49 #define PSA_DONE() \ 50 do \ 51 { \ 52 mbedtls_test_fail_if_psa_leaking(__LINE__, __FILE__); \ 53 mbedtls_test_psa_purge_key_storage(); \ 54 mbedtls_psa_crypto_free(); \ 55 } \ 56 while (0) 57 #else /*MBEDTLS_PSA_CRYPTO_C */ 58 #define PSA_INIT() ((void) 0) 59 #define PSA_DONE() ((void) 0) 60 #endif /* MBEDTLS_PSA_CRYPTO_C */ 61 62 #if defined(MBEDTLS_PSA_CRYPTO_C) 63 64 #if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C) 65 66 /* Internal function for #TEST_USES_KEY_ID. Return 1 on success, 0 on failure. */ 67 int mbedtls_test_uses_key_id(mbedtls_svc_key_id_t key_id); 68 69 /** Destroy persistent keys recorded with #TEST_USES_KEY_ID. 70 */ 71 void mbedtls_test_psa_purge_key_storage(void); 72 73 /** Purge the in-memory cache of persistent keys recorded with 74 * #TEST_USES_KEY_ID. 75 * 76 * Call this function before calling PSA_DONE() if it's ok for 77 * persistent keys to still exist at this point. 78 */ 79 void mbedtls_test_psa_purge_key_cache(void); 80 81 /** \def TEST_USES_KEY_ID 82 * 83 * Call this macro in a test function before potentially creating a 84 * persistent key. Test functions that use this mechanism must call 85 * mbedtls_test_psa_purge_key_storage() in their cleanup code. 86 * 87 * This macro records a persistent key identifier as potentially used in the 88 * current test case. Recorded key identifiers will be cleaned up at the end 89 * of the test case, even on failure. 90 * 91 * This macro has no effect on volatile keys. Therefore, it is safe to call 92 * this macro in a test function that creates either volatile or persistent 93 * keys depending on the test data. 94 * 95 * This macro currently has no effect on special identifiers 96 * used to store implementation-specific files. 97 * 98 * Calling this macro multiple times on the same key identifier in the same 99 * test case has no effect. 100 * 101 * This macro can fail the test case if there isn't enough memory to 102 * record the key id. 103 * 104 * \param key_id The PSA key identifier to record. 105 */ 106 #define TEST_USES_KEY_ID(key_id) \ 107 TEST_ASSERT(mbedtls_test_uses_key_id(key_id)) 108 109 #else /* MBEDTLS_PSA_CRYPTO_STORAGE_C */ 110 111 #define TEST_USES_KEY_ID(key_id) ((void) (key_id)) 112 #define mbedtls_test_psa_purge_key_storage() ((void) 0) 113 #define mbedtls_test_psa_purge_key_cache() ((void) 0) 114 115 #endif /* MBEDTLS_PSA_CRYPTO_STORAGE_C */ 116 117 /** Check for things that have not been cleaned up properly in the 118 * PSA subsystem. 119 * 120 * \return NULL if nothing has leaked. 121 * \return A string literal explaining what has not been cleaned up 122 * if applicable. 123 */ 124 const char *mbedtls_test_helper_is_psa_leaking(void); 125 126 /** Check that no PSA Crypto key slots are in use. 127 * 128 * If any slots are in use, mark the current test as failed and jump to 129 * the exit label. This is equivalent to 130 * `TEST_ASSERT( ! mbedtls_test_helper_is_psa_leaking( ) )` 131 * but with a more informative message. 132 */ 133 #define ASSERT_PSA_PRISTINE() \ 134 do \ 135 { \ 136 if (mbedtls_test_fail_if_psa_leaking(__LINE__, __FILE__)) \ 137 goto exit; \ 138 } \ 139 while (0) 140 141 /** Shut down the PSA Crypto subsystem, allowing persistent keys to survive. 142 * Expect a clean shutdown, with no slots in use. 143 * 144 * If some key slots are still in use, record the test case as failed and 145 * jump to the `exit` label. 146 */ 147 #define PSA_SESSION_DONE() \ 148 do \ 149 { \ 150 mbedtls_test_psa_purge_key_cache(); \ 151 ASSERT_PSA_PRISTINE(); \ 152 mbedtls_psa_crypto_free(); \ 153 } \ 154 while (0) 155 156 157 158 #if defined(RECORD_PSA_STATUS_COVERAGE_LOG) 159 psa_status_t mbedtls_test_record_status(psa_status_t status, 160 const char *func, 161 const char *file, int line, 162 const char *expr); 163 164 /** Return value logging wrapper macro. 165 * 166 * Evaluate \p expr. Write a line recording its value to the log file 167 * #STATUS_LOG_FILE_NAME and return the value. The line is a colon-separated 168 * list of fields: 169 * ``` 170 * value of expr:string:__FILE__:__LINE__:expr 171 * ``` 172 * 173 * The test code does not call this macro explicitly because that would 174 * be very invasive. Instead, we instrument the source code by defining 175 * a bunch of wrapper macros like 176 * ``` 177 * #define psa_crypto_init() RECORD_STATUS("psa_crypto_init", psa_crypto_init()) 178 * ``` 179 * These macro definitions must be present in `instrument_record_status.h` 180 * when building the test suites. 181 * 182 * \param string A string, normally a function name. 183 * \param expr An expression to evaluate, normally a call of the function 184 * whose name is in \p string. This expression must return 185 * a value of type #psa_status_t. 186 * \return The value of \p expr. 187 */ 188 #define RECORD_STATUS(string, expr) \ 189 mbedtls_test_record_status((expr), string, __FILE__, __LINE__, #expr) 190 191 #include "instrument_record_status.h" 192 193 #endif /* defined(RECORD_PSA_STATUS_COVERAGE_LOG) */ 194 195 /** Return extended key usage policies. 196 * 197 * Do a key policy permission extension on key usage policies always involves 198 * permissions of other usage policies 199 * (like PSA_KEY_USAGE_SIGN_HASH involves PSA_KEY_USAGE_SIGN_MESSAGE). 200 */ 201 psa_key_usage_t mbedtls_test_update_key_usage_flags(psa_key_usage_t usage_flags); 202 203 /** Check that no PSA Crypto key slots are in use. 204 * 205 * If any slots are in use, mark the current test as failed. 206 * 207 * \return 0 if the key store is empty, 1 otherwise. 208 */ 209 int mbedtls_test_fail_if_psa_leaking(int line_no, const char *filename); 210 211 /** Skip a test case if the given key is a 192 bits AES key and the AES 212 * implementation is at least partially provided by an accelerator or 213 * alternative implementation. 214 * 215 * Call this macro in a test case when a cryptographic operation that may 216 * involve an AES operation returns a #PSA_ERROR_NOT_SUPPORTED error code. 217 * The macro call will skip and not fail the test case in case the operation 218 * involves a 192 bits AES key and the AES implementation is at least 219 * partially provided by an accelerator or alternative implementation. 220 * 221 * Hardware AES implementations not supporting 192 bits keys commonly exist. 222 * Consequently, PSA test cases aim at not failing when an AES operation with 223 * a 192 bits key performed by an alternative AES implementation returns 224 * with the #PSA_ERROR_NOT_SUPPORTED error code. The purpose of this macro 225 * is to facilitate this and make the test case code more readable. 226 * 227 * \param key_type Key type 228 * \param key_bits Key length in number of bits. 229 */ 230 #if defined(MBEDTLS_AES_ALT) || \ 231 defined(MBEDTLS_AES_SETKEY_ENC_ALT) || \ 232 defined(MBEDTLS_PSA_ACCEL_KEY_TYPE_AES) 233 #define MBEDTLS_TEST_HAVE_ALT_AES 1 234 #else 235 #define MBEDTLS_TEST_HAVE_ALT_AES 0 236 #endif 237 238 #define MBEDTLS_TEST_PSA_SKIP_IF_ALT_AES_192(key_type, key_bits) \ 239 do \ 240 { \ 241 if ((MBEDTLS_TEST_HAVE_ALT_AES) && \ 242 ((key_type) == PSA_KEY_TYPE_AES) && \ 243 (key_bits == 192)) \ 244 { \ 245 mbedtls_test_skip("AES-192 not supported", __LINE__, __FILE__); \ 246 goto exit; \ 247 } \ 248 } \ 249 while (0) 250 251 /** Skip a test case if a GCM operation with a nonce length different from 252 * 12 bytes fails and was performed by an accelerator or alternative 253 * implementation. 254 * 255 * Call this macro in a test case when an AEAD cryptography operation that 256 * may involve the GCM mode returns with a #PSA_ERROR_NOT_SUPPORTED error 257 * code. The macro call will skip and not fail the test case in case the 258 * operation involves the GCM mode, a nonce with a length different from 259 * 12 bytes and the GCM mode implementation is an alternative one. 260 * 261 * Hardware GCM implementations not supporting nonce lengths different from 262 * 12 bytes commonly exist, as supporting a non-12-byte nonce requires 263 * additional computations involving the GHASH function. 264 * Consequently, PSA test cases aim at not failing when an AEAD operation in 265 * GCM mode with a nonce length different from 12 bytes is performed by an 266 * alternative GCM implementation and returns with a #PSA_ERROR_NOT_SUPPORTED 267 * error code. The purpose of this macro is to facilitate this check and make 268 * the test case code more readable. 269 * 270 * \param alg The AEAD algorithm. 271 * \param nonce_length The nonce length in number of bytes. 272 */ 273 #if defined(MBEDTLS_GCM_ALT) || \ 274 defined(MBEDTLS_PSA_ACCEL_ALG_GCM) 275 #define MBEDTLS_TEST_HAVE_ALT_GCM 1 276 #else 277 #define MBEDTLS_TEST_HAVE_ALT_GCM 0 278 #endif 279 280 #define MBEDTLS_TEST_PSA_SKIP_IF_ALT_GCM_NOT_12BYTES_NONCE(alg, \ 281 nonce_length) \ 282 do \ 283 { \ 284 if ((MBEDTLS_TEST_HAVE_ALT_GCM) && \ 285 (PSA_ALG_AEAD_WITH_SHORTENED_TAG((alg), 0) == \ 286 PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, 0)) && \ 287 ((nonce_length) != 12)) \ 288 { \ 289 mbedtls_test_skip("GCM with non-12-byte IV is not supported", __LINE__, __FILE__); \ 290 goto exit; \ 291 } \ 292 } \ 293 while (0) 294 295 #if !defined(MBEDTLS_MD_C) 296 #define PSA_INIT_IF_NO_MD() PSA_INIT() 297 #define PSA_DONE_IF_NO_MD() PSA_DONE() 298 #endif 299 #endif /* MBEDTLS_PSA_CRYPTO_C */ 300 301 #if defined(MBEDTLS_MD_C) 302 #define PSA_INIT_IF_NO_MD() ((void) 0) 303 #define PSA_DONE_IF_NO_MD() ((void) 0) 304 #endif 305 306 /** \def USE_PSA_INIT 307 * 308 * Call this macro to initialize the PSA subsystem if #MBEDTLS_USE_PSA_CRYPTO 309 * or #MBEDTLS_SSL_PROTO_TLS1_3 (In contrast to TLS 1.2 implementation, the 310 * TLS 1.3 one uses PSA independently of the definition of 311 * #MBEDTLS_USE_PSA_CRYPTO) is enabled and do nothing otherwise. If the 312 * initialization fails, mark the test case as failed and jump to the \p exit 313 * label. 314 */ 315 /** \def USE_PSA_DONE 316 * 317 * Call this macro at the end of a test case if you called #USE_PSA_INIT. 318 * This is like #PSA_DONE, except that it does nothing if 319 * #MBEDTLS_USE_PSA_CRYPTO is disabled. 320 */ 321 #if defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3) 322 #define USE_PSA_INIT() PSA_INIT() 323 #define USE_PSA_DONE() PSA_DONE() 324 #else /* MBEDTLS_USE_PSA_CRYPTO || MBEDTLS_SSL_PROTO_TLS1_3 */ 325 /* Define empty macros so that we can use them in the preamble and teardown 326 * of every test function that uses PSA conditionally based on 327 * MBEDTLS_USE_PSA_CRYPTO. */ 328 #define USE_PSA_INIT() ((void) 0) 329 #define USE_PSA_DONE() ((void) 0) 330 #endif /* !MBEDTLS_USE_PSA_CRYPTO && !MBEDTLS_SSL_PROTO_TLS1_3 */ 331 332 #endif /* PSA_CRYPTO_HELPERS_H */ 333