blob: 94a5e0a9b10889d056e116b5ea65eb2a0fdb526b [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)
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100254#define PSA_ALG_BLOCK_CIPHER_BASE ((psa_algorithm_t)0x04000000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100255#define PSA_ALG_BLOCK_CIPHER_MODE_MASK ((psa_algorithm_t)0x000000ff)
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100256#define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x003f0000)
257#define PSA_ALG_BLOCK_CIPHER_PAD_NONE ((psa_algorithm_t)0x00000000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100258#define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100259#define PSA_ALG_IS_BLOCK_CIPHER(alg) \
260 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \
261 PSA_ALG_BLOCK_CIPHER_BASE)
262
Gilles Peskine98f0a242018-02-06 18:57:29 +0100263#define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100264#define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002)
265#define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003)
266#define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100267#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000)
268#define PSA_ALG_CTR ((psa_algorithm_t)0x04800001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100269#define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100270
Gilles Peskine8c9def32018-02-08 10:02:12 +0100271#define PSA_ALG_CCM ((psa_algorithm_t)0x06000001)
272#define PSA_ALG_GCM ((psa_algorithm_t)0x06000002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100273
274#define PSA_ALG_RSA_PKCS1V15_RAW ((psa_algorithm_t)0x10010000)
275#define PSA_ALG_RSA_PSS_MGF1 ((psa_algorithm_t)0x10020000)
276#define PSA_ALG_RSA_OAEP ((psa_algorithm_t)0x12020000)
277#define PSA_ALG_RSA_PKCS1V15(hash_alg) \
278 (PSA_ALG_RSA_PKCS1V15_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
279#define PSA_ALG_IS_RSA_PKCS1V15(alg) \
Gilles Peskine20035e32018-02-03 22:44:14 +0100280 (((alg) & 0x7fffff00) == PSA_ALG_RSA_PKCS1V15_RAW)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100281#define PSA_ALG_RSA_GET_HASH(alg) \
282 (((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100283
284/**@}*/
285
286/** \defgroup key_management Key management
287 * @{
288 */
289
290/**
291 * \brief Import a key in binary format.
292 *
293 * This function supports any output from psa_export_key().
294 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100295 * \param key Slot where the key will be stored. This must be a
296 * valid slot for a key of the chosen type. It must
297 * be unoccupied.
298 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
299 * \param data Buffer containing the key data.
300 * \param data_length Size of the \c data buffer in bytes.
301 *
302 * \retval PSA_SUCCESS
303 * Success.
304 * \retval PSA_ERROR_NOT_SUPPORTED
305 * The key type or key size is not supported.
306 * \retval PSA_ERROR_INVALID_ARGUMENT
307 * The key slot is invalid,
308 * or the key data is not correctly formatted.
309 * \retval PSA_ERROR_OCCUPIED_SLOT
310 There is already a key in the specified slot.
311 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
312 * \retval PSA_ERROR_COMMUNICATION_FAILURE
313 * \retval PSA_ERROR_HARDWARE_FAILURE
314 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100315 */
316psa_status_t psa_import_key(psa_key_slot_t key,
317 psa_key_type_t type,
318 const uint8_t *data,
319 size_t data_length);
320
321/**
322 * \brief Destroy a key.
323 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100324 * \retval PSA_SUCCESS
325 * \retval PSA_ERROR_EMPTY_SLOT
326 * \retval PSA_ERROR_COMMUNICATION_FAILURE
327 * \retval PSA_ERROR_HARDWARE_FAILURE
328 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100329 */
330psa_status_t psa_destroy_key(psa_key_slot_t key);
331
332/**
333 * \brief Get basic metadata about a key.
334 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100335 * \param key Slot whose content is queried. This must
336 * be an occupied key slot.
337 * \param type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
338 * This may be a null pointer, in which case the key type
339 * is not written.
340 * \param bits On success, the key size in bits.
341 * This may be a null pointer, in which case the key type
342 * is not written.
343 *
344 * \retval PSA_SUCCESS
345 * \retval PSA_ERROR_EMPTY_SLOT
346 * \retval PSA_ERROR_COMMUNICATION_FAILURE
347 * \retval PSA_ERROR_HARDWARE_FAILURE
348 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100349 */
350psa_status_t psa_get_key_information(psa_key_slot_t key,
351 psa_key_type_t *type,
352 size_t *bits);
353
354/**
355 * \brief Export a key in binary format.
356 *
357 * The output of this function can be passed to psa_import_key() to
358 * create an equivalent object.
359 *
360 * If a key is created with psa_import_key() and then exported with
361 * this function, it is not guaranteed that the resulting data is
362 * identical: the implementation may choose a different representation
Gilles Peskine92b30732018-03-03 21:29:30 +0100363 * of the same key if the format permits it.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100364 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100365 * For standard key types, the output format is as follows:
366 *
367 * - For symmetric keys (including MAC keys), the format is the
368 * raw bytes of the key.
369 * - For DES, the key data consists of 8 bytes. The parity bits must be
370 * correct.
371 * - For Triple-DES, the format is the concatenation of the
372 * two or three DES keys.
Gilles Peskine92b30732018-03-03 21:29:30 +0100373 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
Gilles Peskine308b91d2018-02-08 09:47:44 +0100374 * is the non-encrypted DER representation defined by PKCS\#8 (RFC 5208)
375 * as PrivateKeyInfo.
376 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
377 * is the DER representation defined by X.509.
378 *
379 * \param key Slot whose content is to be exported. This must
380 * be an occupied key slot.
381 * \param data Buffer where the key data is to be written.
382 * \param data_size Size of the \c data buffer in bytes.
383 * \param data_length On success, the number of bytes
384 * that make up the key data.
385 *
386 * \retval PSA_SUCCESS
387 * \retval PSA_ERROR_EMPTY_SLOT
Gilles Peskine92b30732018-03-03 21:29:30 +0100388 * \retval PSA_ERROR_NOT_PERMITTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100389 * \retval PSA_ERROR_COMMUNICATION_FAILURE
390 * \retval PSA_ERROR_HARDWARE_FAILURE
391 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100392 */
393psa_status_t psa_export_key(psa_key_slot_t key,
394 uint8_t *data,
395 size_t data_size,
396 size_t *data_length);
397
Gilles Peskine20035e32018-02-03 22:44:14 +0100398
399/**@}*/
400
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100401/** \defgroup hash Message digests
402 * @{
403 */
404
Gilles Peskine308b91d2018-02-08 09:47:44 +0100405/** The type of the state data structure for multipart hash operations.
406 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100407 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100408 * make any assumptions about the content of this structure except
409 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100410typedef struct psa_hash_operation_s psa_hash_operation_t;
411
Gilles Peskine308b91d2018-02-08 09:47:44 +0100412/** The size of the output of psa_hash_finish(), in bytes.
413 *
414 * This is also the hash size that psa_hash_verify() expects.
415 *
416 * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
417 * #PSA_ALG_IS_HASH(alg) is true).
418 *
419 * \return The hash size for the specified hash algorithm.
420 * If the hash algorithm is not recognized, return 0.
421 * An implementation may return either 0 or the correct size
422 * for a hash algorithm that it recognizes, but does not support.
423 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100424#define PSA_HASH_FINAL_SIZE(alg) \
425 ( \
426 (alg) == PSA_ALG_MD2 ? 16 : \
427 (alg) == PSA_ALG_MD4 ? 16 : \
428 (alg) == PSA_ALG_MD5 ? 16 : \
429 (alg) == PSA_ALG_SHA_256_128 ? 16 : \
430 (alg) == PSA_ALG_RIPEMD160 ? 20 : \
431 (alg) == PSA_ALG_SHA_1 ? 20 : \
432 (alg) == PSA_ALG_SHA_256_160 ? 20 : \
433 (alg) == PSA_ALG_SHA_224 ? 28 : \
434 (alg) == PSA_ALG_SHA_256 ? 32 : \
435 (alg) == PSA_ALG_SHA_384 ? 48 : \
436 (alg) == PSA_ALG_SHA_512 ? 64 : \
437 (alg) == PSA_ALG_SHA_512_224 ? 28 : \
438 (alg) == PSA_ALG_SHA_512_256 ? 32 : \
439 (alg) == PSA_ALG_SHA3_224 ? 28 : \
440 (alg) == PSA_ALG_SHA3_256 ? 32 : \
441 (alg) == PSA_ALG_SHA3_384 ? 48 : \
442 (alg) == PSA_ALG_SHA3_512 ? 64 : \
443 0)
444
Gilles Peskine308b91d2018-02-08 09:47:44 +0100445/** Start a multipart hash operation.
446 *
447 * The sequence of operations to calculate a hash (message digest)
448 * is as follows:
449 * -# Allocate an operation object which will be passed to all the functions
450 * listed here.
451 * -# Call psa_hash_start() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100452 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100453 * of the message each time. The hash that is calculated is the hash
454 * of the concatenation of these messages in order.
455 * -# To calculate the hash, call psa_hash_finish().
456 * To compare the hash with an expected value, call psa_hash_verify().
457 *
458 * The application may call psa_hash_abort() at any time after the operation
459 * has been initialized with psa_hash_start().
460 *
461 * After a successful call to psa_hash_start(), the application must
462 * eventually destroy the operation through one of the following means:
463 * - A failed call to psa_hash_update().
464 * - A call to psa_hash_final(), psa_hash_verify() or psa_hash_abort().
465 *
466 * \param operation
467 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
468 * such that #PSA_ALG_IS_HASH(alg) is true).
469 *
470 * \retval PSA_SUCCESS
471 * Success.
472 * \retval PSA_ERROR_NOT_SUPPORTED
473 * \c alg is not supported or is not a hash algorithm.
474 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
475 * \retval PSA_ERROR_COMMUNICATION_FAILURE
476 * \retval PSA_ERROR_HARDWARE_FAILURE
477 * \retval PSA_ERROR_TAMPERING_DETECTED
478 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100479psa_status_t psa_hash_start(psa_hash_operation_t *operation,
480 psa_algorithm_t alg);
481
Gilles Peskine308b91d2018-02-08 09:47:44 +0100482/** Add a message fragment to a multipart hash operation.
483 *
484 * The application must call psa_hash_start() before calling this function.
485 *
486 * If this function returns an error status, the operation becomes inactive.
487 *
488 * \param operation Active hash operation.
489 * \param input Buffer containing the message fragment to hash.
490 * \param input_length Size of the \c input buffer in bytes.
491 *
492 * \retval PSA_SUCCESS
493 * Success.
494 * \retval PSA_ERROR_BAD_STATE
495 * The operation state is not valid (not started, or already completed).
496 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
497 * \retval PSA_ERROR_COMMUNICATION_FAILURE
498 * \retval PSA_ERROR_HARDWARE_FAILURE
499 * \retval PSA_ERROR_TAMPERING_DETECTED
500 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100501psa_status_t psa_hash_update(psa_hash_operation_t *operation,
502 const uint8_t *input,
503 size_t input_length);
504
Gilles Peskine308b91d2018-02-08 09:47:44 +0100505/** Finish the calculation of the hash of a message.
506 *
507 * The application must call psa_hash_start() before calling this function.
508 * This function calculates the hash of the message formed by concatenating
509 * the inputs passed to preceding calls to psa_hash_update().
510 *
511 * When this function returns, the operation becomes inactive.
512 *
513 * \warning Applications should not call this function if they expect
514 * a specific value for the hash. Call psa_hash_verify() instead.
515 * Beware that comparing integrity or authenticity data such as
516 * hash values with a function such as \c memcmp is risky
517 * because the time taken by the comparison may leak information
518 * about the hashed data which could allow an attacker to guess
519 * a valid hash and thereby bypass security controls.
520 *
521 * \param operation Active hash operation.
522 * \param hash Buffer where the hash is to be written.
523 * \param hash_size Size of the \c hash buffer in bytes.
524 * \param hash_length On success, the number of bytes
525 * that make up the hash value. This is always
526 * #PSA_HASH_FINAL_SIZE(alg) where \c alg is the
527 * hash algorithm that is calculated.
528 *
529 * \retval PSA_SUCCESS
530 * Success.
531 * \retval PSA_ERROR_BAD_STATE
532 * The operation state is not valid (not started, or already completed).
533 * \retval PSA_ERROR_BUFFER_TOO_SMALL
534 * The size of the \c hash buffer is too small. You can determine a
535 * sufficient buffer size by calling #PSA_HASH_FINAL_SIZE(alg)
536 * where \c alg is the hash algorithm that is calculated.
537 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
538 * \retval PSA_ERROR_COMMUNICATION_FAILURE
539 * \retval PSA_ERROR_HARDWARE_FAILURE
540 * \retval PSA_ERROR_TAMPERING_DETECTED
541 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100542psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
543 uint8_t *hash,
544 size_t hash_size,
545 size_t *hash_length);
546
Gilles Peskine308b91d2018-02-08 09:47:44 +0100547/** Finish the calculation of the hash of a message and compare it with
548 * an expected value.
549 *
550 * The application must call psa_hash_start() before calling this function.
551 * This function calculates the hash of the message formed by concatenating
552 * the inputs passed to preceding calls to psa_hash_update(). It then
553 * compares the calculated hash with the expected hash passed as a
554 * parameter to this function.
555 *
556 * When this function returns, the operation becomes inactive.
557 *
558 * \note Applications shall make the best effort to ensure that the
559 * comparison between the actual hash and the expected hash is performed
560 * in constant time.
561 *
562 * \param operation Active hash operation.
563 * \param hash Buffer containing the expected hash value.
564 * \param hash_length Size of the \c hash buffer in bytes.
565 *
566 * \retval PSA_SUCCESS
567 * The expected hash is identical to the actual hash of the message.
568 * \retval PSA_ERROR_INVALID_SIGNATURE
569 * The hash of the message was calculated successfully, but it
570 * differs from the expected hash.
571 * \retval PSA_ERROR_BAD_STATE
572 * The operation state is not valid (not started, or already completed).
573 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
574 * \retval PSA_ERROR_COMMUNICATION_FAILURE
575 * \retval PSA_ERROR_HARDWARE_FAILURE
576 * \retval PSA_ERROR_TAMPERING_DETECTED
577 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100578psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
579 const uint8_t *hash,
580 size_t hash_length);
581
Gilles Peskine308b91d2018-02-08 09:47:44 +0100582/** Abort a hash operation.
583 *
584 * This function may be called at any time after psa_hash_start().
585 * Aborting an operation frees all associated resources except for the
586 * \c operation structure itself.
587 *
588 * Implementation should strive to be robust and handle inactive hash
589 * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However,
590 * application writers should beware that uninitialized memory may happen
591 * to be indistinguishable from an active hash operation, and the behavior
592 * of psa_hash_abort() is undefined in this case.
593 *
594 * \param operation Active hash operation.
595 *
596 * \retval PSA_SUCCESS
597 * \retval PSA_ERROR_BAD_STATE
598 * \c operation is not an active hash operation.
599 * \retval PSA_ERROR_COMMUNICATION_FAILURE
600 * \retval PSA_ERROR_HARDWARE_FAILURE
601 * \retval PSA_ERROR_TAMPERING_DETECTED
602 */
603psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100604
605/**@}*/
606
Gilles Peskine8c9def32018-02-08 10:02:12 +0100607/** \defgroup MAC Message authentication codes
608 * @{
609 */
610
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100611/** The type of the state data structure for multipart MAC operations.
612 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100613 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100614 * make any assumptions about the content of this structure except
615 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100616typedef struct psa_mac_operation_s psa_mac_operation_t;
617
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100618/** The size of the output of psa_mac_finish(), in bytes.
619 *
620 * This is also the MAC size that psa_mac_verify() expects.
621 *
622 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
623 * #PSA_ALG_IS_MAC(alg) is true).
624 *
625 * \return The MAC size for the specified algorithm.
626 * If the MAC algorithm is not recognized, return 0.
627 * An implementation may return either 0 or the correct size
628 * for a MAC algorithm that it recognizes, but does not support.
629 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100630#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
631 (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_FINAL_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
632 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
633 0)
634
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100635/** Start a multipart MAC operation.
636 *
637 * The sequence of operations to calculate a MAC (message authentication code)
638 * is as follows:
639 * -# Allocate an operation object which will be passed to all the functions
640 * listed here.
641 * -# Call psa_mac_start() to specify the algorithm and key.
642 * The key remains associated with the operation even if the content
643 * of the key slot changes.
644 * -# Call psa_mac_update() zero, one or more times, passing a fragment
645 * of the message each time. The MAC that is calculated is the MAC
646 * of the concatenation of these messages in order.
647 * -# To calculate the MAC, call psa_mac_finish().
648 * To compare the MAC with an expected value, call psa_mac_verify().
649 *
650 * The application may call psa_mac_abort() at any time after the operation
651 * has been initialized with psa_mac_start().
652 *
653 * After a successful call to psa_mac_start(), the application must
654 * eventually destroy the operation through one of the following means:
655 * - A failed call to psa_mac_update().
656 * - A call to psa_mac_final(), psa_mac_verify() or psa_mac_abort().
657 *
658 * \param operation
659 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
660 * such that #PSA_ALG_IS_MAC(alg) is true).
661 *
662 * \retval PSA_SUCCESS
663 * Success.
664 * \retval PSA_ERROR_EMPTY_SLOT
Gilles Peskine92b30732018-03-03 21:29:30 +0100665 * \retval PSA_ERROR_NOT_PERMITTED
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100666 * \retval PSA_ERROR_INVALID_ARGUMENT
667 * \c key is not compatible with \c alg.
668 * \retval PSA_ERROR_NOT_SUPPORTED
669 * \c alg is not supported or is not a MAC algorithm.
670 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
671 * \retval PSA_ERROR_COMMUNICATION_FAILURE
672 * \retval PSA_ERROR_HARDWARE_FAILURE
673 * \retval PSA_ERROR_TAMPERING_DETECTED
674 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100675psa_status_t psa_mac_start(psa_mac_operation_t *operation,
676 psa_key_slot_t key,
677 psa_algorithm_t alg);
678
679psa_status_t psa_mac_update(psa_mac_operation_t *operation,
680 const uint8_t *input,
681 size_t input_length);
682
683psa_status_t psa_mac_finish(psa_mac_operation_t *operation,
684 uint8_t *mac,
685 size_t mac_size,
686 size_t *mac_length);
687
688psa_status_t psa_mac_verify(psa_mac_operation_t *operation,
689 const uint8_t *mac,
690 size_t mac_length);
691
692psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
693
694/**@}*/
695
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100696/** \defgroup cipher Symmetric ciphers
697 * @{
698 */
699
700/** The type of the state data structure for multipart cipher operations.
701 *
702 * This is an implementation-defined \c struct. Applications should not
703 * make any assumptions about the content of this structure except
704 * as directed by the documentation of a specific implementation. */
705typedef struct psa_cipher_operation_s psa_cipher_operation_t;
706
707/** Set the key for a multipart symmetric encryption operation.
708 *
709 * The sequence of operations to encrypt a message with a symmetric cipher
710 * is as follows:
711 * -# Allocate an operation object which will be passed to all the functions
712 * listed here.
713 * -# Call psa_encrypt_setup() to specify the algorithm and key.
714 * The key remains associated with the operation even if the content
715 * of the key slot changes.
716 * -# Call either psa_encrypt_generate_iv() or psa_encrypt_set_iv() to
717 * generate or set the IV (initialization vector). You should use
718 * psa_encrypt_generate_iv() unless the protocol you are implementing
719 * requires a specific IV value.
720 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
721 * of the message each time.
722 * -# Call psa_cipher_finish().
723 *
724 * The application may call psa_cipher_abort() at any time after the operation
725 * has been initialized with psa_encrypt_setup().
726 *
727 * After a successful call to psa_encrypt_setup(), the application must
728 * eventually destroy the operation through one of the following means:
729 * - A failed call to psa_encrypt_generate_iv(), psa_encrypt_set_iv()
730 * or psa_cipher_update().
731 * - A call to psa_cipher_final() or psa_cipher_abort().
732 *
733 * \param operation
734 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
735 * such that #PSA_ALG_IS_CIPHER(alg) is true).
736 *
737 * \retval PSA_SUCCESS
738 * Success.
739 * \retval PSA_ERROR_EMPTY_SLOT
740 * \retval PSA_ERROR_NOT_PERMITTED
741 * \retval PSA_ERROR_INVALID_ARGUMENT
742 * \c key is not compatible with \c alg.
743 * \retval PSA_ERROR_NOT_SUPPORTED
744 * \c alg is not supported or is not a cipher algorithm.
745 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
746 * \retval PSA_ERROR_COMMUNICATION_FAILURE
747 * \retval PSA_ERROR_HARDWARE_FAILURE
748 * \retval PSA_ERROR_TAMPERING_DETECTED
749 */
750psa_status_t psa_encrypt_setup(psa_cipher_operation_t *operation,
751 psa_key_slot_t key,
752 psa_algorithm_t alg);
753
754/** Set the key for a multipart symmetric decryption operation.
755 *
756 * The sequence of operations to decrypt a message with a symmetric cipher
757 * is as follows:
758 * -# Allocate an operation object which will be passed to all the functions
759 * listed here.
760 * -# Call psa_decrypt_setup() to specify the algorithm and key.
761 * The key remains associated with the operation even if the content
762 * of the key slot changes.
763 * -# Call psa_cipher_update() with the IV (initialization vector) for the
764 * decryption. If the IV is prepended to the ciphertext, you can call
765 * psa_cipher_update() on a buffer containing the IV followed by the
766 * beginning of the message.
767 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
768 * of the message each time.
769 * -# Call psa_cipher_finish().
770 *
771 * The application may call psa_cipher_abort() at any time after the operation
772 * has been initialized with psa_encrypt_setup().
773 *
774 * After a successful call to psa_decrypt_setup(), the application must
775 * eventually destroy the operation through one of the following means:
776 * - A failed call to psa_cipher_update().
777 * - A call to psa_cipher_final() or psa_cipher_abort().
778 *
779 * \param operation
780 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
781 * such that #PSA_ALG_IS_CIPHER(alg) is true).
782 *
783 * \retval PSA_SUCCESS
784 * Success.
785 * \retval PSA_ERROR_EMPTY_SLOT
786 * \retval PSA_ERROR_NOT_PERMITTED
787 * \retval PSA_ERROR_INVALID_ARGUMENT
788 * \c key is not compatible with \c alg.
789 * \retval PSA_ERROR_NOT_SUPPORTED
790 * \c alg is not supported or is not a cipher algorithm.
791 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
792 * \retval PSA_ERROR_COMMUNICATION_FAILURE
793 * \retval PSA_ERROR_HARDWARE_FAILURE
794 * \retval PSA_ERROR_TAMPERING_DETECTED
795 */
796psa_status_t psa_decrypt_setup(psa_cipher_operation_t *operation,
797 psa_key_slot_t key,
798 psa_algorithm_t alg);
799
800psa_status_t psa_encrypt_generate_iv(psa_cipher_operation_t *operation,
801 unsigned char *iv,
802 size_t iv_size,
803 size_t *iv_length);
804
805psa_status_t psa_encrypt_set_iv(psa_cipher_operation_t *operation,
806 const unsigned char *iv,
807 size_t iv_length);
808
809psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
810 const uint8_t *input,
811 size_t input_length);
812
813psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
814 uint8_t *mac,
815 size_t mac_size,
816 size_t *mac_length);
817
818psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
819
820/**@}*/
821
Gilles Peskine3b555712018-03-03 21:27:57 +0100822/** \defgroup aead Authenticated encryption with associated data (AEAD)
823 * @{
824 */
825
826/** The type of the state data structure for multipart AEAD operations.
827 *
828 * This is an implementation-defined \c struct. Applications should not
829 * make any assumptions about the content of this structure except
830 * as directed by the documentation of a specific implementation. */
831typedef struct psa_aead_operation_s psa_aead_operation_t;
832
833/** Set the key for a multipart authenticated encryption operation.
834 *
835 * The sequence of operations to authenticate-and-encrypt a message
836 * is as follows:
837 * -# Allocate an operation object which will be passed to all the functions
838 * listed here.
839 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
840 * The key remains associated with the operation even if the content
841 * of the key slot changes.
842 * -# Call either psa_aead_generate_iv() or psa_aead_set_iv() to
843 * generate or set the IV (initialization vector). You should use
844 * psa_encrypt_generate_iv() unless the protocol you are implementing
845 * requires a specific IV value.
846 * -# Call psa_aead_update_ad() to pass the associated data that is
847 * to be authenticated but not encrypted. You may omit this step if
848 * there is no associated data.
849 * -# Call psa_aead_update() zero, one or more times, passing a fragment
850 * of the data to encrypt each time.
851 * -# Call psa_aead_finish().
852 *
853 * The application may call psa_aead_abort() at any time after the operation
854 * has been initialized with psa_aead_encrypt_setup().
855 *
856 * After a successful call to psa_aead_setup(), the application must
857 * eventually destroy the operation through one of the following means:
858 * - A failed call to psa_aead_generate_iv(), psa_aead_set_iv(),
859 * psa_aead_update_ad() or psa_aead_update().
860 * - A call to psa_aead_final() or psa_aead_abort().
861 *
862 * \param operation
863 * \param alg The AEAD algorithm to compute (\c PSA_ALG_XXX value
864 * such that #PSA_ALG_IS_AEAD(alg) is true).
865 *
866 * \retval PSA_SUCCESS
867 * Success.
868 * \retval PSA_ERROR_EMPTY_SLOT
869 * \retval PSA_ERROR_NOT_PERMITTED
870 * \retval PSA_ERROR_INVALID_ARGUMENT
871 * \c key is not compatible with \c alg.
872 * \retval PSA_ERROR_NOT_SUPPORTED
873 * \c alg is not supported or is not an AEAD algorithm.
874 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
875 * \retval PSA_ERROR_COMMUNICATION_FAILURE
876 * \retval PSA_ERROR_HARDWARE_FAILURE
877 * \retval PSA_ERROR_TAMPERING_DETECTED
878 */
879psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
880 psa_key_slot_t key,
881 psa_algorithm_t alg);
882
883/** Set the key for a multipart authenticated decryption operation.
884 *
885 * The sequence of operations to authenticated and decrypt a message
886 * is as follows:
887 * -# Allocate an operation object which will be passed to all the functions
888 * listed here.
889 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
890 * The key remains associated with the operation even if the content
891 * of the key slot changes.
892 * -# Call psa_aead_set_iv() to pass the initialization vector (IV)
893 * for the authenticated decryption.
894 * -# Call psa_aead_update_ad() to pass the associated data that is
895 * to be authenticated but not encrypted. You may omit this step if
896 * there is no associated data.
897 * -# Call psa_aead_update() zero, one or more times, passing a fragment
898 * of the data to decrypt each time.
899 * -# Call psa_aead_finish().
900 *
901 * The application may call psa_aead_abort() at any time after the operation
902 * has been initialized with psa_aead_decrypt_setup().
903 *
904 * After a successful call to psa_decrypt_setup(), the application must
905 * eventually destroy the operation through one of the following means:
906 * - A failed call to psa_aead_update().
907 * - A call to psa_cipher_final() or psa_cipher_abort().
908 *
909 * \param operation
910 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
911 * such that #PSA_ALG_IS_CIPHER(alg) is true).
912 *
913 * \retval PSA_SUCCESS
914 * Success.
915 * \retval PSA_ERROR_EMPTY_SLOT
916 * \retval PSA_ERROR_NOT_PERMITTED
917 * \retval PSA_ERROR_INVALID_ARGUMENT
918 * \c key is not compatible with \c alg.
919 * \retval PSA_ERROR_NOT_SUPPORTED
920 * \c alg is not supported or is not a cipher algorithm.
921 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
922 * \retval PSA_ERROR_COMMUNICATION_FAILURE
923 * \retval PSA_ERROR_HARDWARE_FAILURE
924 * \retval PSA_ERROR_TAMPERING_DETECTED
925 */
926psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
927 psa_key_slot_t key,
928 psa_algorithm_t alg);
929
930psa_status_t psa_aead_generate_iv(psa_aead_operation_t *operation,
931 unsigned char *iv,
932 size_t iv_size,
933 size_t *iv_length);
934
935psa_status_t psa_aead_set_iv(psa_aead_operation_t *operation,
936 const unsigned char *iv,
937 size_t iv_length);
938
939psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
940 const uint8_t *input,
941 size_t input_length);
942
943psa_status_t psa_aead_update(psa_aead_operation_t *operation,
944 const uint8_t *input,
945 size_t input_length);
946
947psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
948 uint8_t *tag,
949 size_t tag_size,
950 size_t *tag_length);
951
952psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
953 uint8_t *tag,
954 size_t tag_length);
955
956psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
957
958/**@}*/
959
Gilles Peskine20035e32018-02-03 22:44:14 +0100960/** \defgroup asymmetric Asymmetric cryptography
961 * @{
962 */
963
964/**
Gilles Peskine0189e752018-02-03 23:57:22 +0100965 * \brief Maximum ECDSA signature size for a given curve bit size
966 *
967 * \param curve_bits Curve size in bits
968 * \return Maximum signature size in bytes
969 *
970 * \note This macro returns a compile-time constant if its argument is one.
971 *
972 * \warning This macro may evaluate its argument multiple times.
973 */
974/*
975 * RFC 4492 page 20:
976 *
977 * Ecdsa-Sig-Value ::= SEQUENCE {
978 * r INTEGER,
979 * s INTEGER
980 * }
981 *
982 * Size is at most
983 * 1 (tag) + 1 (len) + 1 (initial 0) + curve_bytes for each of r and s,
984 * twice that + 1 (tag) + 2 (len) for the sequence
985 * (assuming curve_bytes is less than 126 for r and s,
986 * and less than 124 (total len <= 255) for the sequence)
987 */
988#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
989 ( /*T,L of SEQUENCE*/ ((curve_bits) >= 61 * 8 ? 3 : 2) + \
990 /*T,L of r,s*/ 2 * (((curve_bits) >= 127 * 8 ? 3 : 2) + \
991 /*V of r,s*/ ((curve_bits) + 8) / 8))
992
993
Gilles Peskine308b91d2018-02-08 09:47:44 +0100994/** Safe signature buffer size for psa_asymmetric_sign().
995 *
996 * This macro returns a safe buffer size for a signature using a key
997 * of the specified type and size, with the specified algorithm.
998 * Note that the actual size of the signature may be smaller
999 * (some algorithms produce a variable-size signature).
1000 *
1001 * \warning This function may call its arguments multiple times or
1002 * zero times, so you should not pass arguments that contain
1003 * side effects.
1004 *
1005 * \param key_type An asymmetric key type (this may indifferently be a
1006 * key pair type or a public key type).
1007 * \param key_bits The size of the key in bits.
1008 * \param alg The signature algorithm.
1009 *
1010 * \return If the parameters are valid and supported, return
1011 * a buffer size in bytes that guarantees that
1012 * psa_asymmetric_sign() will not fail with
1013 * #PSA_ERROR_BUFFER_TOO_SMALL.
1014 * If the parameters are a valid combination that is not supported
1015 * by the implementation, this macro either shall return either a
1016 * sensible size or 0.
1017 * If the parameters are not valid, the
1018 * return value is unspecified.
1019 *
1020 */
Gilles Peskine0189e752018-02-03 23:57:22 +01001021#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
1022 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, BITS_TO_BYTES(key_bits)) : \
1023 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
1024 0)
1025
1026/**
Gilles Peskine20035e32018-02-03 22:44:14 +01001027 * \brief Sign a hash or short message with a private key.
1028 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001029 * \param key Key slot containing an asymmetric key pair.
1030 * \param alg A signature algorithm that is compatible with
1031 * the type of \c key.
1032 * \param hash The message to sign.
1033 * \param hash_length Size of the \c hash buffer in bytes.
1034 * \param salt A salt or label, if supported by the signature
1035 * algorithm.
1036 * If the signature algorithm does not support a
1037 * salt, pass \c NULL.
1038 * If the signature algorithm supports an optional
1039 * salt and you do not want to pass a salt,
1040 * pass \c NULL.
1041 * \param salt_length Size of the \c salt buffer in bytes.
1042 * If \c salt is \c NULL, pass 0.
1043 * \param signature Buffer where the signature is to be written.
1044 * \param signature_size Size of the \c signature buffer in bytes.
1045 * \param signature_length On success, the number of bytes
1046 * that make up the returned signature value.
1047 * This is at most #PSA_HASH_FINAL_SIZE(alg)
1048 * (note that it may be less).
1049 *
1050 * \retval PSA_SUCCESS
1051 * \retval PSA_ERROR_BUFFER_TOO_SMALL
1052 * The size of the \c signature buffer is too small. You can
1053 * determine a sufficient buffer size by calling
1054 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
1055 * where \c key_type and \c key_bits are the type and bit-size
1056 * respectively of \c key.
1057 * \retval PSA_ERROR_NOT_SUPPORTED
1058 * \retval PSA_ERROR_INVALID_ARGUMENT
1059 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1060 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1061 * \retval PSA_ERROR_HARDWARE_FAILURE
1062 * \retval PSA_ERROR_TAMPERING_DETECTED
1063 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskine20035e32018-02-03 22:44:14 +01001064 */
1065psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
1066 psa_algorithm_t alg,
1067 const uint8_t *hash,
1068 size_t hash_length,
1069 const uint8_t *salt,
1070 size_t salt_length,
1071 uint8_t *signature,
1072 size_t signature_size,
1073 size_t *signature_length);
1074
1075/**
1076 * \brief Verify the signature a hash or short message using a public key.
1077 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001078 * \param key Key slot containing a public key or an
1079 * asymmetric key pair.
1080 * \param alg A signature algorithm that is compatible with
1081 * the type of \c key.
1082 * \param hash The message whose signature is to be verified.
1083 * \param hash_length Size of the \c hash buffer in bytes.
1084 * \param salt A salt or label, if supported by the signature
1085 * algorithm.
1086 * If the signature algorithm does not support a
1087 * salt, pass \c NULL.
1088 * If the signature algorithm supports an optional
1089 * salt and you do not want to pass a salt,
1090 * pass \c NULL.
1091 * \param salt_length Size of the \c salt buffer in bytes.
1092 * If \c salt is \c NULL, pass 0.
1093 * \param signature Buffer containing the signature to verify.
1094 * \param signature_size Size of the \c signature buffer in bytes.
1095 *
1096 * \retval PSA_SUCCESS
1097 * The signature is valid.
1098 * \retval PSA_ERROR_INVALID_SIGNATURE
1099 * The calculation was perfomed successfully, but the passed
1100 * signature is not a valid signature.
1101 * \retval PSA_ERROR_NOT_SUPPORTED
1102 * \retval PSA_ERROR_INVALID_ARGUMENT
1103 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1104 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1105 * \retval PSA_ERROR_HARDWARE_FAILURE
1106 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine20035e32018-02-03 22:44:14 +01001107 */
1108psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
1109 psa_algorithm_t alg,
1110 const uint8_t *hash,
1111 size_t hash_length,
1112 const uint8_t *salt,
1113 size_t salt_length,
1114 uint8_t *signature,
1115 size_t signature_size);
1116
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01001117/**@}*/
1118
Gilles Peskinee59236f2018-01-27 23:32:46 +01001119#ifdef __cplusplus
1120}
1121#endif
1122
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001123/* The file "crypto_struct.h" contains definitions for
1124 * implementation-specific structs that are declared above. */
1125#include "crypto_struct.h"
1126
1127/* The file "crypto_extra.h" contains vendor-specific definitions. This
1128 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01001129#include "crypto_extra.h"
1130
1131#endif /* PSA_CRYPTO_H */