blob: 57eae58911f7e942cb465bf55c3ce93a0d65ee14 [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
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_EXERCISE_KEY_H
22#define PSA_EXERCISE_KEY_H
23
24#include "test/helpers.h"
25#include "test/psa_crypto_helpers.h"
26
27#include <psa/crypto.h>
28
Gilles Peskinee50b5782021-02-14 01:13:55 +010029/** \def KNOWN_SUPPORTED_HASH_ALG
30 *
31 * A hash algorithm that is known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010032 *
33 * This is used in some smoke tests.
34 */
35#if defined(PSA_WANT_ALG_MD2)
36#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD2
37#elif defined(PSA_WANT_ALG_MD4)
38#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD4
39#elif defined(PSA_WANT_ALG_MD5)
40#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_MD5
41/* MBEDTLS_RIPEMD160_C omitted. This is necessary for the sake of
42 * exercise_signature_key() because Mbed TLS doesn't support RIPEMD160
43 * in RSA PKCS#1v1.5 signatures. A RIPEMD160-only configuration would be
44 * implausible anyway. */
45#elif defined(PSA_WANT_ALG_SHA_1)
46#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_1
47#elif defined(PSA_WANT_ALG_SHA_256)
48#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_256
49#elif defined(PSA_WANT_ALG_SHA_384)
50#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_384
51#elif defined(PSA_WANT_ALG_SHA_512)
52#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA_512
53#elif defined(PSA_WANT_ALG_SHA3_256)
54#define KNOWN_SUPPORTED_HASH_ALG PSA_ALG_SHA3_256
55#else
56#undef KNOWN_SUPPORTED_HASH_ALG
57#endif
58
Gilles Peskinee50b5782021-02-14 01:13:55 +010059/** \def KNOWN_SUPPORTED_BLOCK_CIPHER
60 *
61 * A block cipher that is known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010062 *
63 * For simplicity's sake, stick to block ciphers with 16-byte blocks.
64 */
65#if defined(MBEDTLS_AES_C)
66#define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_AES
67#elif defined(MBEDTLS_ARIA_C)
68#define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_ARIA
69#elif defined(MBEDTLS_CAMELLIA_C)
70#define KNOWN_SUPPORTED_BLOCK_CIPHER PSA_KEY_TYPE_CAMELLIA
71#undef KNOWN_SUPPORTED_BLOCK_CIPHER
72#endif
73
Gilles Peskinee50b5782021-02-14 01:13:55 +010074/** \def KNOWN_SUPPORTED_MAC_ALG
75 *
76 * A MAC mode that is known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010077 *
78 * It must either be HMAC with #KNOWN_SUPPORTED_HASH_ALG or
79 * a block cipher-based MAC with #KNOWN_SUPPORTED_BLOCK_CIPHER.
80 *
81 * This is used in some smoke tests.
82 */
83#if defined(KNOWN_SUPPORTED_HASH_ALG) && defined(PSA_WANT_ALG_HMAC)
84#define KNOWN_SUPPORTED_MAC_ALG ( PSA_ALG_HMAC( KNOWN_SUPPORTED_HASH_ALG ) )
85#define KNOWN_SUPPORTED_MAC_KEY_TYPE PSA_KEY_TYPE_HMAC
86#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CMAC_C)
87#define KNOWN_SUPPORTED_MAC_ALG PSA_ALG_CMAC
88#define KNOWN_SUPPORTED_MAC_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER
89#else
90#undef KNOWN_SUPPORTED_MAC_ALG
91#undef KNOWN_SUPPORTED_MAC_KEY_TYPE
92#endif
93
Gilles Peskinee50b5782021-02-14 01:13:55 +010094/** \def KNOWN_SUPPORTED_BLOCK_CIPHER_ALG
95 *
96 * A cipher algorithm and key type that are known to be supported.
Gilles Peskinee78b0022021-02-13 00:41:11 +010097 *
98 * This is used in some smoke tests.
99 */
100#if defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CTR)
101#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CTR
102#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CBC)
103#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CBC_NO_PADDING
104#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_CFB)
105#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_CFB
106#elif defined(KNOWN_SUPPORTED_BLOCK_CIPHER) && defined(MBEDTLS_CIPHER_MODE_OFB)
107#define KNOWN_SUPPORTED_BLOCK_CIPHER_ALG PSA_ALG_OFB
108#else
109#undef KNOWN_SUPPORTED_BLOCK_CIPHER_ALG
110#endif
111#if defined(KNOWN_SUPPORTED_BLOCK_CIPHER_ALG)
112#define KNOWN_SUPPORTED_CIPHER_ALG KNOWN_SUPPORTED_BLOCK_CIPHER_ALG
113#define KNOWN_SUPPORTED_CIPHER_KEY_TYPE KNOWN_SUPPORTED_BLOCK_CIPHER
114#elif defined(MBEDTLS_RC4_C)
115#define KNOWN_SUPPORTED_CIPHER_ALG PSA_ALG_RC4
116#define KNOWN_SUPPORTED_CIPHER_KEY_TYPE PSA_KEY_TYPE_RC4
117#else
118#undef KNOWN_SUPPORTED_CIPHER_ALG
119#undef KNOWN_SUPPORTED_CIPHER_KEY_TYPE
120#endif
121
Gilles Peskinee50b5782021-02-14 01:13:55 +0100122/** Convenience function to set up a key derivation.
123 *
124 * In case of failure, mark the current test case as failed.
125 *
126 * The inputs \p input1 and \p input2 are, in order:
127 * - HKDF: salt, info.
128 * - TKS 1.2 PRF, TLS 1.2 PSK-to-MS: seed, label.
129 *
130 * \param operation The operation object to use.
131 * It must be in the initialized state.
132 * \param key The key to use.
133 * \param alg The algorithm to use.
134 * \param input1 The first input to pass.
135 * \param input1_length The length of \p input1 in bytes.
Gilles Peskine5a7702e2021-02-23 13:40:19 +0100136 * \param input2 The first input to pass.
137 * \param input2_length The length of \p input2 in bytes.
Gilles Peskinee50b5782021-02-14 01:13:55 +0100138 * \param capacity The capacity to set.
139 *
140 * \return \c 1 on success, \c 0 on failure.
141 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100142int mbedtls_test_psa_setup_key_derivation_wrap(
143 psa_key_derivation_operation_t* operation,
144 mbedtls_svc_key_id_t key,
145 psa_algorithm_t alg,
Gilles Peskine5c2665b2021-02-14 01:22:56 +0100146 const unsigned char* input1, size_t input1_length,
147 const unsigned char* input2, size_t input2_length,
Gilles Peskinee78b0022021-02-13 00:41:11 +0100148 size_t capacity );
149
Gilles Peskinee50b5782021-02-14 01:13:55 +0100150/** Perform a key agreement using the given key pair against its public key
151 * using psa_raw_key_agreement().
152 *
153 * The result is discarded. The purpose of this function is to smoke-test a key.
154 *
155 * In case of failure, mark the current test case as failed.
156 *
157 * \param alg A key agreement algorithm compatible with \p key.
158 * \param key A key that allows key agreement with \p alg.
159 *
160 * \return \c 1 on success, \c 0 on failure.
161 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100162psa_status_t mbedtls_test_psa_raw_key_agreement_with_self(
163 psa_algorithm_t alg,
164 mbedtls_svc_key_id_t key );
165
Gilles Peskinee50b5782021-02-14 01:13:55 +0100166/** Perform a key agreement using the given key pair against its public key
167 * using psa_key_derivation_raw_key().
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 *
Gilles Peskine5a7702e2021-02-23 13:40:19 +0100173 * \param operation An operation that has been set up for a key
174 * agreement algorithm that is compatible with
175 * \p key.
176 * \param key A key pair object that is suitable for a key
177 * agreement with \p operation.
Gilles Peskinee50b5782021-02-14 01:13:55 +0100178 *
179 * \return \c 1 on success, \c 0 on failure.
180 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100181psa_status_t mbedtls_test_psa_key_agreement_with_self(
182 psa_key_derivation_operation_t *operation,
183 mbedtls_svc_key_id_t key );
184
Gilles Peskinee50b5782021-02-14 01:13:55 +0100185/** Perform sanity checks on the given key representation.
186 *
187 * If any of the checks fail, mark the current test case as failed.
188 *
189 * The checks depend on the key type.
190 * - All types: check the export size against maximum-size macros.
191 * - DES: parity bits.
192 * - RSA: check the ASN.1 structure and the size and parity of the integers.
193 * - ECC private or public key: exact representation length.
194 * - Montgomery public key: first byte.
195 *
196 * \param type The key type.
Gilles Peskine5a7702e2021-02-23 13:40:19 +0100197 * \param bits The key size in bits.
198 * \param exported A buffer containing the key representation.
199 * \param exported_length The length of \p exported in bytes.
Gilles Peskinee50b5782021-02-14 01:13:55 +0100200 *
201 * \return \c 1 if all checks passed, \c 0 on failure.
202 */
Gilles Peskinee78b0022021-02-13 00:41:11 +0100203int mbedtls_test_psa_exported_key_sanity_check(
204 psa_key_type_t type, size_t bits,
Gilles Peskine5c2665b2021-02-14 01:22:56 +0100205 const uint8_t *exported, size_t exported_length );
Gilles Peskinee78b0022021-02-13 00:41:11 +0100206
207/** Do smoke tests on a key.
208 *
209 * Perform one of each operation indicated by \p alg (decrypt/encrypt,
210 * sign/verify, or derivation) that is permitted according to \p usage.
211 * \p usage and \p alg should correspond to the expected policy on the
212 * key.
213 *
214 * Export the key if permitted by \p usage, and check that the output
215 * looks sensible. If \p usage forbids export, check that
216 * \p psa_export_key correctly rejects the attempt. If the key is
217 * asymmetric, also check \p psa_export_public_key.
218 *
219 * If the key fails the tests, this function calls the test framework's
220 * `mbedtls_test_fail` function and returns false. Otherwise this function
221 * returns true. Therefore it should be used as follows:
222 * ```
223 * if( ! exercise_key( ... ) ) goto exit;
224 * ```
225 *
226 * \param key The key to exercise. It should be capable of performing
227 * \p alg.
228 * \param usage The usage flags to assume.
229 * \param alg The algorithm to exercise.
230 *
231 * \retval 0 The key failed the smoke tests.
232 * \retval 1 The key passed the smoke tests.
233 */
234int mbedtls_test_psa_exercise_key( mbedtls_svc_key_id_t key,
235 psa_key_usage_t usage,
236 psa_algorithm_t alg );
237
238psa_key_usage_t mbedtls_test_psa_usage_to_exercise( psa_key_type_t type,
239 psa_algorithm_t alg );
Gilles Peskine66e7b902021-02-12 23:40:58 +0100240
241#endif /* PSA_EXERCISE_KEY_H */