blob: b8eb4aa5d4fc673e45695740fb4b61edb9d837bb [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 Cron02c78b72020-05-27 09:22:32 +020024#include "test/psa_helpers.h"
Gilles Peskine952f4092019-05-23 20:25:48 +020025
Gilles Peskine3cff7682019-06-20 12:54:43 +020026#include <psa/crypto.h>
Ronald Cron0c3752a2020-10-30 11:54:03 +010027#include <psa_crypto_slot_management.h>
Gilles Peskine952f4092019-05-23 20:25:48 +020028
Gilles Peskine1e005652020-11-24 17:41:07 +010029/** Check for things that have not been cleaned up properly in the
30 * PSA subsystem.
31 *
32 * \return NULL if nothing has leaked.
33 * \return A string literal explaining what has not been cleaned up
34 * if applicable.
35 */
Gilles Peskined4008d52020-11-24 17:34:30 +010036const char *mbedtls_test_helper_is_psa_leaking( void );
Gilles Peskinedd413d32019-05-28 15:06:43 +020037
Gilles Peskine3cff7682019-06-20 12:54:43 +020038/** Check that no PSA Crypto key slots are in use.
Gilles Peskinec85c2012021-01-06 20:47:16 +010039 *
40 * If any slots are in use, mark the current test as failed and jump to
41 * the exit label. This is equivalent to
42 * `TEST_ASSERT( ! mbedtls_test_helper_is_psa_leaking( ) )`
43 * but with a more informative message.
Gilles Peskinedd413d32019-05-28 15:06:43 +020044 */
Gilles Peskinec85c2012021-01-06 20:47:16 +010045#define ASSERT_PSA_PRISTINE( ) \
46 do \
47 { \
48 if( test_fail_if_psa_leaking( __LINE__, __FILE__ ) ) \
49 goto exit; \
50 } \
51 while( 0 )
Gilles Peskinea6d252a2019-05-23 20:34:30 +020052
Gilles Peskine3cff7682019-06-20 12:54:43 +020053/** Shut down the PSA Crypto subsystem. Expect a clean shutdown, with no slots
Gilles Peskinea6d252a2019-05-23 20:34:30 +020054 * in use.
55 */
Gilles Peskinec85c2012021-01-06 20:47:16 +010056#define PSA_DONE( ) \
57 do \
58 { \
59 test_fail_if_psa_leaking( __LINE__, __FILE__ ); \
60 mbedtls_psa_crypto_free( ); \
61 } \
Gilles Peskine1e005652020-11-24 17:41:07 +010062 while( 0 )
Gilles Peskinea6d252a2019-05-23 20:34:30 +020063
Gilles Peskine51681552019-05-20 19:35:37 +020064
65
Gilles Peskine76175ba2020-11-24 18:39:12 +010066#if defined(MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG)
67/** Enable the insecure implementation of mbedtls_psa_external_get_random().
68 *
69 * The insecure implementation of mbedtls_psa_external_get_random() is
70 * disabled by default.
71 *
72 * When MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled and the test
Gilles Peskinec85c2012021-01-06 20:47:16 +010073 * helpers are linked into a program, you must enable this before running any
74 * code that uses the PSA subsystem to generate random data (including internal
Gilles Peskine76175ba2020-11-24 18:39:12 +010075 * random generation for purposes such as blinding when the random generation
76 * is routed through PSA).
77 *
78 * You can enable and disable it at any time, regardless of the state
79 * of the PSA subsystem. You may disable it temporarily to simulate a
80 * depleted entropy source.
81 */
82void mbedtls_test_enable_insecure_external_rng( void );
83
84/** Disable the insecure implementation of mbedtls_psa_external_get_random().
85 *
86 * See mbedtls_test_enable_insecure_external_rng().
87 */
88void mbedtls_test_disable_insecure_external_rng( void );
89#endif /* MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG */
90
91
Gilles Peskine51681552019-05-20 19:35:37 +020092#if defined(RECORD_PSA_STATUS_COVERAGE_LOG)
Gilles Peskined4008d52020-11-24 17:34:30 +010093psa_status_t mbedtls_test_record_status( psa_status_t status,
94 const char *func,
95 const char *file, int line,
96 const char *expr );
Gilles Peskine51681552019-05-20 19:35:37 +020097
98/** Return value logging wrapper macro.
99 *
100 * Evaluate \p expr. Write a line recording its value to the log file
101 * #STATUS_LOG_FILE_NAME and return the value. The line is a colon-separated
102 * list of fields:
103 * ```
104 * value of expr:string:__FILE__:__LINE__:expr
105 * ```
106 *
107 * The test code does not call this macro explicitly because that would
108 * be very invasive. Instead, we instrument the source code by defining
109 * a bunch of wrapper macros like
110 * ```
111 * #define psa_crypto_init() RECORD_STATUS("psa_crypto_init", psa_crypto_init())
112 * ```
113 * These macro definitions must be present in `instrument_record_status.h`
114 * when building the test suites.
115 *
116 * \param string A string, normally a function name.
117 * \param expr An expression to evaluate, normally a call of the function
118 * whose name is in \p string. This expression must return
119 * a value of type #psa_status_t.
120 * \return The value of \p expr.
121 */
122#define RECORD_STATUS( string, expr ) \
Gilles Peskineddfd0802020-11-24 17:07:05 +0100123 mbedtls_test_record_status( ( expr ), string, __FILE__, __LINE__, #expr )
Gilles Peskine51681552019-05-20 19:35:37 +0200124
125#include "instrument_record_status.h"
126
127#endif /* defined(RECORD_PSA_STATUS_COVERAGE_LOG) */
128
Gilles Peskine1838e822019-06-20 12:40:56 +0200129#endif /* PSA_CRYPTO_HELPERS_H */