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 OR GPL-2.0-or-later
7 */
8
9#ifndef PSA_CRYPTO_HELPERS_H
10#define PSA_CRYPTO_HELPERS_H
11
12#include "test/helpers.h"
13
14#if defined(MBEDTLS_PSA_CRYPTO_C)
15#include "test/psa_helpers.h"
16#include <psa/crypto.h>
17#endif
18
19#if defined(MBEDTLS_PSA_CRYPTO_C)
20/** Initialize the PSA Crypto subsystem. */
21#define PSA_INIT() PSA_ASSERT(psa_crypto_init())
22
23/** Shut down the PSA Crypto subsystem and destroy persistent keys.
24 * Expect a clean shutdown, with no slots in use.
25 *
26 * If some key slots are still in use, record the test case as failed,
27 * but continue executing. This macro is suitable (and primarily intended)
28 * for use in the cleanup section of test functions.
29 *
30 * \note Persistent keys must be recorded with #TEST_USES_KEY_ID before
31 *       creating them.
32 */
33#define PSA_DONE()                                                      \
34    do                                                                  \
35    {                                                                   \
36        mbedtls_test_fail_if_psa_leaking(__LINE__, __FILE__);           \
37        mbedtls_test_psa_purge_key_storage();                           \
38        mbedtls_psa_crypto_free();                                      \
39    }                                                                   \
40    while (0)
41#else /*MBEDTLS_PSA_CRYPTO_C */
42#define PSA_INIT() ((void) 0)
43#define PSA_DONE() ((void) 0)
44#endif /* MBEDTLS_PSA_CRYPTO_C */
45
46#if defined(MBEDTLS_PSA_CRYPTO_C)
47
48#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C)
49
50/* Internal function for #TEST_USES_KEY_ID. Return 1 on success, 0 on failure. */
51int mbedtls_test_uses_key_id(mbedtls_svc_key_id_t key_id);
52
53/** Destroy persistent keys recorded with #TEST_USES_KEY_ID.
54 */
55void mbedtls_test_psa_purge_key_storage(void);
56
57/** Purge the in-memory cache of persistent keys recorded with
58 * #TEST_USES_KEY_ID.
59 *
60 * Call this function before calling PSA_DONE() if it's ok for
61 * persistent keys to still exist at this point.
62 */
63void mbedtls_test_psa_purge_key_cache(void);
64
65/** \def TEST_USES_KEY_ID
66 *
67 * Call this macro in a test function before potentially creating a
68 * persistent key. Test functions that use this mechanism must call
69 * mbedtls_test_psa_purge_key_storage() in their cleanup code.
70 *
71 * This macro records a persistent key identifier as potentially used in the
72 * current test case. Recorded key identifiers will be cleaned up at the end
73 * of the test case, even on failure.
74 *
75 * This macro has no effect on volatile keys. Therefore, it is safe to call
76 * this macro in a test function that creates either volatile or persistent
77 * keys depending on the test data.
78 *
79 * This macro currently has no effect on special identifiers
80 * used to store implementation-specific files.
81 *
82 * Calling this macro multiple times on the same key identifier in the same
83 * test case has no effect.
84 *
85 * This macro can fail the test case if there isn't enough memory to
86 * record the key id.
87 *
88 * \param key_id    The PSA key identifier to record.
89 */
90#define TEST_USES_KEY_ID(key_id)                      \
91    TEST_ASSERT(mbedtls_test_uses_key_id(key_id))
92
93#else /* MBEDTLS_PSA_CRYPTO_STORAGE_C */
94
95#define TEST_USES_KEY_ID(key_id) ((void) (key_id))
96#define mbedtls_test_psa_purge_key_storage() ((void) 0)
97#define mbedtls_test_psa_purge_key_cache() ((void) 0)
98
99#endif /* MBEDTLS_PSA_CRYPTO_STORAGE_C */
100
101/** Check for things that have not been cleaned up properly in the
102 * PSA subsystem.
103 *
104 * \return NULL if nothing has leaked.
105 * \return A string literal explaining what has not been cleaned up
106 *         if applicable.
107 */
108const char *mbedtls_test_helper_is_psa_leaking(void);
109
110/** Check that no PSA Crypto key slots are in use.
111 *
112 * If any slots are in use, mark the current test as failed and jump to
113 * the exit label. This is equivalent to
114 * `TEST_ASSERT( ! mbedtls_test_helper_is_psa_leaking( ) )`
115 * but with a more informative message.
116 */
117#define ASSERT_PSA_PRISTINE()                                           \
118    do                                                                  \
119    {                                                                   \
120        if (mbedtls_test_fail_if_psa_leaking(__LINE__, __FILE__))       \
121        goto exit;                                                      \
122    }                                                                   \
123    while (0)
124
125/** Shut down the PSA Crypto subsystem, allowing persistent keys to survive.
126 * Expect a clean shutdown, with no slots in use.
127 *
128 * If some key slots are still in use, record the test case as failed and
129 * jump to the `exit` label.
130 */
131#define PSA_SESSION_DONE()                                             \
132    do                                                                  \
133    {                                                                   \
134        mbedtls_test_psa_purge_key_cache();                            \
135        ASSERT_PSA_PRISTINE();                                         \
136        mbedtls_psa_crypto_free();                                     \
137    }                                                                   \
138    while (0)
139
140
141
142#if defined(RECORD_PSA_STATUS_COVERAGE_LOG)
143psa_status_t mbedtls_test_record_status(psa_status_t status,
144                                        const char *func,
145                                        const char *file, int line,
146                                        const char *expr);
147
148/** Return value logging wrapper macro.
149 *
150 * Evaluate \p expr. Write a line recording its value to the log file
151 * #STATUS_LOG_FILE_NAME and return the value. The line is a colon-separated
152 * list of fields:
153 * ```
154 * value of expr:string:__FILE__:__LINE__:expr
155 * ```
156 *
157 * The test code does not call this macro explicitly because that would
158 * be very invasive. Instead, we instrument the source code by defining
159 * a bunch of wrapper macros like
160 * ```
161 * #define psa_crypto_init() RECORD_STATUS("psa_crypto_init", psa_crypto_init())
162 * ```
163 * These macro definitions must be present in `instrument_record_status.h`
164 * when building the test suites.
165 *
166 * \param string    A string, normally a function name.
167 * \param expr      An expression to evaluate, normally a call of the function
168 *                  whose name is in \p string. This expression must return
169 *                  a value of type #psa_status_t.
170 * \return          The value of \p expr.
171 */
172#define RECORD_STATUS(string, expr)                                   \
173    mbedtls_test_record_status((expr), string, __FILE__, __LINE__, #expr)
174
175#include "instrument_record_status.h"
176
177#endif /* defined(RECORD_PSA_STATUS_COVERAGE_LOG) */
178
179/** Return extended key usage policies.
180 *
181 * Do a key policy permission extension on key usage policies always involves
182 * permissions of other usage policies
183 * (like PSA_KEY_USAGE_SIGN_HASH involves PSA_KEY_USAGE_SIGN_MESSAGE).
184 */
185psa_key_usage_t mbedtls_test_update_key_usage_flags(psa_key_usage_t usage_flags);
186
187/** Check that no PSA Crypto key slots are in use.
188 *
189 * If any slots are in use, mark the current test as failed.
190 *
191 * \return 0 if the key store is empty, 1 otherwise.
192 */
193int mbedtls_test_fail_if_psa_leaking(int line_no, const char *filename);
194
195
196
197#if defined(MBEDTLS_PSA_INJECT_ENTROPY)
198/* The #MBEDTLS_PSA_INJECT_ENTROPY feature requires two extra platform
199 * functions, which must be configured as #MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
200 * and #MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO. The job of these functions
201 * is to read and write from the entropy seed file, which is located
202 * in the PSA ITS file whose uid is #PSA_CRYPTO_ITS_RANDOM_SEED_UID.
203 * (These could have been provided as library functions, but for historical
204 * reasons, they weren't, and so each integrator has to provide a copy
205 * of these functions.)
206 *
207 * Provide implementations of these functions for testing. */
208int mbedtls_test_inject_entropy_seed_read(unsigned char *buf, size_t len);
209int mbedtls_test_inject_entropy_seed_write(unsigned char *buf, size_t len);
210
211
212/** Make sure that the injected entropy is present.
213 *
214 * When MBEDTLS_PSA_INJECT_ENTROPY is enabled, psa_crypto_init()
215 * will fail if the PSA entropy seed is not present.
216 * This function must be called at least once in a test suite or other
217 * program before any call to psa_crypto_init().
218 * It does not need to be called in each test case.
219 *
220 * The test framework calls this function before running any test case.
221 *
222 * The few tests that might remove the entropy file must call this function
223 * in their cleanup.
224 */
225int mbedtls_test_inject_entropy_restore(void);
226#endif /* MBEDTLS_PSA_INJECT_ENTROPY */
227
228/** Parse binary string and convert it to a long integer
229 */
230uint64_t mbedtls_test_parse_binary_string(data_t *bin_string);
231
232/** Skip a test case if the given key is a 192 bits AES key and the AES
233 *  implementation is at least partially provided by an accelerator or
234 *  alternative implementation.
235 *
236 *  Call this macro in a test case when a cryptographic operation that may
237 *  involve an AES operation returns a #PSA_ERROR_NOT_SUPPORTED error code.
238 *  The macro call will skip and not fail the test case in case the operation
239 *  involves a 192 bits AES key and the AES implementation is at least
240 *  partially provided by an accelerator or alternative implementation.
241 *
242 *  Hardware AES implementations not supporting 192 bits keys commonly exist.
243 *  Consequently, PSA test cases aim at not failing when an AES operation with
244 *  a 192 bits key performed by an alternative AES implementation returns
245 *  with the #PSA_ERROR_NOT_SUPPORTED error code. The purpose of this macro
246 *  is to facilitate this and make the test case code more readable.
247 *
248 *  \param key_type  Key type
249 *  \param key_bits  Key length in number of bits.
250 */
251#if defined(MBEDTLS_AES_ALT) || \
252    defined(MBEDTLS_AES_SETKEY_ENC_ALT) || \
253    defined(MBEDTLS_PSA_ACCEL_KEY_TYPE_AES)
254#define MBEDTLS_TEST_HAVE_ALT_AES 1
255#else
256#define MBEDTLS_TEST_HAVE_ALT_AES 0
257#endif
258
259#define MBEDTLS_TEST_PSA_SKIP_IF_ALT_AES_192(key_type, key_bits)        \
260    do                                                                    \
261    {                                                                     \
262        if ((MBEDTLS_TEST_HAVE_ALT_AES) &&                              \
263            ((key_type) == PSA_KEY_TYPE_AES) &&                       \
264            (key_bits == 192))                                         \
265        {                                                                 \
266            mbedtls_test_skip("AES-192 not supported", __LINE__, __FILE__);     \
267            goto exit;                                                    \
268        }                                                                 \
269    }                                                                     \
270    while (0)
271
272/** Skip a test case if a GCM operation with a nonce length different from
273 *  12 bytes fails and was performed by an accelerator or alternative
274 *  implementation.
275 *
276 *  Call this macro in a test case when an AEAD cryptography operation that
277 *  may involve the GCM mode returns with a #PSA_ERROR_NOT_SUPPORTED error
278 *  code. The macro call will skip and not fail the test case in case the
279 *  operation involves the GCM mode, a nonce with a length different from
280 *  12 bytes and the GCM mode implementation is an alternative one.
281 *
282 *  Hardware GCM implementations not supporting nonce lengths different from
283 *  12 bytes commonly exist, as supporting a non-12-byte nonce requires
284 *  additional computations involving the GHASH function.
285 *  Consequently, PSA test cases aim at not failing when an AEAD operation in
286 *  GCM mode with a nonce length different from 12 bytes is performed by an
287 *  alternative GCM implementation and returns with a #PSA_ERROR_NOT_SUPPORTED
288 *  error code. The purpose of this macro is to facilitate this check and make
289 *  the test case code more readable.
290 *
291 *  \param  alg             The AEAD algorithm.
292 *  \param  nonce_length    The nonce length in number of bytes.
293 */
294#if defined(MBEDTLS_GCM_ALT) || \
295    defined(MBEDTLS_PSA_ACCEL_ALG_GCM)
296#define MBEDTLS_TEST_HAVE_ALT_GCM  1
297#else
298#define MBEDTLS_TEST_HAVE_ALT_GCM  0
299#endif
300
301#define MBEDTLS_TEST_PSA_SKIP_IF_ALT_GCM_NOT_12BYTES_NONCE(alg,           \
302                                                           nonce_length) \
303    do                                                                     \
304    {                                                                      \
305        if ((MBEDTLS_TEST_HAVE_ALT_GCM) &&                               \
306            (PSA_ALG_AEAD_WITH_SHORTENED_TAG((alg), 0) ==            \
307             PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, 0)) &&       \
308            ((nonce_length) != 12))                                   \
309        {                                                                  \
310            mbedtls_test_skip("GCM with non-12-byte IV is not supported", __LINE__, __FILE__); \
311            goto exit;                                                     \
312        }                                                                  \
313    }                                                                      \
314    while (0)
315
316#endif /* MBEDTLS_PSA_CRYPTO_C */
317
318/** \def USE_PSA_INIT
319 *
320 * Call this macro to initialize the PSA subsystem if #MBEDTLS_USE_PSA_CRYPTO
321 * or #MBEDTLS_SSL_PROTO_TLS1_3 (In contrast to TLS 1.2 implementation, the
322 * TLS 1.3 one uses PSA independently of the definition of
323 * #MBEDTLS_USE_PSA_CRYPTO) is enabled and do nothing otherwise.
324 *
325 * If the initialization fails, mark the test case as failed and jump to the
326 * \p exit label.
327 */
328/** \def USE_PSA_DONE
329 *
330 * Call this macro at the end of a test case if you called #USE_PSA_INIT.
331 *
332 * This is like #PSA_DONE except it does nothing under the same conditions as
333 * #USE_PSA_INIT.
334 */
335#if defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3)
336#define USE_PSA_INIT() PSA_INIT()
337#define USE_PSA_DONE() PSA_DONE()
338#else /* MBEDTLS_USE_PSA_CRYPTO || MBEDTLS_SSL_PROTO_TLS1_3 */
339/* Define empty macros so that we can use them in the preamble and teardown
340 * of every test function that uses PSA conditionally based on
341 * MBEDTLS_USE_PSA_CRYPTO. */
342#define USE_PSA_INIT() ((void) 0)
343#define USE_PSA_DONE() ((void) 0)
344#endif /* !MBEDTLS_USE_PSA_CRYPTO && !MBEDTLS_SSL_PROTO_TLS1_3 */
345
346/** \def MD_PSA_INIT
347 *
348 * Call this macro to initialize the PSA subsystem if MD uses a driver,
349 * and do nothing otherwise.
350 *
351 * If the initialization fails, mark the test case as failed and jump to the
352 * \p exit label.
353 */
354/** \def MD_PSA_DONE
355 *
356 * Call this macro at the end of a test case if you called #MD_PSA_INIT.
357 *
358 * This is like #PSA_DONE except it does nothing under the same conditions as
359 * #MD_PSA_INIT.
360 */
361#if defined(MBEDTLS_MD_SOME_PSA)
362#define MD_PSA_INIT()   PSA_INIT()
363#define MD_PSA_DONE()   PSA_DONE()
364#else /* MBEDTLS_MD_SOME_PSA */
365#define MD_PSA_INIT() ((void) 0)
366#define MD_PSA_DONE() ((void) 0)
367#endif /* MBEDTLS_MD_SOME_PSA */
368
369/** \def BLOCK_CIPHER_PSA_INIT
370 *
371 * Call this macro to initialize the PSA subsystem if BLOCK_CIPHER uses a driver,
372 * and do nothing otherwise.
373 *
374 * If the initialization fails, mark the test case as failed and jump to the
375 * \p exit label.
376 */
377/** \def BLOCK_CIPHER_PSA_DONE
378 *
379 * Call this macro at the end of a test case if you called #BLOCK_CIPHER_PSA_INIT.
380 *
381 * This is like #PSA_DONE except it does nothing under the same conditions as
382 * #BLOCK_CIPHER_PSA_INIT.
383 */
384#if defined(MBEDTLS_BLOCK_CIPHER_SOME_PSA)
385#define BLOCK_CIPHER_PSA_INIT()   PSA_INIT()
386#define BLOCK_CIPHER_PSA_DONE()   PSA_DONE()
387#else /* MBEDTLS_MD_SOME_PSA */
388#define BLOCK_CIPHER_PSA_INIT() ((void) 0)
389#define BLOCK_CIPHER_PSA_DONE() ((void) 0)
390#endif /* MBEDTLS_MD_SOME_PSA */
391
392
393/** \def MD_OR_USE_PSA_INIT
394 *
395 * Call this macro to initialize the PSA subsystem if MD uses a driver,
396 * or if #MBEDTLS_USE_PSA_CRYPTO or #MBEDTLS_SSL_PROTO_TLS1_3 is enabled,
397 * and do nothing otherwise.
398 *
399 * If the initialization fails, mark the test case as failed and jump to the
400 * \p exit label.
401 */
402/** \def MD_OR_USE_PSA_DONE
403 *
404 * Call this macro at the end of a test case if you called #MD_OR_USE_PSA_INIT.
405 *
406 * This is like #PSA_DONE except it does nothing under the same conditions as
407 * #MD_OR_USE_PSA_INIT.
408 */
409#if defined(MBEDTLS_MD_SOME_PSA) || \
410    defined(MBEDTLS_USE_PSA_CRYPTO) || defined(MBEDTLS_SSL_PROTO_TLS1_3)
411#define MD_OR_USE_PSA_INIT()   PSA_INIT()
412#define MD_OR_USE_PSA_DONE()   PSA_DONE()
413#else
414#define MD_OR_USE_PSA_INIT() ((void) 0)
415#define MD_OR_USE_PSA_DONE() ((void) 0)
416#endif
417
418/** \def AES_PSA_INIT
419 *
420 * Call this macro to initialize the PSA subsystem if AES_C is not defined,
421 * so that CTR_DRBG uses PSA implementation to get AES-ECB.
422 *
423 * If the initialization fails, mark the test case as failed and jump to the
424 * \p exit label.
425 */
426/** \def AES_PSA_DONE
427 *
428 * Call this macro at the end of a test case if you called #AES_PSA_INIT.
429 *
430 * This is like #PSA_DONE except it does nothing under the same conditions as
431 * #AES_PSA_INIT.
432 */
433#if defined(MBEDTLS_AES_C)
434#define AES_PSA_INIT() ((void) 0)
435#define AES_PSA_DONE() ((void) 0)
436#else /* MBEDTLS_AES_C */
437#define AES_PSA_INIT()   PSA_INIT()
438#define AES_PSA_DONE()   PSA_DONE()
439#endif /* MBEDTLS_AES_C */
440
441#endif /* PSA_CRYPTO_HELPERS_H */
442