blob: cad2be94fcc8a827eeb2cf1571a07cb98775daae [file] [log] [blame]
Gilles Peskine66e7b902021-02-12 23:40:58 +01001/** 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
Dave Rodgman7ff79652023-11-03 12:04:52 +00006 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Gilles Peskine66e7b902021-02-12 23:40:58 +01007 */
8
9#ifndef PSA_EXERCISE_KEY_H
10#define PSA_EXERCISE_KEY_H
11
12#include "test/helpers.h"
13#include "test/psa_crypto_helpers.h"
14
15#include <psa/crypto.h>
16
Gilles Peskinee50b5782021-02-14 01:13:55 +010017/** \def KNOWN_SUPPORTED_HASH_ALG
18 *
19 * A hash algorithm that is known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010020 *
21 * This is used in some smoke tests.
22 */
23#if defined(PSA_WANT_ALG_MD2)
24#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD2
25#elif defined(PSA_WANT_ALG_MD4)
26#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD4
27#elif defined(PSA_WANT_ALG_MD5)
28#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD5
29/* MBEDTLS_RIPEMD160_C omitted. This is necessary for the sake of
30 * exercise_signature_key() because Mbed TLS doesn't support RIPEMD160
31 * in RSA PKCS#1v1.5 signatures. A RIPEMD160-only configuration would be
32 * implausible anyway. */
33#elif defined(PSA_WANT_ALG_SHA_1)
34#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_1
35#elif defined(PSA_WANT_ALG_SHA_256)
36#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_256
37#elif defined(PSA_WANT_ALG_SHA_384)
38#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_384
39#elif defined(PSA_WANT_ALG_SHA_512)
40#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_512
41#elif defined(PSA_WANT_ALG_SHA3_256)
42#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA3_256
43#else
44#undef KNOWN_SUPPORTED_HASH_ALG
45#endif
46
Ronald Cronef14af02021-08-31 19:08:55 +020047/** \def KNOWN_MBEDTLS_SUPPORTED_HASH_ALG
48 *
49 * A hash algorithm that is known to be supported by Mbed TLS APIs.
50 *
51 * This is used in some smoke tests where the hash algorithm is used as
52 * part of another algorithm like a signature algorithm and the hashing is
53 * completed through an Mbed TLS hash API, not the PSA one.
54 */
55#if defined(MBEDTLS_MD2_C)
56#define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_MD2
57#elif defined(MBEDTLS_MD4_C)
58#define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_MD4
59#elif defined(MBEDTLS_MD5_C)
60#define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_MD5
61/* MBEDTLS_RIPEMD160_C omitted. This is necessary for the sake of
62 * exercise_signature_key() because Mbed TLS doesn't support RIPEMD160
63 * in RSA PKCS#1v1.5 signatures. A RIPEMD160-only configuration would be
64 * implausible anyway. */
65#elif defined(MBEDTLS_SHA1_C)
66#define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_SHA_1
67#elif defined(MBEDTLS_SHA256_C)
68#define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_SHA_256
69#elif defined(MBEDTLS_SHA512_C)
70#define KNOWN_MBEDTLS_SUPPORTED_HASH_ALG PSA_ALG_SHA_512
71#else
Dave Rodgmana03396a2022-12-06 16:30:38 +000072#undef KNOWN_MBEDTLS_SUPPORTED_HASH_ALG
Ronald Cronef14af02021-08-31 19:08:55 +020073#endif
74
Gilles Peskinee50b5782021-02-14 01:13:55 +010075/** \def KNOWN_SUPPORTED_BLOCK_CIPHER
76 *
77 * A block cipher that is known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010078 *
79 * For simplicity's sake, stick to block ciphers with 16-byte blocks.
80 */
81#if defined(MBEDTLS_AES_C)
82#define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_AES
83#elif defined(MBEDTLS_ARIA_C)
84#define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_ARIA
85#elif defined(MBEDTLS_CAMELLIA_C)
86#define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_CAMELLIA
87#undef KNOWN_SUPPORTED_BLOCK_CIPHER
88#endif
89
Gilles Peskinee50b5782021-02-14 01:13:55 +010090/** \def KNOWN_SUPPORTED_MAC_ALG
91 *
92 * A MAC mode that is known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010093 *
94 * It must either be HMAC with #KNOWN_SUPPORTED_HASH_ALG or
95 * a block cipher-based MAC with #KNOWN_SUPPORTED_BLOCK_CIPHER.
96 *
97 * This is used in some smoke tests.
98 */
99#if defined(KNOWN_SUPPORTED_HASH_ALG) && defined(PSA_WANT_ALG_HMAC)
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100100#define KNOWN_SUPPORTED_MAC_ALG (PSA_ALG_HMAC(KNOWN_SUPPORTED_HASH_ALG))
Gilles Peskinee78b0022021-02-13 00:41:11 +0100101#define KNOWN_SUPPORTED_MAC_KEY_TYPE PSA_KEY_TYPE_HMAC
102#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CMAC_C)
103#define KNOWN_SUPPORTED_MAC_ALG PSA_ALG_CMAC
104#define KNOWN_SUPPORTED_MAC_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER
105#else
106#undef KNOWN_SUPPORTED_MAC_ALG
107#undef KNOWN_SUPPORTED_MAC_KEY_TYPE
108#endif
109
Gilles Peskinee50b5782021-02-14 01:13:55 +0100110/** \def KNOWN_SUPPORTED_BLOCK_CIPHER_ALG
111 *
112 * A cipher algorithm and key type that are known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +0100113 *
114 * This is used in some smoke tests.
115 */
116#if defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CTR)
117#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CTR
118#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CBC)
119#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CBC_NO_PADDING
120#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CFB)
121#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CFB
122#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_OFB)
123#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_OFB
124#else
125#undef KNOWN_SUPPORTED_BLOCK_CIPHER_ALG
126#endif
127#if defined(KNOWN_SUPPORTED_BLOCK_CIPHER_ALG)
128#define KNOWN_SUPPORTED_CIPHER_ALG KNOWN_SUPPORTED_BLOCK_CIPHER_ALG
129#define KNOWN_SUPPORTED_CIPHER_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER
130#elif defined(MBEDTLS_RC4_C)
131#define KNOWN_SUPPORTED_CIPHER_ALG PSA_ALG_RC4
132#define KNOWN_SUPPORTED_CIPHER_KEY_TYPE PSA_KEY_TYPE_RC4
133#else
134#undef KNOWN_SUPPORTED_CIPHER_ALG
135#undef KNOWN_SUPPORTED_CIPHER_KEY_TYPE
136#endif
137
Gilles Peskinee50b5782021-02-14 01:13:55 +0100138/** Convenience function to set up a key derivation.
139 *
140 * In case of failure, mark the current test case as failed.
141 *
142 * The inputs \p input1 and \p input2 are, in order:
143 * - HKDF: salt, info.
144 * - TKS 1.2 PRF, TLS 1.2 PSK-to-MS: seed, label.
145 *
146 * \param operation The operation object to use.
147 * It must be in the initialized state.
148 * \param key The key to use.
149 * \param alg The algorithm to use.
150 * \param input1 The first input to pass.
151 * \param input1_length The length of \p input1 in bytes.
Gilles Peskine5a7702e2021-02-23 13:40:19 +0100152 * \param input2 The first input to pass.
153 * \param input2_length The length of \p input2 in bytes.
Gilles Peskinee50b5782021-02-14 01:13:55 +0100154 * \param capacity The capacity to set.
155 *
156 * \return \c 1 on success, \c 0 on failure.
157 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100158int mbedtls_test_psa_setup_key_derivation_wrap(
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100159 psa_key_derivation_operation_t *operation,
Gilles Peskinee78b0022021-02-13 00:41:11 +0100160 mbedtls_svc_key_id_t key,
161 psa_algorithm_t alg,
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100162 const unsigned char *input1, size_t input1_length,
163 const unsigned char *input2, size_t input2_length,
164 size_t capacity);
Gilles Peskinee78b0022021-02-13 00:41:11 +0100165
Gilles Peskinee50b5782021-02-14 01:13:55 +0100166/** Perform a key agreement using the given key pair against its public key
167 * using psa_raw_key_agreement().
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 *
173 * \param alg A key agreement algorithm compatible with \p key.
174 * \param key A key that allows key agreement with \p alg.
175 *
176 * \return \c 1 on success, \c 0 on failure.
177 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100178psa_status_t mbedtls_test_psa_raw_key_agreement_with_self(
179 psa_algorithm_t alg,
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100180 mbedtls_svc_key_id_t key);
Gilles Peskinee78b0022021-02-13 00:41:11 +0100181
Gilles Peskinee50b5782021-02-14 01:13:55 +0100182/** Perform a key agreement using the given key pair against its public key
183 * using psa_key_derivation_raw_key().
184 *
185 * The result is discarded. The purpose of this function is to smoke-test a key.
186 *
187 * In case of failure, mark the current test case as failed.
188 *
Gilles Peskine5a7702e2021-02-23 13:40:19 +0100189 * \param operation An operation that has been set up for a key
190 * agreement algorithm that is compatible with
191 * \p key.
192 * \param key A key pair object that is suitable for a key
193 * agreement with \p operation.
Gilles Peskinee50b5782021-02-14 01:13:55 +0100194 *
195 * \return \c 1 on success, \c 0 on failure.
196 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100197psa_status_t mbedtls_test_psa_key_agreement_with_self(
198 psa_key_derivation_operation_t *operation,
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100199 mbedtls_svc_key_id_t key);
Gilles Peskinee78b0022021-02-13 00:41:11 +0100200
Gilles Peskinee50b5782021-02-14 01:13:55 +0100201/** Perform sanity checks on the given key representation.
202 *
203 * If any of the checks fail, mark the current test case as failed.
204 *
205 * The checks depend on the key type.
206 * - All types: check the export size against maximum-size macros.
207 * - DES: parity bits.
208 * - RSA: check the ASN.1 structure and the size and parity of the integers.
209 * - ECC private or public key: exact representation length.
210 * - Montgomery public key: first byte.
211 *
212 * \param type The key type.
Gilles Peskine5a7702e2021-02-23 13:40:19 +0100213 * \param bits The key size in bits.
214 * \param exported A buffer containing the key representation.
215 * \param exported_length The length of \p exported in bytes.
Gilles Peskinee50b5782021-02-14 01:13:55 +0100216 *
217 * \return \c 1 if all checks passed, \c 0 on failure.
218 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100219int mbedtls_test_psa_exported_key_sanity_check(
220 psa_key_type_t type, size_t bits,
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100221 const uint8_t *exported, size_t exported_length);
Gilles Peskinee78b0022021-02-13 00:41:11 +0100222
223/** Do smoke tests on a key.
224 *
225 * Perform one of each operation indicated by \p alg (decrypt/encrypt,
226 * sign/verify, or derivation) that is permitted according to \p usage.
227 * \p usage and \p alg should correspond to the expected policy on the
228 * key.
229 *
230 * Export the key if permitted by \p usage, and check that the output
231 * looks sensible. If \p usage forbids export, check that
232 * \p psa_export_key correctly rejects the attempt. If the key is
233 * asymmetric, also check \p psa_export_public_key.
234 *
235 * If the key fails the tests, this function calls the test framework's
236 * `mbedtls_test_fail` function and returns false. Otherwise this function
237 * returns true. Therefore it should be used as follows:
238 * ```
239 * if( ! exercise_key( ... ) ) goto exit;
240 * ```
241 *
242 * \param key The key to exercise. It should be capable of performing
243 * \p alg.
244 * \param usage The usage flags to assume.
245 * \param alg The algorithm to exercise.
246 *
247 * \retval 0 The key failed the smoke tests.
248 * \retval 1 The key passed the smoke tests.
249 */
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100250int mbedtls_test_psa_exercise_key(mbedtls_svc_key_id_t key,
251 psa_key_usage_t usage,
252 psa_algorithm_t alg);
Gilles Peskinee78b0022021-02-13 00:41:11 +0100253
Gilles Peskine1b6c09a2023-01-11 14:52:35 +0100254psa_key_usage_t mbedtls_test_psa_usage_to_exercise(psa_key_type_t type,
255 psa_algorithm_t alg);
Gilles Peskine66e7b902021-02-12 23:40:58 +0100256
257#endif /* PSA_EXERCISE_KEY_H */