blob: 8cf7e3a3f2fdd2e2f71ecc4fda37effbaf80db9a [file] [log] [blame]
Gilles Peskinee59236f2018-01-27 23:32:46 +01001/**
2 * \file psa/crypto.h
3 * \brief Platform Security Architecture cryptography module
4 */
5
6#ifndef PSA_CRYPTO_H
7#define PSA_CRYPTO_H
8
9#include "crypto_platform.h"
10
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010011#include <stddef.h>
12
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010013#ifdef __DOXYGEN_ONLY__
14/** \defgroup platform Implementation-specific definitions
15 * @{
16 */
17
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010018/** \brief Key slot number.
19 *
20 * This type represents key slots. It must be an unsigned integral
Gilles Peskine308b91d2018-02-08 09:47:44 +010021 * type. The choice of type is implementation-dependent.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010022 * 0 is not a valid key slot number. The meaning of other values is
23 * implementation dependent.
24 *
25 * At any given point in time, each key slot either contains a
26 * cryptographic object, or is empty. Key slots are persistent:
27 * once set, the cryptographic object remains in the key slot until
28 * explicitly destroyed.
29 */
30typedef _unsigned_integral_type_ psa_key_slot_t;
31
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010032/**@}*/
33#endif
34
Gilles Peskinee59236f2018-01-27 23:32:46 +010035#ifdef __cplusplus
36extern "C" {
37#endif
38
39/** \defgroup basic Basic definitions
40 * @{
41 */
42
43/**
44 * \brief Function return status.
45 *
46 * Zero indicates success, anything else indicates an error.
47 */
48typedef enum {
49 /** The action was completed successfully. */
50 PSA_SUCCESS = 0,
51 /** The requested operation or a parameter is not supported
52 by this implementation. */
53 PSA_ERROR_NOT_SUPPORTED,
54 /** The requested action is denied by a policy. */
55 PSA_ERROR_NOT_PERMITTED,
56 /** An output buffer is too small. */
57 PSA_ERROR_BUFFER_TOO_SMALL,
58 /** A slot is occupied, but must be empty to carry out the
59 requested action. */
60 PSA_ERROR_OCCUPIED_SLOT,
61 /** A slot is empty, but must be occupied to carry out the
62 requested action. */
63 PSA_ERROR_EMPTY_SLOT,
64 /** The requested action cannot be performed in the current state. */
65 PSA_ERROR_BAD_STATE,
66 /** The parameters passed to the function are invalid. */
67 PSA_ERROR_INVALID_ARGUMENT,
68 /** There is not enough runtime memory. */
69 PSA_ERROR_INSUFFICIENT_MEMORY,
70 /** There is not enough persistent storage. */
71 PSA_ERROR_INSUFFICIENT_STORAGE,
72 /** There was a communication failure inside the implementation. */
73 PSA_ERROR_COMMUNICATION_FAILURE,
Gilles Peskinea5905292018-02-07 20:59:33 +010074 /** There was a storage failure that may have led to data loss. */
75 PSA_ERROR_STORAGE_FAILURE,
Gilles Peskinee59236f2018-01-27 23:32:46 +010076 /** A hardware failure was detected. */
77 PSA_ERROR_HARDWARE_FAILURE,
78 /** A tampering attempt was detected. */
79 PSA_ERROR_TAMPERING_DETECTED,
80 /** There is not enough entropy to generate random data needed
81 for the requested action. */
82 PSA_ERROR_INSUFFICIENT_ENTROPY,
Gilles Peskinea5905292018-02-07 20:59:33 +010083 /** The signature, MAC or hash is incorrect. */
Gilles Peskinee59236f2018-01-27 23:32:46 +010084 PSA_ERROR_INVALID_SIGNATURE,
Gilles Peskinea5905292018-02-07 20:59:33 +010085 /** The decrypted padding is incorrect. */
86 PSA_ERROR_INVALID_PADDING,
Gilles Peskinee59236f2018-01-27 23:32:46 +010087 /** An error occurred that does not correspond to any defined
88 failure cause. */
89 PSA_ERROR_UNKNOWN_ERROR,
90} psa_status_t;
91
92/**
93 * \brief Library initialization.
94 *
95 * Applications must call this function before calling any other
96 * function in this module.
97 *
98 * Applications may call this function more than once. Once a call
99 * succeeds, subsequent calls are guaranteed to succeed.
100 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100101 * \retval PSA_SUCCESS
102 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
103 * \retval PSA_ERROR_COMMUNICATION_FAILURE
104 * \retval PSA_ERROR_HARDWARE_FAILURE
105 * \retval PSA_ERROR_TAMPERING_DETECTED
106 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinee59236f2018-01-27 23:32:46 +0100107 */
108psa_status_t psa_crypto_init(void);
109
Gilles Peskine0189e752018-02-03 23:57:22 +0100110#define BITS_TO_BYTES(bits) (((bits) + 7) / 8)
111#define BYTES_TO_BITS(bytes) ((bytes) * 8)
112
Gilles Peskinee59236f2018-01-27 23:32:46 +0100113/**@}*/
114
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100115/** \defgroup crypto_types Key and algorithm types
116 * @{
117 */
118
Gilles Peskine308b91d2018-02-08 09:47:44 +0100119/** \brief Encoding of a key type.
120 */
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100121typedef uint32_t psa_key_type_t;
122
Gilles Peskine98f0a242018-02-06 18:57:29 +0100123#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000)
124#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100125
Gilles Peskine98f0a242018-02-06 18:57:29 +0100126#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000)
127#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x02000000)
128#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x04000000)
129#define PSA_KEY_TYPE_CATEGORY_ASYMMETRIC ((psa_key_type_t)0x06000000)
130#define PSA_KEY_TYPE_PAIR_FLAG ((psa_key_type_t)0x01000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100131
Gilles Peskine98f0a242018-02-06 18:57:29 +0100132#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001)
133#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x04000001)
134#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x04000002)
135#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003)
136#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x04000004)
137
Gilles Peskine308b91d2018-02-08 09:47:44 +0100138/** RSA public key. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100139#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x06010000)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100140/** RSA key pair (private and public key). */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100141#define PSA_KEY_TYPE_RSA_KEYPAIR ((psa_key_type_t)0x07010000)
142#define PSA_KEY_TYPE_ECC_BASE ((psa_key_type_t)0x06030000)
143#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
144
145#define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100146 (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100147#define PSA_KEY_TYPE_IS_RAW_BYTES(type) \
148 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_RAW_DATA || \
149 ((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100150#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \
151 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_ASYMMETRIC)
152#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \
153 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG) == \
154 PSA_KEY_TYPE_CATEGORY_ASYMMETRIC))
155#define PSA_KEY_TYPE_IS_KEYPAIR(type) \
156 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG)) == \
157 (PSA_KEY_TYPE_CATEGORY_ASYMMETRIC | PSA_KEY_TYPE_PAIR_FLAG))
Gilles Peskine0189e752018-02-03 23:57:22 +0100158#define PSA_KEY_TYPE_IS_RSA(type) \
Gilles Peskine98f0a242018-02-06 18:57:29 +0100159 (((type) & ~PSA_KEY_TYPE_PAIR_FLAG) == PSA_KEY_TYPE_RSA_PUBLIC_KEY)
Gilles Peskinec66ea6a2018-02-03 22:43:28 +0100160#define PSA_KEY_TYPE_IS_ECC(type) \
Gilles Peskine98f0a242018-02-06 18:57:29 +0100161 (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_BASE)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100162
Gilles Peskine8c9def32018-02-08 10:02:12 +0100163#define PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) \
164 ( \
165 (type) == PSA_KEY_TYPE_AES ? 16 : \
166 (type) == PSA_KEY_TYPE_DES ? 8 : \
167 (type) == PSA_KEY_TYPE_CAMELLIA ? 16 : \
168 0)
169
Gilles Peskine308b91d2018-02-08 09:47:44 +0100170/** \brief Encoding of a cryptographic algorithm.
171 *
172 * For algorithms that can be applied to multiple key types, this type
173 * does not encode the key type. For example, for symmetric ciphers
174 * based on a block cipher, #psa_algorithm_t encodes the block cipher
175 * mode and the padding mode while the block cipher itself is encoded
176 * via #psa_key_type_t.
177 */
Gilles Peskine20035e32018-02-03 22:44:14 +0100178typedef uint32_t psa_algorithm_t;
179
Gilles Peskine98f0a242018-02-06 18:57:29 +0100180#define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t)0x80000000)
181#define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t)0x7f000000)
182#define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t)0x01000000)
183#define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x02000000)
184#define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000)
185#define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t)0x06000000)
186#define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t)0x10000000)
187#define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t)0x12000000)
188#define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t)0x22000000)
189#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x30000000)
Gilles Peskine20035e32018-02-03 22:44:14 +0100190
Gilles Peskine98f0a242018-02-06 18:57:29 +0100191#define PSA_ALG_IS_VENDOR_DEFINED(alg) \
192 (((alg) & PSA_ALG_VENDOR_FLAG) != 0)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100193/** Whether the specified algorithm is a hash algorithm.
194 *
195 * \param alg An algorithm identifier (\c PSA_ALG_XXX value)
196 *
197 * \return 1 if \c alg is a hash algorithm, 0 otherwise.
198 * This macro may return either 0 or 1 if \c alg is not a valid
199 * algorithm identifier. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100200#define PSA_ALG_IS_HASH(alg) \
201 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
202#define PSA_ALG_IS_MAC(alg) \
203 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)
204#define PSA_ALG_IS_CIPHER(alg) \
205 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)
206#define PSA_ALG_IS_AEAD(alg) \
207 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD)
208#define PSA_ALG_IS_SIGN(alg) \
209 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)
210#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
211 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)
212#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
213 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)
214#define PSA_ALG_IS_KEY_DERIVATION(alg) \
215 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
216
217#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)
218#define PSA_ALG_MD2 ((psa_algorithm_t)0x01000001)
219#define PSA_ALG_MD4 ((psa_algorithm_t)0x01000002)
220#define PSA_ALG_MD5 ((psa_algorithm_t)0x01000003)
221#define PSA_ALG_SHA_256_128 ((psa_algorithm_t)0x01000004)
222#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x01000005)
223#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x01000006)
224#define PSA_ALG_SHA_256_160 ((psa_algorithm_t)0x01000007)
225#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x01000008)
226#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x01000009)
227#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0100000a)
228#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0100000b)
229#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0100000c)
230#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0100000d)
231#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x01000010)
232#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x01000011)
233#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x01000012)
234#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
235
Gilles Peskine8c9def32018-02-08 10:02:12 +0100236#define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100237#define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000)
238#define PSA_ALG_HMAC(hash_alg) \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100239 (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
240#define PSA_ALG_HMAC_HASH(hmac_alg) \
241 (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK))
242#define PSA_ALG_IS_HMAC(alg) \
243 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
244 PSA_ALG_HMAC_BASE)
245#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000)
246#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001)
247#define PSA_ALG_CMAC ((psa_algorithm_t)0x02c00002)
248#define PSA_ALG_GMAC ((psa_algorithm_t)0x02c00003)
249#define PSA_ALG_IS_CIPHER_MAC(alg) \
250 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
251 PSA_ALG_CIPHER_MAC_BASE)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100252
Gilles Peskine8c9def32018-02-08 10:02:12 +0100253#define PSA_ALG_CIPHER_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
254#define PSA_ALG_BLOCK_CIPHER_BASE ((psa_algorithm_t)0x04000001)
255#define PSA_ALG_BLOCK_CIPHER_MODE_MASK ((psa_algorithm_t)0x000000ff)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100256#define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x007f0000)
257#define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100258#define PSA_ALG_IS_BLOCK_CIPHER(alg) \
259 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \
260 PSA_ALG_BLOCK_CIPHER_BASE)
261
Gilles Peskine98f0a242018-02-06 18:57:29 +0100262#define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100263#define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002)
264#define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003)
265#define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100266#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000)
267#define PSA_ALG_CTR ((psa_algorithm_t)0x04800001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100268#define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100269
Gilles Peskine8c9def32018-02-08 10:02:12 +0100270#define PSA_ALG_CCM ((psa_algorithm_t)0x06000001)
271#define PSA_ALG_GCM ((psa_algorithm_t)0x06000002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100272
273#define PSA_ALG_RSA_PKCS1V15_RAW ((psa_algorithm_t)0x10010000)
274#define PSA_ALG_RSA_PSS_MGF1 ((psa_algorithm_t)0x10020000)
275#define PSA_ALG_RSA_OAEP ((psa_algorithm_t)0x12020000)
276#define PSA_ALG_RSA_PKCS1V15(hash_alg) \
277 (PSA_ALG_RSA_PKCS1V15_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
278#define PSA_ALG_IS_RSA_PKCS1V15(alg) \
Gilles Peskine20035e32018-02-03 22:44:14 +0100279 (((alg) & 0x7fffff00) == PSA_ALG_RSA_PKCS1V15_RAW)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100280#define PSA_ALG_RSA_GET_HASH(alg) \
281 (((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100282
283/**@}*/
284
285/** \defgroup key_management Key management
286 * @{
287 */
288
289/**
290 * \brief Import a key in binary format.
291 *
292 * This function supports any output from psa_export_key().
293 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100294 * \param key Slot where the key will be stored. This must be a
295 * valid slot for a key of the chosen type. It must
296 * be unoccupied.
297 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
298 * \param data Buffer containing the key data.
299 * \param data_length Size of the \c data buffer in bytes.
300 *
301 * \retval PSA_SUCCESS
302 * Success.
303 * \retval PSA_ERROR_NOT_SUPPORTED
304 * The key type or key size is not supported.
305 * \retval PSA_ERROR_INVALID_ARGUMENT
306 * The key slot is invalid,
307 * or the key data is not correctly formatted.
308 * \retval PSA_ERROR_OCCUPIED_SLOT
309 There is already a key in the specified slot.
310 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
311 * \retval PSA_ERROR_COMMUNICATION_FAILURE
312 * \retval PSA_ERROR_HARDWARE_FAILURE
313 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100314 */
315psa_status_t psa_import_key(psa_key_slot_t key,
316 psa_key_type_t type,
317 const uint8_t *data,
318 size_t data_length);
319
320/**
321 * \brief Destroy a key.
322 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100323 * \retval PSA_SUCCESS
324 * \retval PSA_ERROR_EMPTY_SLOT
325 * \retval PSA_ERROR_COMMUNICATION_FAILURE
326 * \retval PSA_ERROR_HARDWARE_FAILURE
327 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100328 */
329psa_status_t psa_destroy_key(psa_key_slot_t key);
330
331/**
332 * \brief Get basic metadata about a key.
333 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100334 * \param key Slot whose content is queried. This must
335 * be an occupied key slot.
336 * \param type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
337 * This may be a null pointer, in which case the key type
338 * is not written.
339 * \param bits On success, the key size in bits.
340 * This may be a null pointer, in which case the key type
341 * is not written.
342 *
343 * \retval PSA_SUCCESS
344 * \retval PSA_ERROR_EMPTY_SLOT
345 * \retval PSA_ERROR_COMMUNICATION_FAILURE
346 * \retval PSA_ERROR_HARDWARE_FAILURE
347 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100348 */
349psa_status_t psa_get_key_information(psa_key_slot_t key,
350 psa_key_type_t *type,
351 size_t *bits);
352
353/**
354 * \brief Export a key in binary format.
355 *
356 * The output of this function can be passed to psa_import_key() to
357 * create an equivalent object.
358 *
359 * If a key is created with psa_import_key() and then exported with
360 * this function, it is not guaranteed that the resulting data is
361 * identical: the implementation may choose a different representation
362 * of the same key.
363 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100364 * For standard key types, the output format is as follows:
365 *
366 * - For symmetric keys (including MAC keys), the format is the
367 * raw bytes of the key.
368 * - For DES, the key data consists of 8 bytes. The parity bits must be
369 * correct.
370 * - For Triple-DES, the format is the concatenation of the
371 * two or three DES keys.
372 * - For RSA key pairs keys (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
373 * is the non-encrypted DER representation defined by PKCS\#8 (RFC 5208)
374 * as PrivateKeyInfo.
375 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
376 * is the DER representation defined by X.509.
377 *
378 * \param key Slot whose content is to be exported. This must
379 * be an occupied key slot.
380 * \param data Buffer where the key data is to be written.
381 * \param data_size Size of the \c data buffer in bytes.
382 * \param data_length On success, the number of bytes
383 * that make up the key data.
384 *
385 * \retval PSA_SUCCESS
386 * \retval PSA_ERROR_EMPTY_SLOT
387 * \retval PSA_ERROR_COMMUNICATION_FAILURE
388 * \retval PSA_ERROR_HARDWARE_FAILURE
389 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100390 */
391psa_status_t psa_export_key(psa_key_slot_t key,
392 uint8_t *data,
393 size_t data_size,
394 size_t *data_length);
395
Gilles Peskine20035e32018-02-03 22:44:14 +0100396
397/**@}*/
398
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100399/** \defgroup hash Message digests
400 * @{
401 */
402
Gilles Peskine308b91d2018-02-08 09:47:44 +0100403/** The type of the state data structure for multipart hash operations.
404 *
405 * This is an implementation-define \c struct. Applications should not
406 * make any assumptions about the content of this structure except
407 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100408typedef struct psa_hash_operation_s psa_hash_operation_t;
409
Gilles Peskine308b91d2018-02-08 09:47:44 +0100410/** The size of the output of psa_hash_finish(), in bytes.
411 *
412 * This is also the hash size that psa_hash_verify() expects.
413 *
414 * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
415 * #PSA_ALG_IS_HASH(alg) is true).
416 *
417 * \return The hash size for the specified hash algorithm.
418 * If the hash algorithm is not recognized, return 0.
419 * An implementation may return either 0 or the correct size
420 * for a hash algorithm that it recognizes, but does not support.
421 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100422#define PSA_HASH_FINAL_SIZE(alg) \
423 ( \
424 (alg) == PSA_ALG_MD2 ? 16 : \
425 (alg) == PSA_ALG_MD4 ? 16 : \
426 (alg) == PSA_ALG_MD5 ? 16 : \
427 (alg) == PSA_ALG_SHA_256_128 ? 16 : \
428 (alg) == PSA_ALG_RIPEMD160 ? 20 : \
429 (alg) == PSA_ALG_SHA_1 ? 20 : \
430 (alg) == PSA_ALG_SHA_256_160 ? 20 : \
431 (alg) == PSA_ALG_SHA_224 ? 28 : \
432 (alg) == PSA_ALG_SHA_256 ? 32 : \
433 (alg) == PSA_ALG_SHA_384 ? 48 : \
434 (alg) == PSA_ALG_SHA_512 ? 64 : \
435 (alg) == PSA_ALG_SHA_512_224 ? 28 : \
436 (alg) == PSA_ALG_SHA_512_256 ? 32 : \
437 (alg) == PSA_ALG_SHA3_224 ? 28 : \
438 (alg) == PSA_ALG_SHA3_256 ? 32 : \
439 (alg) == PSA_ALG_SHA3_384 ? 48 : \
440 (alg) == PSA_ALG_SHA3_512 ? 64 : \
441 0)
442
Gilles Peskine308b91d2018-02-08 09:47:44 +0100443/** Start a multipart hash operation.
444 *
445 * The sequence of operations to calculate a hash (message digest)
446 * is as follows:
447 * -# Allocate an operation object which will be passed to all the functions
448 * listed here.
449 * -# Call psa_hash_start() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100450 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100451 * of the message each time. The hash that is calculated is the hash
452 * of the concatenation of these messages in order.
453 * -# To calculate the hash, call psa_hash_finish().
454 * To compare the hash with an expected value, call psa_hash_verify().
455 *
456 * The application may call psa_hash_abort() at any time after the operation
457 * has been initialized with psa_hash_start().
458 *
459 * After a successful call to psa_hash_start(), the application must
460 * eventually destroy the operation through one of the following means:
461 * - A failed call to psa_hash_update().
462 * - A call to psa_hash_final(), psa_hash_verify() or psa_hash_abort().
463 *
464 * \param operation
465 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
466 * such that #PSA_ALG_IS_HASH(alg) is true).
467 *
468 * \retval PSA_SUCCESS
469 * Success.
470 * \retval PSA_ERROR_NOT_SUPPORTED
471 * \c alg is not supported or is not a hash algorithm.
472 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
473 * \retval PSA_ERROR_COMMUNICATION_FAILURE
474 * \retval PSA_ERROR_HARDWARE_FAILURE
475 * \retval PSA_ERROR_TAMPERING_DETECTED
476 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100477psa_status_t psa_hash_start(psa_hash_operation_t *operation,
478 psa_algorithm_t alg);
479
Gilles Peskine308b91d2018-02-08 09:47:44 +0100480/** Add a message fragment to a multipart hash operation.
481 *
482 * The application must call psa_hash_start() before calling this function.
483 *
484 * If this function returns an error status, the operation becomes inactive.
485 *
486 * \param operation Active hash operation.
487 * \param input Buffer containing the message fragment to hash.
488 * \param input_length Size of the \c input buffer in bytes.
489 *
490 * \retval PSA_SUCCESS
491 * Success.
492 * \retval PSA_ERROR_BAD_STATE
493 * The operation state is not valid (not started, or already completed).
494 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
495 * \retval PSA_ERROR_COMMUNICATION_FAILURE
496 * \retval PSA_ERROR_HARDWARE_FAILURE
497 * \retval PSA_ERROR_TAMPERING_DETECTED
498 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100499psa_status_t psa_hash_update(psa_hash_operation_t *operation,
500 const uint8_t *input,
501 size_t input_length);
502
Gilles Peskine308b91d2018-02-08 09:47:44 +0100503/** Finish the calculation of the hash of a message.
504 *
505 * The application must call psa_hash_start() before calling this function.
506 * This function calculates the hash of the message formed by concatenating
507 * the inputs passed to preceding calls to psa_hash_update().
508 *
509 * When this function returns, the operation becomes inactive.
510 *
511 * \warning Applications should not call this function if they expect
512 * a specific value for the hash. Call psa_hash_verify() instead.
513 * Beware that comparing integrity or authenticity data such as
514 * hash values with a function such as \c memcmp is risky
515 * because the time taken by the comparison may leak information
516 * about the hashed data which could allow an attacker to guess
517 * a valid hash and thereby bypass security controls.
518 *
519 * \param operation Active hash operation.
520 * \param hash Buffer where the hash is to be written.
521 * \param hash_size Size of the \c hash buffer in bytes.
522 * \param hash_length On success, the number of bytes
523 * that make up the hash value. This is always
524 * #PSA_HASH_FINAL_SIZE(alg) where \c alg is the
525 * hash algorithm that is calculated.
526 *
527 * \retval PSA_SUCCESS
528 * Success.
529 * \retval PSA_ERROR_BAD_STATE
530 * The operation state is not valid (not started, or already completed).
531 * \retval PSA_ERROR_BUFFER_TOO_SMALL
532 * The size of the \c hash buffer is too small. You can determine a
533 * sufficient buffer size by calling #PSA_HASH_FINAL_SIZE(alg)
534 * where \c alg is the hash algorithm that is calculated.
535 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
536 * \retval PSA_ERROR_COMMUNICATION_FAILURE
537 * \retval PSA_ERROR_HARDWARE_FAILURE
538 * \retval PSA_ERROR_TAMPERING_DETECTED
539 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100540psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
541 uint8_t *hash,
542 size_t hash_size,
543 size_t *hash_length);
544
Gilles Peskine308b91d2018-02-08 09:47:44 +0100545/** Finish the calculation of the hash of a message and compare it with
546 * an expected value.
547 *
548 * The application must call psa_hash_start() before calling this function.
549 * This function calculates the hash of the message formed by concatenating
550 * the inputs passed to preceding calls to psa_hash_update(). It then
551 * compares the calculated hash with the expected hash passed as a
552 * parameter to this function.
553 *
554 * When this function returns, the operation becomes inactive.
555 *
556 * \note Applications shall make the best effort to ensure that the
557 * comparison between the actual hash and the expected hash is performed
558 * in constant time.
559 *
560 * \param operation Active hash operation.
561 * \param hash Buffer containing the expected hash value.
562 * \param hash_length Size of the \c hash buffer in bytes.
563 *
564 * \retval PSA_SUCCESS
565 * The expected hash is identical to the actual hash of the message.
566 * \retval PSA_ERROR_INVALID_SIGNATURE
567 * The hash of the message was calculated successfully, but it
568 * differs from the expected hash.
569 * \retval PSA_ERROR_BAD_STATE
570 * The operation state is not valid (not started, or already completed).
571 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
572 * \retval PSA_ERROR_COMMUNICATION_FAILURE
573 * \retval PSA_ERROR_HARDWARE_FAILURE
574 * \retval PSA_ERROR_TAMPERING_DETECTED
575 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100576psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
577 const uint8_t *hash,
578 size_t hash_length);
579
Gilles Peskine308b91d2018-02-08 09:47:44 +0100580/** Abort a hash operation.
581 *
582 * This function may be called at any time after psa_hash_start().
583 * Aborting an operation frees all associated resources except for the
584 * \c operation structure itself.
585 *
586 * Implementation should strive to be robust and handle inactive hash
587 * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However,
588 * application writers should beware that uninitialized memory may happen
589 * to be indistinguishable from an active hash operation, and the behavior
590 * of psa_hash_abort() is undefined in this case.
591 *
592 * \param operation Active hash operation.
593 *
594 * \retval PSA_SUCCESS
595 * \retval PSA_ERROR_BAD_STATE
596 * \c operation is not an active hash operation.
597 * \retval PSA_ERROR_COMMUNICATION_FAILURE
598 * \retval PSA_ERROR_HARDWARE_FAILURE
599 * \retval PSA_ERROR_TAMPERING_DETECTED
600 */
601psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100602
603/**@}*/
604
Gilles Peskine8c9def32018-02-08 10:02:12 +0100605/** \defgroup MAC Message authentication codes
606 * @{
607 */
608
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100609/** The type of the state data structure for multipart MAC operations.
610 *
611 * This is an implementation-define \c struct. Applications should not
612 * make any assumptions about the content of this structure except
613 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100614typedef struct psa_mac_operation_s psa_mac_operation_t;
615
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100616/** The size of the output of psa_mac_finish(), in bytes.
617 *
618 * This is also the MAC size that psa_mac_verify() expects.
619 *
620 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
621 * #PSA_ALG_IS_MAC(alg) is true).
622 *
623 * \return The MAC size for the specified algorithm.
624 * If the MAC algorithm is not recognized, return 0.
625 * An implementation may return either 0 or the correct size
626 * for a MAC algorithm that it recognizes, but does not support.
627 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100628#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
629 (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_FINAL_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
630 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
631 0)
632
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100633/** Start a multipart MAC operation.
634 *
635 * The sequence of operations to calculate a MAC (message authentication code)
636 * is as follows:
637 * -# Allocate an operation object which will be passed to all the functions
638 * listed here.
639 * -# Call psa_mac_start() to specify the algorithm and key.
640 * The key remains associated with the operation even if the content
641 * of the key slot changes.
642 * -# Call psa_mac_update() zero, one or more times, passing a fragment
643 * of the message each time. The MAC that is calculated is the MAC
644 * of the concatenation of these messages in order.
645 * -# To calculate the MAC, call psa_mac_finish().
646 * To compare the MAC with an expected value, call psa_mac_verify().
647 *
648 * The application may call psa_mac_abort() at any time after the operation
649 * has been initialized with psa_mac_start().
650 *
651 * After a successful call to psa_mac_start(), the application must
652 * eventually destroy the operation through one of the following means:
653 * - A failed call to psa_mac_update().
654 * - A call to psa_mac_final(), psa_mac_verify() or psa_mac_abort().
655 *
656 * \param operation
657 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
658 * such that #PSA_ALG_IS_MAC(alg) is true).
659 *
660 * \retval PSA_SUCCESS
661 * Success.
662 * \retval PSA_ERROR_EMPTY_SLOT
663 * \retval PSA_ERROR_INVALID_ARGUMENT
664 * \c key is not compatible with \c alg.
665 * \retval PSA_ERROR_NOT_SUPPORTED
666 * \c alg is not supported or is not a MAC algorithm.
667 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
668 * \retval PSA_ERROR_COMMUNICATION_FAILURE
669 * \retval PSA_ERROR_HARDWARE_FAILURE
670 * \retval PSA_ERROR_TAMPERING_DETECTED
671 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100672psa_status_t psa_mac_start(psa_mac_operation_t *operation,
673 psa_key_slot_t key,
674 psa_algorithm_t alg);
675
676psa_status_t psa_mac_update(psa_mac_operation_t *operation,
677 const uint8_t *input,
678 size_t input_length);
679
680psa_status_t psa_mac_finish(psa_mac_operation_t *operation,
681 uint8_t *mac,
682 size_t mac_size,
683 size_t *mac_length);
684
685psa_status_t psa_mac_verify(psa_mac_operation_t *operation,
686 const uint8_t *mac,
687 size_t mac_length);
688
689psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
690
691/**@}*/
692
Gilles Peskine20035e32018-02-03 22:44:14 +0100693/** \defgroup asymmetric Asymmetric cryptography
694 * @{
695 */
696
697/**
Gilles Peskine0189e752018-02-03 23:57:22 +0100698 * \brief Maximum ECDSA signature size for a given curve bit size
699 *
700 * \param curve_bits Curve size in bits
701 * \return Maximum signature size in bytes
702 *
703 * \note This macro returns a compile-time constant if its argument is one.
704 *
705 * \warning This macro may evaluate its argument multiple times.
706 */
707/*
708 * RFC 4492 page 20:
709 *
710 * Ecdsa-Sig-Value ::= SEQUENCE {
711 * r INTEGER,
712 * s INTEGER
713 * }
714 *
715 * Size is at most
716 * 1 (tag) + 1 (len) + 1 (initial 0) + curve_bytes for each of r and s,
717 * twice that + 1 (tag) + 2 (len) for the sequence
718 * (assuming curve_bytes is less than 126 for r and s,
719 * and less than 124 (total len <= 255) for the sequence)
720 */
721#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
722 ( /*T,L of SEQUENCE*/ ((curve_bits) >= 61 * 8 ? 3 : 2) + \
723 /*T,L of r,s*/ 2 * (((curve_bits) >= 127 * 8 ? 3 : 2) + \
724 /*V of r,s*/ ((curve_bits) + 8) / 8))
725
726
Gilles Peskine308b91d2018-02-08 09:47:44 +0100727/** Safe signature buffer size for psa_asymmetric_sign().
728 *
729 * This macro returns a safe buffer size for a signature using a key
730 * of the specified type and size, with the specified algorithm.
731 * Note that the actual size of the signature may be smaller
732 * (some algorithms produce a variable-size signature).
733 *
734 * \warning This function may call its arguments multiple times or
735 * zero times, so you should not pass arguments that contain
736 * side effects.
737 *
738 * \param key_type An asymmetric key type (this may indifferently be a
739 * key pair type or a public key type).
740 * \param key_bits The size of the key in bits.
741 * \param alg The signature algorithm.
742 *
743 * \return If the parameters are valid and supported, return
744 * a buffer size in bytes that guarantees that
745 * psa_asymmetric_sign() will not fail with
746 * #PSA_ERROR_BUFFER_TOO_SMALL.
747 * If the parameters are a valid combination that is not supported
748 * by the implementation, this macro either shall return either a
749 * sensible size or 0.
750 * If the parameters are not valid, the
751 * return value is unspecified.
752 *
753 */
Gilles Peskine0189e752018-02-03 23:57:22 +0100754#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
755 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, BITS_TO_BYTES(key_bits)) : \
756 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
757 0)
758
759/**
Gilles Peskine20035e32018-02-03 22:44:14 +0100760 * \brief Sign a hash or short message with a private key.
761 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100762 * \param key Key slot containing an asymmetric key pair.
763 * \param alg A signature algorithm that is compatible with
764 * the type of \c key.
765 * \param hash The message to sign.
766 * \param hash_length Size of the \c hash buffer in bytes.
767 * \param salt A salt or label, if supported by the signature
768 * algorithm.
769 * If the signature algorithm does not support a
770 * salt, pass \c NULL.
771 * If the signature algorithm supports an optional
772 * salt and you do not want to pass a salt,
773 * pass \c NULL.
774 * \param salt_length Size of the \c salt buffer in bytes.
775 * If \c salt is \c NULL, pass 0.
776 * \param signature Buffer where the signature is to be written.
777 * \param signature_size Size of the \c signature buffer in bytes.
778 * \param signature_length On success, the number of bytes
779 * that make up the returned signature value.
780 * This is at most #PSA_HASH_FINAL_SIZE(alg)
781 * (note that it may be less).
782 *
783 * \retval PSA_SUCCESS
784 * \retval PSA_ERROR_BUFFER_TOO_SMALL
785 * The size of the \c signature buffer is too small. You can
786 * determine a sufficient buffer size by calling
787 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
788 * where \c key_type and \c key_bits are the type and bit-size
789 * respectively of \c key.
790 * \retval PSA_ERROR_NOT_SUPPORTED
791 * \retval PSA_ERROR_INVALID_ARGUMENT
792 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
793 * \retval PSA_ERROR_COMMUNICATION_FAILURE
794 * \retval PSA_ERROR_HARDWARE_FAILURE
795 * \retval PSA_ERROR_TAMPERING_DETECTED
796 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskine20035e32018-02-03 22:44:14 +0100797 */
798psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
799 psa_algorithm_t alg,
800 const uint8_t *hash,
801 size_t hash_length,
802 const uint8_t *salt,
803 size_t salt_length,
804 uint8_t *signature,
805 size_t signature_size,
806 size_t *signature_length);
807
808/**
809 * \brief Verify the signature a hash or short message using a public key.
810 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100811 * \param key Key slot containing a public key or an
812 * asymmetric key pair.
813 * \param alg A signature algorithm that is compatible with
814 * the type of \c key.
815 * \param hash The message whose signature is to be verified.
816 * \param hash_length Size of the \c hash buffer in bytes.
817 * \param salt A salt or label, if supported by the signature
818 * algorithm.
819 * If the signature algorithm does not support a
820 * salt, pass \c NULL.
821 * If the signature algorithm supports an optional
822 * salt and you do not want to pass a salt,
823 * pass \c NULL.
824 * \param salt_length Size of the \c salt buffer in bytes.
825 * If \c salt is \c NULL, pass 0.
826 * \param signature Buffer containing the signature to verify.
827 * \param signature_size Size of the \c signature buffer in bytes.
828 *
829 * \retval PSA_SUCCESS
830 * The signature is valid.
831 * \retval PSA_ERROR_INVALID_SIGNATURE
832 * The calculation was perfomed successfully, but the passed
833 * signature is not a valid signature.
834 * \retval PSA_ERROR_NOT_SUPPORTED
835 * \retval PSA_ERROR_INVALID_ARGUMENT
836 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
837 * \retval PSA_ERROR_COMMUNICATION_FAILURE
838 * \retval PSA_ERROR_HARDWARE_FAILURE
839 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine20035e32018-02-03 22:44:14 +0100840 */
841psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
842 psa_algorithm_t alg,
843 const uint8_t *hash,
844 size_t hash_length,
845 const uint8_t *salt,
846 size_t salt_length,
847 uint8_t *signature,
848 size_t signature_size);
849
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100850/**@}*/
851
Gilles Peskinee59236f2018-01-27 23:32:46 +0100852#ifdef __cplusplus
853}
854#endif
855
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100856/* The file "crypto_struct.h" contains definitions for
857 * implementation-specific structs that are declared above. */
858#include "crypto_struct.h"
859
860/* The file "crypto_extra.h" contains vendor-specific definitions. This
861 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +0100862#include "crypto_extra.h"
863
864#endif /* PSA_CRYPTO_H */