blob: 8ac09c802bb7c7c178acdb37710b3ba2ddc2e48c [file] [log] [blame]
Gilles Peskine952f4092019-05-23 20:25:48 +02001/*
Gilles Peskine3cff7682019-06-20 12:54:43 +02002 * Helper functions for tests that use the PSA Crypto API.
Gilles Peskine952f4092019-05-23 20:25:48 +02003 */
Bence Szépkúti86974652020-06-15 11:59:37 +02004/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02005 * Copyright The Mbed TLS Contributors
Gilles Peskine952f4092019-05-23 20:25:48 +02006 * 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.
Gilles Peskine952f4092019-05-23 20:25:48 +020019 */
20
Gilles Peskine1838e822019-06-20 12:40:56 +020021#ifndef PSA_CRYPTO_HELPERS_H
22#define PSA_CRYPTO_HELPERS_H
23
Ronald Cron28a45ed2021-02-09 20:35:42 +010024#include "test/helpers.h"
Gilles Peskine9de97e22021-02-02 21:00:11 +010025
26#if defined(MBEDTLS_PSA_CRYPTO_C)
27
Ronald Cron02c78b72020-05-27 09:22:32 +020028#include "test/psa_helpers.h"
Gilles Peskine952f4092019-05-23 20:25:48 +020029
Gilles Peskine3cff7682019-06-20 12:54:43 +020030#include <psa/crypto.h>
Gilles Peskine952f4092019-05-23 20:25:48 +020031
Gilles Peskine9de97e22021-02-02 21:00:11 +010032#if defined(MBEDTLS_USE_PSA_CRYPTO)
33#include "mbedtls/psa_util.h"
34#endif
35
Gilles Peskine313ffb82021-02-14 12:51:14 +010036#if defined(MBEDTLS_PSA_CRYPTO_STORAGE_C)
Gilles Peskinee09ef872021-02-14 13:10:38 +010037
38/* Internal function for #TEST_USES_KEY_ID. Return 1 on success, 0 on failure. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010039int mbedtls_test_uses_key_id(mbedtls_svc_key_id_t key_id);
Gilles Peskinee09ef872021-02-14 13:10:38 +010040
41/** Destroy persistent keys recorded with #TEST_USES_KEY_ID.
42 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010043void mbedtls_test_psa_purge_key_storage(void);
Gilles Peskinee09ef872021-02-14 13:10:38 +010044
Gilles Peskineaae718c2021-02-14 13:46:39 +010045/** Purge the in-memory cache of persistent keys recorded with
46 * #TEST_USES_KEY_ID.
Gilles Peskine65048ad2021-02-14 14:08:22 +010047 *
48 * Call this function before calling PSA_DONE() if it's ok for
49 * persistent keys to still exist at this point.
Gilles Peskineaae718c2021-02-14 13:46:39 +010050 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010051void mbedtls_test_psa_purge_key_cache(void);
Gilles Peskineaae718c2021-02-14 13:46:39 +010052
Gilles Peskinee09ef872021-02-14 13:10:38 +010053/** \def TEST_USES_KEY_ID
54 *
55 * Call this macro in a test function before potentially creating a
56 * persistent key. Test functions that use this mechanism must call
57 * mbedtls_test_psa_purge_key_storage() in their cleanup code.
58 *
59 * This macro records a persistent key identifier as potentially used in the
60 * current test case. Recorded key identifiers will be cleaned up at the end
61 * of the test case, even on failure.
62 *
63 * This macro has no effect on volatile keys. Therefore, it is safe to call
64 * this macro in a test function that creates either volatile or persistent
65 * keys depending on the test data.
66 *
67 * This macro currently has no effect on special identifiers
68 * used to store implementation-specific files.
69 *
70 * Calling this macro multiple times on the same key identifier in the same
71 * test case has no effect.
72 *
73 * This macro can fail the test case if there isn't enough memory to
74 * record the key id.
75 *
76 * \param key_id The PSA key identifier to record.
77 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010078#define TEST_USES_KEY_ID(key_id) \
79 TEST_ASSERT(mbedtls_test_uses_key_id(key_id))
Gilles Peskinee09ef872021-02-14 13:10:38 +010080
Gilles Peskine313ffb82021-02-14 12:51:14 +010081#else /* MBEDTLS_PSA_CRYPTO_STORAGE_C */
Gilles Peskinee09ef872021-02-14 13:10:38 +010082
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010083#define TEST_USES_KEY_ID(key_id) ((void) (key_id))
84#define mbedtls_test_psa_purge_key_storage() ((void) 0)
85#define mbedtls_test_psa_purge_key_cache() ((void) 0)
Gilles Peskinee09ef872021-02-14 13:10:38 +010086
Gilles Peskine313ffb82021-02-14 12:51:14 +010087#endif /* MBEDTLS_PSA_CRYPTO_STORAGE_C */
88
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010089#define PSA_INIT() PSA_ASSERT(psa_crypto_init())
Gilles Peskine9de97e22021-02-02 21:00:11 +010090
Gilles Peskine1e005652020-11-24 17:41:07 +010091/** Check for things that have not been cleaned up properly in the
92 * PSA subsystem.
93 *
94 * \return NULL if nothing has leaked.
95 * \return A string literal explaining what has not been cleaned up
96 * if applicable.
97 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +010098const char *mbedtls_test_helper_is_psa_leaking(void);
Gilles Peskinedd413d32019-05-28 15:06:43 +020099
Gilles Peskine3cff7682019-06-20 12:54:43 +0200100/** Check that no PSA Crypto key slots are in use.
Gilles Peskinec85c2012021-01-06 20:47:16 +0100101 *
102 * If any slots are in use, mark the current test as failed and jump to
103 * the exit label. This is equivalent to
104 * `TEST_ASSERT( ! mbedtls_test_helper_is_psa_leaking( ) )`
105 * but with a more informative message.
Gilles Peskinedd413d32019-05-28 15:06:43 +0200106 */
Yanray Wang89b4d122022-10-28 18:12:01 +0800107#define ASSERT_PSA_PRISTINE() \
Gilles Peskinec85c2012021-01-06 20:47:16 +0100108 do \
109 { \
Yanray Wang89b4d122022-10-28 18:12:01 +0800110 if (mbedtls_test_fail_if_psa_leaking(__LINE__, __FILE__)) \
111 goto exit; \
Gilles Peskinec85c2012021-01-06 20:47:16 +0100112 } \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100113 while (0)
Gilles Peskinea6d252a2019-05-23 20:34:30 +0200114
Gilles Peskine65048ad2021-02-14 14:08:22 +0100115/** Shut down the PSA Crypto subsystem and destroy persistent keys.
116 * Expect a clean shutdown, with no slots in use.
117 *
118 * If some key slots are still in use, record the test case as failed,
119 * but continue executing. This macro is suitable (and primarily intended)
120 * for use in the cleanup section of test functions.
121 *
122 * \note Persistent keys must be recorded with #TEST_USES_KEY_ID before
123 * creating them.
Gilles Peskinea6d252a2019-05-23 20:34:30 +0200124 */
Yanray Wang89b4d122022-10-28 18:12:01 +0800125#define PSA_DONE() \
Gilles Peskinec85c2012021-01-06 20:47:16 +0100126 do \
127 { \
Yanray Wang89b4d122022-10-28 18:12:01 +0800128 mbedtls_test_fail_if_psa_leaking(__LINE__, __FILE__); \
129 mbedtls_test_psa_purge_key_storage(); \
130 mbedtls_psa_crypto_free(); \
Gilles Peskine65048ad2021-02-14 14:08:22 +0100131 } \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100132 while (0)
Gilles Peskine65048ad2021-02-14 14:08:22 +0100133
134/** Shut down the PSA Crypto subsystem, allowing persistent keys to survive.
135 * Expect a clean shutdown, with no slots in use.
136 *
137 * If some key slots are still in use, record the test case as failed and
138 * jump to the `exit` label.
139 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100140#define PSA_SESSION_DONE() \
Gilles Peskine65048ad2021-02-14 14:08:22 +0100141 do \
142 { \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100143 mbedtls_test_psa_purge_key_cache(); \
144 ASSERT_PSA_PRISTINE(); \
145 mbedtls_psa_crypto_free(); \
Gilles Peskinec85c2012021-01-06 20:47:16 +0100146 } \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100147 while (0)
Gilles Peskinea6d252a2019-05-23 20:34:30 +0200148
Gilles Peskine51681552019-05-20 19:35:37 +0200149
150
151#if defined(RECORD_PSA_STATUS_COVERAGE_LOG)
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100152psa_status_t mbedtls_test_record_status(psa_status_t status,
153 const char *func,
154 const char *file, int line,
155 const char *expr);
Gilles Peskine51681552019-05-20 19:35:37 +0200156
157/** Return value logging wrapper macro.
158 *
159 * Evaluate \p expr. Write a line recording its value to the log file
160 * #STATUS_LOG_FILE_NAME and return the value. The line is a colon-separated
161 * list of fields:
162 * ```
163 * value of expr:string:__FILE__:__LINE__:expr
164 * ```
165 *
166 * The test code does not call this macro explicitly because that would
167 * be very invasive. Instead, we instrument the source code by defining
168 * a bunch of wrapper macros like
169 * ```
170 * #define psa_crypto_init() RECORD_STATUS("psa_crypto_init", psa_crypto_init())
171 * ```
172 * These macro definitions must be present in `instrument_record_status.h`
173 * when building the test suites.
174 *
175 * \param string A string, normally a function name.
176 * \param expr An expression to evaluate, normally a call of the function
177 * whose name is in \p string. This expression must return
178 * a value of type #psa_status_t.
179 * \return The value of \p expr.
180 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100181#define RECORD_STATUS(string, expr) \
182 mbedtls_test_record_status((expr), string, __FILE__, __LINE__, #expr)
Gilles Peskine51681552019-05-20 19:35:37 +0200183
184#include "instrument_record_status.h"
185
186#endif /* defined(RECORD_PSA_STATUS_COVERAGE_LOG) */
187
gabor-mezei-arm4d9009e2021-05-13 12:05:01 +0200188/** Return extended key usage policies.
189 *
190 * Do a key policy permission extension on key usage policies always involves
191 * permissions of other usage policies
Tom Cosgrove49f99bc2022-12-04 16:44:21 +0000192 * (like PSA_KEY_USAGE_SIGN_HASH involves PSA_KEY_USAGE_SIGN_MESSAGE).
gabor-mezei-arm4d9009e2021-05-13 12:05:01 +0200193 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100194psa_key_usage_t mbedtls_test_update_key_usage_flags(psa_key_usage_t usage_flags);
gabor-mezei-arm4d9009e2021-05-13 12:05:01 +0200195
Yanray Wang89b4d122022-10-28 18:12:01 +0800196/** Check that no PSA Crypto key slots are in use.
197 *
198 * If any slots are in use, mark the current test as failed.
199 *
200 * \return 0 if the key store is empty, 1 otherwise.
201 */
202int mbedtls_test_fail_if_psa_leaking(int line_no, const char *filename);
203
Gilles Peskine73521b02023-04-28 21:01:49 +0200204
205
206#if defined(MBEDTLS_PSA_INJECT_ENTROPY)
207/* The #MBEDTLS_PSA_INJECT_ENTROPY feature requires two extra platform
208 * functions, which must be configured as #MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
209 * and #MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO. The job of these functions
210 * is to read and write from the entropy seed file, which is located
211 * in the PSA ITS file whose uid is #PSA_CRYPTO_ITS_RANDOM_SEED_UID.
212 * (These could have been provided as library functions, but for historical
213 * reasons, they weren't, and so each integrator has to provide a copy
214 * of these functions.)
215 *
216 * Provide implementations of these functions for testing. */
217int mbedtls_test_inject_entropy_seed_read(unsigned char *buf, size_t len);
218int mbedtls_test_inject_entropy_seed_write(unsigned char *buf, size_t len);
Gilles Peskine4f8bf3c2023-04-28 23:39:45 +0200219
220
221/** Make sure that the injected entropy is present.
222 *
223 * When MBEDTLS_PSA_INJECT_ENTROPY is enabled, psa_crypto_init()
224 * will fail if the PSA entropy seed is not present.
225 * This function must be called at least once in a test suite or other
226 * program before any call to psa_crypto_init().
227 * It does not need to be called in each test case.
228 *
229 * The test framework calls this function before running any test case.
230 *
231 * The few tests that might remove the entropy file must call this function
232 * in their cleanup.
233 */
234int mbedtls_test_inject_entropy_restore(void);
Gilles Peskine73521b02023-04-28 21:01:49 +0200235#endif /* MBEDTLS_PSA_INJECT_ENTROPY */
236
237
238
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100239/** Skip a test case if the given key is a 192 bits AES key and the AES
240 * implementation is at least partially provided by an accelerator or
Ronald Cron28a45ed2021-02-09 20:35:42 +0100241 * alternative implementation.
242 *
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100243 * Call this macro in a test case when a cryptographic operation that may
244 * involve an AES operation returns a #PSA_ERROR_NOT_SUPPORTED error code.
245 * The macro call will skip and not fail the test case in case the operation
246 * involves a 192 bits AES key and the AES implementation is at least
247 * partially provided by an accelerator or alternative implementation.
248 *
249 * Hardware AES implementations not supporting 192 bits keys commonly exist.
Ronald Cron28a45ed2021-02-09 20:35:42 +0100250 * Consequently, PSA test cases aim at not failing when an AES operation with
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100251 * a 192 bits key performed by an alternative AES implementation returns
252 * with the #PSA_ERROR_NOT_SUPPORTED error code. The purpose of this macro
253 * is to facilitate this and make the test case code more readable.
Ronald Cron28a45ed2021-02-09 20:35:42 +0100254 *
255 * \param key_type Key type
256 * \param key_bits Key length in number of bits.
257 */
258#if defined(MBEDTLS_AES_ALT) || \
259 defined(MBEDTLS_AES_SETKEY_ENC_ALT) || \
260 defined(MBEDTLS_PSA_ACCEL_KEY_TYPE_AES)
261#define MBEDTLS_TEST_HAVE_ALT_AES 1
262#else
263#define MBEDTLS_TEST_HAVE_ALT_AES 0
264#endif
265
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100266#define MBEDTLS_TEST_PSA_SKIP_IF_ALT_AES_192(key_type, key_bits) \
Ronald Cron28a45ed2021-02-09 20:35:42 +0100267 do \
268 { \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100269 if ((MBEDTLS_TEST_HAVE_ALT_AES) && \
270 ((key_type) == PSA_KEY_TYPE_AES) && \
271 (key_bits == 192)) \
Ronald Cron28a45ed2021-02-09 20:35:42 +0100272 { \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100273 mbedtls_test_skip("AES-192 not supported", __LINE__, __FILE__); \
Ronald Cron28a45ed2021-02-09 20:35:42 +0100274 goto exit; \
275 } \
276 } \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100277 while (0)
Ronald Cron28a45ed2021-02-09 20:35:42 +0100278
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100279/** Skip a test case if a GCM operation with a nonce length different from
280 * 12 bytes fails and was performed by an accelerator or alternative
281 * implementation.
Ronald Cron28a45ed2021-02-09 20:35:42 +0100282 *
283 * Call this macro in a test case when an AEAD cryptography operation that
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100284 * may involve the GCM mode returns with a #PSA_ERROR_NOT_SUPPORTED error
285 * code. The macro call will skip and not fail the test case in case the
286 * operation involves the GCM mode, a nonce with a length different from
287 * 12 bytes and the GCM mode implementation is an alternative one.
Ronald Cron28a45ed2021-02-09 20:35:42 +0100288 *
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100289 * Hardware GCM implementations not supporting nonce lengths different from
290 * 12 bytes commonly exist, as supporting a non-12-byte nonce requires
291 * additional computations involving the GHASH function.
292 * Consequently, PSA test cases aim at not failing when an AEAD operation in
293 * GCM mode with a nonce length different from 12 bytes is performed by an
294 * alternative GCM implementation and returns with a #PSA_ERROR_NOT_SUPPORTED
295 * error code. The purpose of this macro is to facilitate this check and make
296 * the test case code more readable.
Ronald Cron28a45ed2021-02-09 20:35:42 +0100297 *
Steven Cooreman1e9c0422021-02-10 17:02:05 +0100298 * \param alg The AEAD algorithm.
299 * \param nonce_length The nonce length in number of bytes.
Ronald Cron28a45ed2021-02-09 20:35:42 +0100300 */
Ronald Cron28a45ed2021-02-09 20:35:42 +0100301#if defined(MBEDTLS_GCM_ALT) || \
302 defined(MBEDTLS_PSA_ACCEL_ALG_GCM)
303#define MBEDTLS_TEST_HAVE_ALT_GCM 1
304#else
305#define MBEDTLS_TEST_HAVE_ALT_GCM 0
306#endif
307
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100308#define MBEDTLS_TEST_PSA_SKIP_IF_ALT_GCM_NOT_12BYTES_NONCE(alg, \
309 nonce_length) \
Ronald Cron28a45ed2021-02-09 20:35:42 +0100310 do \
311 { \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100312 if ((MBEDTLS_TEST_HAVE_ALT_GCM) && \
313 (PSA_ALG_AEAD_WITH_SHORTENED_TAG((alg), 0) == \
314 PSA_ALG_AEAD_WITH_SHORTENED_TAG(PSA_ALG_GCM, 0)) && \
315 ((nonce_length) != 12)) \
Ronald Cron28a45ed2021-02-09 20:35:42 +0100316 { \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100317 mbedtls_test_skip("GCM with non-12-byte IV is not supported", __LINE__, __FILE__); \
Ronald Cron28a45ed2021-02-09 20:35:42 +0100318 goto exit; \
319 } \
320 } \
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100321 while (0)
Ronald Cron28a45ed2021-02-09 20:35:42 +0100322
Gilles Peskine9de97e22021-02-02 21:00:11 +0100323#endif /* MBEDTLS_PSA_CRYPTO_C */
324
325/** \def USE_PSA_INIT
326 *
327 * Call this macro to initialize the PSA subsystem if #MBEDTLS_USE_PSA_CRYPTO
328 * is enabled and do nothing otherwise. If the initialization fails, mark
329 * the test case as failed and jump to the \p exit label.
330 */
331/** \def USE_PSA_DONE
332 *
333 * Call this macro at the end of a test case if you called #USE_PSA_INIT.
334 * This is like #PSA_DONE, except that it does nothing if
335 * #MBEDTLS_USE_PSA_CRYPTO is disabled.
336 */
337#if defined(MBEDTLS_USE_PSA_CRYPTO)
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100338#define USE_PSA_INIT() PSA_INIT()
339#define USE_PSA_DONE() PSA_DONE()
Gilles Peskine9de97e22021-02-02 21:00:11 +0100340#else /* MBEDTLS_USE_PSA_CRYPTO */
341/* Define empty macros so that we can use them in the preamble and teardown
342 * of every test function that uses PSA conditionally based on
343 * MBEDTLS_USE_PSA_CRYPTO. */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100344#define USE_PSA_INIT() ((void) 0)
345#define USE_PSA_DONE() ((void) 0)
Gilles Peskine9de97e22021-02-02 21:00:11 +0100346#endif /* !MBEDTLS_USE_PSA_CRYPTO */
347
Gilles Peskine1838e822019-06-20 12:40:56 +0200348#endif /* PSA_CRYPTO_HELPERS_H */