blob: af1ab37c401a478c1137789545c687cfbe4c5809 [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__
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010014/* This __DOXYGEN_ONLY__ block contains mock definitions for things that
15 * must be defined in the crypto_platform.h header. These mock definitions
16 * are present in this file as a convenience to generate pretty-printed
17 * documentation that includes those definitions. */
18
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010019/** \defgroup platform Implementation-specific definitions
20 * @{
21 */
22
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010023/** \brief Key slot number.
24 *
25 * This type represents key slots. It must be an unsigned integral
Gilles Peskine308b91d2018-02-08 09:47:44 +010026 * type. The choice of type is implementation-dependent.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010027 * 0 is not a valid key slot number. The meaning of other values is
28 * implementation dependent.
29 *
30 * At any given point in time, each key slot either contains a
31 * cryptographic object, or is empty. Key slots are persistent:
32 * once set, the cryptographic object remains in the key slot until
33 * explicitly destroyed.
34 */
35typedef _unsigned_integral_type_ psa_key_slot_t;
36
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010037/**@}*/
Gilles Peskinef5b9fa12018-03-07 16:40:18 +010038#endif /* __DOXYGEN_ONLY__ */
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010039
Gilles Peskinee59236f2018-01-27 23:32:46 +010040#ifdef __cplusplus
41extern "C" {
42#endif
43
44/** \defgroup basic Basic definitions
45 * @{
46 */
47
48/**
49 * \brief Function return status.
50 *
51 * Zero indicates success, anything else indicates an error.
52 */
53typedef enum {
54 /** The action was completed successfully. */
55 PSA_SUCCESS = 0,
56 /** The requested operation or a parameter is not supported
57 by this implementation. */
58 PSA_ERROR_NOT_SUPPORTED,
59 /** The requested action is denied by a policy. */
60 PSA_ERROR_NOT_PERMITTED,
61 /** An output buffer is too small. */
62 PSA_ERROR_BUFFER_TOO_SMALL,
63 /** A slot is occupied, but must be empty to carry out the
64 requested action. */
65 PSA_ERROR_OCCUPIED_SLOT,
66 /** A slot is empty, but must be occupied to carry out the
67 requested action. */
68 PSA_ERROR_EMPTY_SLOT,
69 /** The requested action cannot be performed in the current state. */
70 PSA_ERROR_BAD_STATE,
71 /** The parameters passed to the function are invalid. */
72 PSA_ERROR_INVALID_ARGUMENT,
73 /** There is not enough runtime memory. */
74 PSA_ERROR_INSUFFICIENT_MEMORY,
75 /** There is not enough persistent storage. */
76 PSA_ERROR_INSUFFICIENT_STORAGE,
77 /** There was a communication failure inside the implementation. */
78 PSA_ERROR_COMMUNICATION_FAILURE,
Gilles Peskinea5905292018-02-07 20:59:33 +010079 /** There was a storage failure that may have led to data loss. */
80 PSA_ERROR_STORAGE_FAILURE,
Gilles Peskinee59236f2018-01-27 23:32:46 +010081 /** A hardware failure was detected. */
82 PSA_ERROR_HARDWARE_FAILURE,
83 /** A tampering attempt was detected. */
84 PSA_ERROR_TAMPERING_DETECTED,
85 /** There is not enough entropy to generate random data needed
86 for the requested action. */
87 PSA_ERROR_INSUFFICIENT_ENTROPY,
Gilles Peskinea5905292018-02-07 20:59:33 +010088 /** The signature, MAC or hash is incorrect. */
Gilles Peskinee59236f2018-01-27 23:32:46 +010089 PSA_ERROR_INVALID_SIGNATURE,
Gilles Peskinea5905292018-02-07 20:59:33 +010090 /** The decrypted padding is incorrect. */
91 PSA_ERROR_INVALID_PADDING,
Gilles Peskinee59236f2018-01-27 23:32:46 +010092 /** An error occurred that does not correspond to any defined
93 failure cause. */
94 PSA_ERROR_UNKNOWN_ERROR,
95} psa_status_t;
96
97/**
98 * \brief Library initialization.
99 *
100 * Applications must call this function before calling any other
101 * function in this module.
102 *
103 * Applications may call this function more than once. Once a call
104 * succeeds, subsequent calls are guaranteed to succeed.
105 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100106 * \retval PSA_SUCCESS
107 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
108 * \retval PSA_ERROR_COMMUNICATION_FAILURE
109 * \retval PSA_ERROR_HARDWARE_FAILURE
110 * \retval PSA_ERROR_TAMPERING_DETECTED
111 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinee59236f2018-01-27 23:32:46 +0100112 */
113psa_status_t psa_crypto_init(void);
114
Gilles Peskine2905a7a2018-03-07 16:39:31 +0100115#define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
116#define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
Gilles Peskine0189e752018-02-03 23:57:22 +0100117
Gilles Peskinee59236f2018-01-27 23:32:46 +0100118/**@}*/
119
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100120/** \defgroup crypto_types Key and algorithm types
121 * @{
122 */
123
Gilles Peskine308b91d2018-02-08 09:47:44 +0100124/** \brief Encoding of a key type.
125 */
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100126typedef uint32_t psa_key_type_t;
127
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100128/** An invalid key type value.
129 *
130 * Zero is not the encoding of any key type.
131 */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100132#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000)
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100133
134/** Vendor-defined flag
135 *
136 * Key types defined by this standard will never have the
137 * #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types
138 * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should
139 * respect the bitwise structure used by standard encodings whenever practical.
140 */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100141#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100142
Gilles Peskine98f0a242018-02-06 18:57:29 +0100143#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000)
144#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x02000000)
145#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x04000000)
mohammad1603dad36fa2018-05-09 02:24:42 -0700146#define PSA_KEY_TYPE_CATEGORY_CIPHER ((psa_key_type_t)0x04000000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100147#define PSA_KEY_TYPE_CATEGORY_ASYMMETRIC ((psa_key_type_t)0x06000000)
148#define PSA_KEY_TYPE_PAIR_FLAG ((psa_key_type_t)0x01000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100149
Gilles Peskine98f0a242018-02-06 18:57:29 +0100150#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001)
151#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x04000001)
152#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x04000002)
153#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003)
154#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x04000004)
155
Gilles Peskine308b91d2018-02-08 09:47:44 +0100156/** RSA public key. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100157#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x06010000)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100158/** RSA key pair (private and public key). */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100159#define PSA_KEY_TYPE_RSA_KEYPAIR ((psa_key_type_t)0x07010000)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100160/** DSA public key. */
161#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x06020000)
162/** DSA key pair (private and public key). */
163#define PSA_KEY_TYPE_DSA_KEYPAIR ((psa_key_type_t)0x07020000)
164#define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x06030000)
165#define PSA_KEY_TYPE_ECC_KEYPAIR_BASE ((psa_key_type_t)0x07030000)
itayzafrir5c753392018-05-08 11:18:38 +0300166#define PSA_KEY_TYPE_ECC_CURVE_NISTP256R1 ((psa_key_type_t)0x00000001)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100167#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100168#define PSA_KEY_TYPE_ECC_KEYPAIR(curve) \
169 (PSA_KEY_TYPE_ECC_KEYPAIR_BASE | (curve))
170#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \
171 (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve))
Gilles Peskine98f0a242018-02-06 18:57:29 +0100172
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100173/** Whether a key type is vendor-defined. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100174#define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100175 (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100176#define PSA_KEY_TYPE_IS_RAW_BYTES(type) \
177 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_RAW_DATA || \
178 ((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100179
180/** Whether a key type is asymmetric: either a key pair or a public key. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100181#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \
182 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_ASYMMETRIC)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100183/** Whether a key type is the public part of a key pair. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100184#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \
185 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG) == \
186 PSA_KEY_TYPE_CATEGORY_ASYMMETRIC))
Gilles Peskine06dc2632018-03-08 07:47:25 +0100187/** Whether a key type is a key pair containing a private part and a public
188 * part. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100189#define PSA_KEY_TYPE_IS_KEYPAIR(type) \
190 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG)) == \
191 (PSA_KEY_TYPE_CATEGORY_ASYMMETRIC | PSA_KEY_TYPE_PAIR_FLAG))
Gilles Peskine06dc2632018-03-08 07:47:25 +0100192/** Whether a key type is an RSA key pair or public key. */
193/** The key pair type corresponding to a public key type. */
194#define PSA_KEY_TYPE_KEYPAIR_OF_PUBLIC_KEY(type) \
195 ((type) | PSA_KEY_TYPE_PAIR_FLAG)
196/** The public key type corresponding to a key pair type. */
197#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) \
198 ((type) & ~PSA_KEY_TYPE_PAIR_FLAG)
Gilles Peskine0189e752018-02-03 23:57:22 +0100199#define PSA_KEY_TYPE_IS_RSA(type) \
Gilles Peskine06dc2632018-03-08 07:47:25 +0100200 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY)
201/** Whether a key type is an elliptic curve key pair or public key. */
Gilles Peskinec66ea6a2018-02-03 22:43:28 +0100202#define PSA_KEY_TYPE_IS_ECC(type) \
Gilles Peskine06dc2632018-03-08 07:47:25 +0100203 ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) & \
204 ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100205
Gilles Peskine7e198532018-03-08 07:50:30 +0100206/** The block size of a block cipher.
207 *
208 * \param type A cipher key type (value of type #psa_key_type_t).
209 *
210 * \return The block size for a block cipher, or 1 for a stream cipher.
211 * The return value is undefined if \c type does not identify
212 * a cipher algorithm.
213 *
214 * \note This macro returns a compile-time constant if its argument is one.
215 *
216 * \warning This macro may evaluate its argument multiple times.
217 */
Gilles Peskine03182e92018-03-07 16:40:52 +0100218#define PSA_BLOCK_CIPHER_BLOCK_SIZE(type) \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100219 ( \
220 (type) == PSA_KEY_TYPE_AES ? 16 : \
221 (type) == PSA_KEY_TYPE_DES ? 8 : \
222 (type) == PSA_KEY_TYPE_CAMELLIA ? 16 : \
Gilles Peskine7e198532018-03-08 07:50:30 +0100223 (type) == PSA_KEY_TYPE_ARC4 ? 1 : \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100224 0)
225
Gilles Peskine308b91d2018-02-08 09:47:44 +0100226/** \brief Encoding of a cryptographic algorithm.
227 *
228 * For algorithms that can be applied to multiple key types, this type
229 * does not encode the key type. For example, for symmetric ciphers
230 * based on a block cipher, #psa_algorithm_t encodes the block cipher
231 * mode and the padding mode while the block cipher itself is encoded
232 * via #psa_key_type_t.
233 */
Gilles Peskine20035e32018-02-03 22:44:14 +0100234typedef uint32_t psa_algorithm_t;
235
Gilles Peskine98f0a242018-02-06 18:57:29 +0100236#define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t)0x80000000)
237#define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t)0x7f000000)
238#define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t)0x01000000)
239#define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x02000000)
240#define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000)
241#define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t)0x06000000)
242#define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t)0x10000000)
243#define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t)0x12000000)
244#define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t)0x22000000)
245#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x30000000)
Gilles Peskine20035e32018-02-03 22:44:14 +0100246
Gilles Peskine98f0a242018-02-06 18:57:29 +0100247#define PSA_ALG_IS_VENDOR_DEFINED(alg) \
248 (((alg) & PSA_ALG_VENDOR_FLAG) != 0)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100249/** Whether the specified algorithm is a hash algorithm.
250 *
Gilles Peskine7e198532018-03-08 07:50:30 +0100251 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100252 *
253 * \return 1 if \c alg is a hash algorithm, 0 otherwise.
254 * This macro may return either 0 or 1 if \c alg is not a valid
Gilles Peskine7e198532018-03-08 07:50:30 +0100255 * algorithm identifier.
256 */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100257#define PSA_ALG_IS_HASH(alg) \
258 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
259#define PSA_ALG_IS_MAC(alg) \
260 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)
261#define PSA_ALG_IS_CIPHER(alg) \
262 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)
263#define PSA_ALG_IS_AEAD(alg) \
264 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD)
265#define PSA_ALG_IS_SIGN(alg) \
266 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)
267#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
268 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)
269#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
270 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)
271#define PSA_ALG_IS_KEY_DERIVATION(alg) \
272 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
273
274#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)
275#define PSA_ALG_MD2 ((psa_algorithm_t)0x01000001)
276#define PSA_ALG_MD4 ((psa_algorithm_t)0x01000002)
277#define PSA_ALG_MD5 ((psa_algorithm_t)0x01000003)
Gilles Peskinee3f694f2018-03-08 07:48:40 +0100278#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x01000004)
279#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x01000005)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100280#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x01000008)
281#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x01000009)
282#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0100000a)
283#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0100000b)
284#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0100000c)
285#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0100000d)
286#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x01000010)
287#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x01000011)
288#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x01000012)
289#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
290
Gilles Peskine8c9def32018-02-08 10:02:12 +0100291#define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100292#define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000)
293#define PSA_ALG_HMAC(hash_alg) \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100294 (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
295#define PSA_ALG_HMAC_HASH(hmac_alg) \
296 (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK))
297#define PSA_ALG_IS_HMAC(alg) \
298 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
299 PSA_ALG_HMAC_BASE)
300#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000)
301#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001)
302#define PSA_ALG_CMAC ((psa_algorithm_t)0x02c00002)
303#define PSA_ALG_GMAC ((psa_algorithm_t)0x02c00003)
304#define PSA_ALG_IS_CIPHER_MAC(alg) \
305 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
306 PSA_ALG_CIPHER_MAC_BASE)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100307
Gilles Peskine8c9def32018-02-08 10:02:12 +0100308#define PSA_ALG_CIPHER_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100309#define PSA_ALG_BLOCK_CIPHER_BASE ((psa_algorithm_t)0x04000000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100310#define PSA_ALG_BLOCK_CIPHER_MODE_MASK ((psa_algorithm_t)0x000000ff)
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100311#define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x003f0000)
312#define PSA_ALG_BLOCK_CIPHER_PAD_NONE ((psa_algorithm_t)0x00000000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100313#define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100314#define PSA_ALG_IS_BLOCK_CIPHER(alg) \
315 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \
316 PSA_ALG_BLOCK_CIPHER_BASE)
317
Gilles Peskine98f0a242018-02-06 18:57:29 +0100318#define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100319#define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002)
320#define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003)
321#define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100322#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000)
323#define PSA_ALG_CTR ((psa_algorithm_t)0x04800001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100324#define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100325
Gilles Peskine8c9def32018-02-08 10:02:12 +0100326#define PSA_ALG_CCM ((psa_algorithm_t)0x06000001)
327#define PSA_ALG_GCM ((psa_algorithm_t)0x06000002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100328
Gilles Peskinea5926232018-03-28 14:16:50 +0200329#define PSA_ALG_RSA_PKCS1V15_SIGN_RAW ((psa_algorithm_t)0x10010000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100330#define PSA_ALG_RSA_PSS_MGF1 ((psa_algorithm_t)0x10020000)
Gilles Peskine6944f9a2018-03-28 14:18:39 +0200331#define PSA_ALG_RSA_PKCS1V15_CRYPT ((psa_algorithm_t)0x12010000)
332#define PSA_ALG_RSA_OAEP_MGF1_BASE ((psa_algorithm_t)0x12020000)
Gilles Peskinea5926232018-03-28 14:16:50 +0200333#define PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) \
334 (PSA_ALG_RSA_PKCS1V15_SIGN_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
335#define PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) \
Gilles Peskine9673cc82018-04-11 16:57:49 +0200336 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_PKCS1V15_SIGN_RAW)
337#define PSA_ALG_RSA_OAEP_MGF1(hash_alg) \
338 (PSA_ALG_RSA_OAEP_MGF1_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
339#define PSA_ALG_IS_RSA_OAEP_MGF1(alg) \
340 (((alg) & ~PSA_ALG_HASH_MASK) == PSA_ALG_RSA_OAEP_MGF1_RAW)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100341#define PSA_ALG_RSA_GET_HASH(alg) \
342 (((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100343
344/**@}*/
345
346/** \defgroup key_management Key management
347 * @{
348 */
349
350/**
351 * \brief Import a key in binary format.
352 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100353 * This function supports any output from psa_export_key(). Refer to the
354 * documentation of psa_export_key() for the format for each key type.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100355 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100356 * \param key Slot where the key will be stored. This must be a
357 * valid slot for a key of the chosen type. It must
358 * be unoccupied.
359 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
360 * \param data Buffer containing the key data.
361 * \param data_length Size of the \c data buffer in bytes.
362 *
363 * \retval PSA_SUCCESS
364 * Success.
365 * \retval PSA_ERROR_NOT_SUPPORTED
366 * The key type or key size is not supported.
367 * \retval PSA_ERROR_INVALID_ARGUMENT
368 * The key slot is invalid,
369 * or the key data is not correctly formatted.
370 * \retval PSA_ERROR_OCCUPIED_SLOT
371 There is already a key in the specified slot.
372 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
373 * \retval PSA_ERROR_COMMUNICATION_FAILURE
374 * \retval PSA_ERROR_HARDWARE_FAILURE
375 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100376 */
377psa_status_t psa_import_key(psa_key_slot_t key,
378 psa_key_type_t type,
379 const uint8_t *data,
380 size_t data_length);
381
382/**
383 * \brief Destroy a key.
384 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100385 * \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_destroy_key(psa_key_slot_t key);
392
393/**
394 * \brief Get basic metadata about a key.
395 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100396 * \param key Slot whose content is queried. This must
397 * be an occupied key slot.
398 * \param type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
399 * This may be a null pointer, in which case the key type
400 * is not written.
401 * \param bits On success, the key size in bits.
Gilles Peskine9a1ba0d2018-03-21 20:49:16 +0100402 * This may be a null pointer, in which case the key size
Gilles Peskine308b91d2018-02-08 09:47:44 +0100403 * is not written.
404 *
405 * \retval PSA_SUCCESS
406 * \retval PSA_ERROR_EMPTY_SLOT
407 * \retval PSA_ERROR_COMMUNICATION_FAILURE
408 * \retval PSA_ERROR_HARDWARE_FAILURE
409 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100410 */
411psa_status_t psa_get_key_information(psa_key_slot_t key,
412 psa_key_type_t *type,
413 size_t *bits);
414
415/**
416 * \brief Export a key in binary format.
417 *
418 * The output of this function can be passed to psa_import_key() to
419 * create an equivalent object.
420 *
421 * If a key is created with psa_import_key() and then exported with
422 * this function, it is not guaranteed that the resulting data is
423 * identical: the implementation may choose a different representation
Gilles Peskine92b30732018-03-03 21:29:30 +0100424 * of the same key if the format permits it.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100425 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100426 * For standard key types, the output format is as follows:
427 *
428 * - For symmetric keys (including MAC keys), the format is the
429 * raw bytes of the key.
430 * - For DES, the key data consists of 8 bytes. The parity bits must be
431 * correct.
432 * - For Triple-DES, the format is the concatenation of the
433 * two or three DES keys.
Gilles Peskine92b30732018-03-03 21:29:30 +0100434 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
Gilles Peskine308b91d2018-02-08 09:47:44 +0100435 * is the non-encrypted DER representation defined by PKCS\#8 (RFC 5208)
436 * as PrivateKeyInfo.
437 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
Gilles Peskine971f7062018-03-20 17:52:58 +0100438 * is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100439 *
440 * \param key Slot whose content is to be exported. This must
441 * be an occupied key slot.
442 * \param data Buffer where the key data is to be written.
443 * \param data_size Size of the \c data buffer in bytes.
444 * \param data_length On success, the number of bytes
445 * that make up the key data.
446 *
447 * \retval PSA_SUCCESS
448 * \retval PSA_ERROR_EMPTY_SLOT
Gilles Peskine92b30732018-03-03 21:29:30 +0100449 * \retval PSA_ERROR_NOT_PERMITTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100450 * \retval PSA_ERROR_COMMUNICATION_FAILURE
451 * \retval PSA_ERROR_HARDWARE_FAILURE
452 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100453 */
454psa_status_t psa_export_key(psa_key_slot_t key,
455 uint8_t *data,
456 size_t data_size,
457 size_t *data_length);
458
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100459/**
460 * \brief Export a public key or the public part of a key pair in binary format.
461 *
462 * The output of this function can be passed to psa_import_key() to
463 * create an object that is equivalent to the public key.
464 *
465 * For standard key types, the output format is as follows:
466 *
467 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEYPAIR or #PSA_KEY_TYPE_RSA_PUBLIC_KEY),
Gilles Peskine971f7062018-03-20 17:52:58 +0100468 * is the DER representation of the public key defined by RFC 5280
469 * as SubjectPublicKeyInfo.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100470 *
471 * \param key Slot whose content is to be exported. This must
472 * be an occupied key slot.
473 * \param data Buffer where the key data is to be written.
474 * \param data_size Size of the \c data buffer in bytes.
475 * \param data_length On success, the number of bytes
476 * that make up the key data.
477 *
478 * \retval PSA_SUCCESS
479 * \retval PSA_ERROR_EMPTY_SLOT
480 * \retval PSA_ERROR_INVALID_ARGUMENT
481 * \retval PSA_ERROR_COMMUNICATION_FAILURE
482 * \retval PSA_ERROR_HARDWARE_FAILURE
483 * \retval PSA_ERROR_TAMPERING_DETECTED
484 */
485psa_status_t psa_export_public_key(psa_key_slot_t key,
486 uint8_t *data,
487 size_t data_size,
488 size_t *data_length);
489
490/**@}*/
491
492/** \defgroup policy Key policies
493 * @{
494 */
495
496/** \brief Encoding of permitted usage on a key. */
497typedef uint32_t psa_key_usage_t;
498
Gilles Peskine7e198532018-03-08 07:50:30 +0100499/** Whether the key may be exported.
500 *
501 * A public key or the public part of a key pair may always be exported
502 * regardless of the value of this permission flag.
503 *
504 * If a key does not have export permission, implementations shall not
505 * allow the key to be exported in plain form from the cryptoprocessor,
506 * whether through psa_export_key() or through a proprietary interface.
507 * The key may however be exportable in a wrapped form, i.e. in a form
508 * where it is encrypted by another key.
509 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100510#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001)
511
Gilles Peskine7e198532018-03-08 07:50:30 +0100512/** Whether the key may be used to encrypt a message.
513 *
514 * For a key pair, this concerns the public key.
515 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100516#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100)
Gilles Peskine7e198532018-03-08 07:50:30 +0100517
518/** Whether the key may be used to decrypt a message.
519 *
520 * For a key pair, this concerns the private key.
521 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100522#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)
Gilles Peskine7e198532018-03-08 07:50:30 +0100523
524/** Whether the key may be used to sign a message.
525 *
526 * For a key pair, this concerns the private key.
527 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100528#define PSA_KEY_USAGE_SIGN ((psa_key_usage_t)0x00000400)
Gilles Peskine7e198532018-03-08 07:50:30 +0100529
530/** Whether the key may be used to verify a message signature.
531 *
532 * For a key pair, this concerns the public key.
533 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100534#define PSA_KEY_USAGE_VERIFY ((psa_key_usage_t)0x00000800)
535
536/** The type of the key policy data structure.
537 *
538 * This is an implementation-defined \c struct. Applications should not
539 * make any assumptions about the content of this structure except
540 * as directed by the documentation of a specific implementation. */
541typedef struct psa_key_policy_s psa_key_policy_t;
542
543/** \brief Initialize a key policy structure to a default that forbids all
544 * usage of the key. */
545void psa_key_policy_init(psa_key_policy_t *policy);
546
Gilles Peskine7e198532018-03-08 07:50:30 +0100547/** \brief Set the standard fields of a policy structure.
548 *
549 * Note that this function does not make any consistency check of the
550 * parameters. The values are only checked when applying the policy to
551 * a key slot with psa_set_key_policy().
552 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100553void psa_key_policy_set_usage(psa_key_policy_t *policy,
554 psa_key_usage_t usage,
555 psa_algorithm_t alg);
556
557psa_key_usage_t psa_key_policy_get_usage(psa_key_policy_t *policy);
558
559psa_algorithm_t psa_key_policy_get_algorithm(psa_key_policy_t *policy);
560
561/** \brief Set the usage policy on a key slot.
562 *
563 * This function must be called on an empty key slot, before importing,
564 * generating or creating a key in the slot. Changing the policy of an
565 * existing key is not permitted.
Gilles Peskine7e198532018-03-08 07:50:30 +0100566 *
567 * Implementations may set restrictions on supported key policies
568 * depending on the key type and the key slot.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100569 */
570psa_status_t psa_set_key_policy(psa_key_slot_t key,
571 const psa_key_policy_t *policy);
572
Gilles Peskine7e198532018-03-08 07:50:30 +0100573/** \brief Get the usage policy for a key slot.
574 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100575psa_status_t psa_get_key_policy(psa_key_slot_t key,
576 psa_key_policy_t *policy);
Gilles Peskine20035e32018-02-03 22:44:14 +0100577
578/**@}*/
579
Gilles Peskine609b6a52018-03-03 21:31:50 +0100580/** \defgroup persistence Key lifetime
581 * @{
582 */
583
584/** Encoding of key lifetimes.
585 */
586typedef uint32_t psa_key_lifetime_t;
587
588/** A volatile key slot retains its content as long as the application is
589 * running. It is guaranteed to be erased on a power reset.
590 */
591#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000)
592
593/** A persistent key slot retains its content as long as it is not explicitly
594 * destroyed.
595 */
596#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001)
597
598/** A write-once key slot may not be modified once a key has been set.
599 * It will retain its content as long as the device remains operational.
600 */
601#define PSA_KEY_LIFETIME_WRITE_ONCE ((psa_key_lifetime_t)0x7fffffff)
602
Gilles Peskined393e182018-03-08 07:49:16 +0100603/** \brief Retrieve the lifetime of a key slot.
604 *
605 * The assignment of lifetimes to slots is implementation-dependent.
Gilles Peskine8ca56022018-04-17 14:07:59 +0200606 *
Gilles Peskine9bb53d72018-04-17 14:09:24 +0200607 * \param key Slot to query.
mohammad1603804cd712018-03-20 22:44:08 +0200608 * \param lifetime On success, the lifetime value.
Gilles Peskine8ca56022018-04-17 14:07:59 +0200609 *
mohammad1603804cd712018-03-20 22:44:08 +0200610 * \retval PSA_SUCCESS
611 * Success.
612 * \retval PSA_ERROR_INVALID_ARGUMENT
mohammad1603a7d245a2018-04-17 00:40:08 -0700613 * The key slot is invalid.
Gilles Peskinef0c9dd32018-04-17 14:11:07 +0200614 * \retval PSA_ERROR_COMMUNICATION_FAILURE
615 * \retval PSA_ERROR_HARDWARE_FAILURE
616 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskined393e182018-03-08 07:49:16 +0100617 */
Gilles Peskine609b6a52018-03-03 21:31:50 +0100618psa_status_t psa_get_key_lifetime(psa_key_slot_t key,
619 psa_key_lifetime_t *lifetime);
620
Gilles Peskined393e182018-03-08 07:49:16 +0100621/** \brief Change the lifetime of a key slot.
622 *
623 * Whether the lifetime of a key slot can be changed at all, and if so
Gilles Peskine19067982018-03-20 17:54:53 +0100624 * whether the lifetime of an occupied key slot can be changed, is
Gilles Peskined393e182018-03-08 07:49:16 +0100625 * implementation-dependent.
Gilles Peskine8ca56022018-04-17 14:07:59 +0200626 *
Gilles Peskine9bb53d72018-04-17 14:09:24 +0200627 * \param key Slot whose lifetime is to be changed.
628 * \param lifetime The lifetime value to set for the given key slot.
Gilles Peskine8ca56022018-04-17 14:07:59 +0200629 *
mohammad1603804cd712018-03-20 22:44:08 +0200630 * \retval PSA_SUCCESS
631 * Success.
632 * \retval PSA_ERROR_INVALID_ARGUMENT
633 * The key slot is invalid,
mohammad1603a7d245a2018-04-17 00:40:08 -0700634 * or the lifetime value is invalid.
Gilles Peskinef0c9dd32018-04-17 14:11:07 +0200635 * \retval PSA_ERROR_NOT_SUPPORTED
636 * The implementation does not support the specified lifetime value,
637 * at least for the specified key slot.
638 * \retval PSA_ERROR_OCCUPIED_SLOT
639 * The slot contains a key, and the implementation does not support
640 * changing the lifetime of an occupied slot.
641 * \retval PSA_ERROR_COMMUNICATION_FAILURE
642 * \retval PSA_ERROR_HARDWARE_FAILURE
643 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskined393e182018-03-08 07:49:16 +0100644 */
645psa_status_t psa_set_key_lifetime(psa_key_slot_t key,
mohammad1603ea050092018-04-17 00:31:34 -0700646 psa_key_lifetime_t lifetime);
Gilles Peskined393e182018-03-08 07:49:16 +0100647
Gilles Peskine609b6a52018-03-03 21:31:50 +0100648/**@}*/
649
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100650/** \defgroup hash Message digests
651 * @{
652 */
653
Gilles Peskine308b91d2018-02-08 09:47:44 +0100654/** The type of the state data structure for multipart hash operations.
655 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100656 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100657 * make any assumptions about the content of this structure except
658 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100659typedef struct psa_hash_operation_s psa_hash_operation_t;
660
Gilles Peskine308b91d2018-02-08 09:47:44 +0100661/** The size of the output of psa_hash_finish(), in bytes.
662 *
663 * This is also the hash size that psa_hash_verify() expects.
664 *
665 * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
666 * #PSA_ALG_IS_HASH(alg) is true).
667 *
668 * \return The hash size for the specified hash algorithm.
669 * If the hash algorithm is not recognized, return 0.
670 * An implementation may return either 0 or the correct size
671 * for a hash algorithm that it recognizes, but does not support.
672 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100673#define PSA_HASH_FINAL_SIZE(alg) \
674 ( \
675 (alg) == PSA_ALG_MD2 ? 16 : \
676 (alg) == PSA_ALG_MD4 ? 16 : \
677 (alg) == PSA_ALG_MD5 ? 16 : \
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100678 (alg) == PSA_ALG_RIPEMD160 ? 20 : \
679 (alg) == PSA_ALG_SHA_1 ? 20 : \
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100680 (alg) == PSA_ALG_SHA_224 ? 28 : \
681 (alg) == PSA_ALG_SHA_256 ? 32 : \
682 (alg) == PSA_ALG_SHA_384 ? 48 : \
683 (alg) == PSA_ALG_SHA_512 ? 64 : \
684 (alg) == PSA_ALG_SHA_512_224 ? 28 : \
685 (alg) == PSA_ALG_SHA_512_256 ? 32 : \
686 (alg) == PSA_ALG_SHA3_224 ? 28 : \
687 (alg) == PSA_ALG_SHA3_256 ? 32 : \
688 (alg) == PSA_ALG_SHA3_384 ? 48 : \
689 (alg) == PSA_ALG_SHA3_512 ? 64 : \
690 0)
691
Gilles Peskine308b91d2018-02-08 09:47:44 +0100692/** Start a multipart hash operation.
693 *
694 * The sequence of operations to calculate a hash (message digest)
695 * is as follows:
696 * -# Allocate an operation object which will be passed to all the functions
697 * listed here.
698 * -# Call psa_hash_start() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100699 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100700 * of the message each time. The hash that is calculated is the hash
701 * of the concatenation of these messages in order.
702 * -# To calculate the hash, call psa_hash_finish().
703 * To compare the hash with an expected value, call psa_hash_verify().
704 *
705 * The application may call psa_hash_abort() at any time after the operation
706 * has been initialized with psa_hash_start().
707 *
708 * After a successful call to psa_hash_start(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100709 * eventually terminate the operation. The following events terminate an
710 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100711 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100712 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100713 *
714 * \param operation
715 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
716 * such that #PSA_ALG_IS_HASH(alg) is true).
717 *
718 * \retval PSA_SUCCESS
719 * Success.
720 * \retval PSA_ERROR_NOT_SUPPORTED
721 * \c alg is not supported or is not a hash algorithm.
722 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
723 * \retval PSA_ERROR_COMMUNICATION_FAILURE
724 * \retval PSA_ERROR_HARDWARE_FAILURE
725 * \retval PSA_ERROR_TAMPERING_DETECTED
726 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100727psa_status_t psa_hash_start(psa_hash_operation_t *operation,
728 psa_algorithm_t alg);
729
Gilles Peskine308b91d2018-02-08 09:47:44 +0100730/** Add a message fragment to a multipart hash operation.
731 *
732 * The application must call psa_hash_start() before calling this function.
733 *
734 * If this function returns an error status, the operation becomes inactive.
735 *
736 * \param operation Active hash operation.
737 * \param input Buffer containing the message fragment to hash.
738 * \param input_length Size of the \c input buffer in bytes.
739 *
740 * \retval PSA_SUCCESS
741 * Success.
742 * \retval PSA_ERROR_BAD_STATE
743 * The operation state is not valid (not started, or already completed).
744 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
745 * \retval PSA_ERROR_COMMUNICATION_FAILURE
746 * \retval PSA_ERROR_HARDWARE_FAILURE
747 * \retval PSA_ERROR_TAMPERING_DETECTED
748 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100749psa_status_t psa_hash_update(psa_hash_operation_t *operation,
750 const uint8_t *input,
751 size_t input_length);
752
Gilles Peskine308b91d2018-02-08 09:47:44 +0100753/** Finish the calculation of the hash of a message.
754 *
755 * The application must call psa_hash_start() before calling this function.
756 * This function calculates the hash of the message formed by concatenating
757 * the inputs passed to preceding calls to psa_hash_update().
758 *
759 * When this function returns, the operation becomes inactive.
760 *
761 * \warning Applications should not call this function if they expect
762 * a specific value for the hash. Call psa_hash_verify() instead.
763 * Beware that comparing integrity or authenticity data such as
764 * hash values with a function such as \c memcmp is risky
765 * because the time taken by the comparison may leak information
766 * about the hashed data which could allow an attacker to guess
767 * a valid hash and thereby bypass security controls.
768 *
769 * \param operation Active hash operation.
770 * \param hash Buffer where the hash is to be written.
771 * \param hash_size Size of the \c hash buffer in bytes.
772 * \param hash_length On success, the number of bytes
773 * that make up the hash value. This is always
774 * #PSA_HASH_FINAL_SIZE(alg) where \c alg is the
775 * hash algorithm that is calculated.
776 *
777 * \retval PSA_SUCCESS
778 * Success.
779 * \retval PSA_ERROR_BAD_STATE
780 * The operation state is not valid (not started, or already completed).
781 * \retval PSA_ERROR_BUFFER_TOO_SMALL
782 * The size of the \c hash buffer is too small. You can determine a
783 * sufficient buffer size by calling #PSA_HASH_FINAL_SIZE(alg)
784 * where \c alg is the hash algorithm that is calculated.
785 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
786 * \retval PSA_ERROR_COMMUNICATION_FAILURE
787 * \retval PSA_ERROR_HARDWARE_FAILURE
788 * \retval PSA_ERROR_TAMPERING_DETECTED
789 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100790psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
791 uint8_t *hash,
792 size_t hash_size,
793 size_t *hash_length);
794
Gilles Peskine308b91d2018-02-08 09:47:44 +0100795/** Finish the calculation of the hash of a message and compare it with
796 * an expected value.
797 *
798 * The application must call psa_hash_start() before calling this function.
799 * This function calculates the hash of the message formed by concatenating
800 * the inputs passed to preceding calls to psa_hash_update(). It then
801 * compares the calculated hash with the expected hash passed as a
802 * parameter to this function.
803 *
804 * When this function returns, the operation becomes inactive.
805 *
Gilles Peskine19067982018-03-20 17:54:53 +0100806 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +0100807 * comparison between the actual hash and the expected hash is performed
808 * in constant time.
809 *
810 * \param operation Active hash operation.
811 * \param hash Buffer containing the expected hash value.
812 * \param hash_length Size of the \c hash buffer in bytes.
813 *
814 * \retval PSA_SUCCESS
815 * The expected hash is identical to the actual hash of the message.
816 * \retval PSA_ERROR_INVALID_SIGNATURE
817 * The hash of the message was calculated successfully, but it
818 * differs from the expected hash.
819 * \retval PSA_ERROR_BAD_STATE
820 * The operation state is not valid (not started, or already completed).
821 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
822 * \retval PSA_ERROR_COMMUNICATION_FAILURE
823 * \retval PSA_ERROR_HARDWARE_FAILURE
824 * \retval PSA_ERROR_TAMPERING_DETECTED
825 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100826psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
827 const uint8_t *hash,
828 size_t hash_length);
829
Gilles Peskine308b91d2018-02-08 09:47:44 +0100830/** Abort a hash operation.
831 *
832 * This function may be called at any time after psa_hash_start().
833 * Aborting an operation frees all associated resources except for the
834 * \c operation structure itself.
835 *
836 * Implementation should strive to be robust and handle inactive hash
837 * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However,
838 * application writers should beware that uninitialized memory may happen
839 * to be indistinguishable from an active hash operation, and the behavior
840 * of psa_hash_abort() is undefined in this case.
841 *
842 * \param operation Active hash operation.
843 *
844 * \retval PSA_SUCCESS
845 * \retval PSA_ERROR_BAD_STATE
846 * \c operation is not an active hash operation.
847 * \retval PSA_ERROR_COMMUNICATION_FAILURE
848 * \retval PSA_ERROR_HARDWARE_FAILURE
849 * \retval PSA_ERROR_TAMPERING_DETECTED
850 */
851psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100852
853/**@}*/
854
Gilles Peskine8c9def32018-02-08 10:02:12 +0100855/** \defgroup MAC Message authentication codes
856 * @{
857 */
858
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100859/** The type of the state data structure for multipart MAC operations.
860 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100861 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100862 * make any assumptions about the content of this structure except
863 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100864typedef struct psa_mac_operation_s psa_mac_operation_t;
865
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100866/** The size of the output of psa_mac_finish(), in bytes.
867 *
868 * This is also the MAC size that psa_mac_verify() expects.
869 *
870 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
871 * #PSA_ALG_IS_MAC(alg) is true).
872 *
873 * \return The MAC size for the specified algorithm.
874 * If the MAC algorithm is not recognized, return 0.
875 * An implementation may return either 0 or the correct size
876 * for a MAC algorithm that it recognizes, but does not support.
877 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100878#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
879 (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_FINAL_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
880 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
881 0)
882
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100883/** Start a multipart MAC operation.
884 *
885 * The sequence of operations to calculate a MAC (message authentication code)
886 * is as follows:
887 * -# Allocate an operation object which will be passed to all the functions
888 * listed here.
889 * -# Call psa_mac_start() 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_mac_update() zero, one or more times, passing a fragment
893 * of the message each time. The MAC that is calculated is the MAC
894 * of the concatenation of these messages in order.
895 * -# To calculate the MAC, call psa_mac_finish().
896 * To compare the MAC with an expected value, call psa_mac_verify().
897 *
898 * The application may call psa_mac_abort() at any time after the operation
899 * has been initialized with psa_mac_start().
900 *
901 * After a successful call to psa_mac_start(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100902 * eventually terminate the operation. The following events terminate an
903 * operation:
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100904 * - A failed call to psa_mac_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100905 * - A call to psa_mac_finish(), psa_mac_verify() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100906 *
907 * \param operation
908 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
909 * such that #PSA_ALG_IS_MAC(alg) is true).
910 *
911 * \retval PSA_SUCCESS
912 * Success.
913 * \retval PSA_ERROR_EMPTY_SLOT
Gilles Peskine92b30732018-03-03 21:29:30 +0100914 * \retval PSA_ERROR_NOT_PERMITTED
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100915 * \retval PSA_ERROR_INVALID_ARGUMENT
916 * \c key is not compatible with \c alg.
917 * \retval PSA_ERROR_NOT_SUPPORTED
918 * \c alg is not supported or is not a MAC algorithm.
919 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
920 * \retval PSA_ERROR_COMMUNICATION_FAILURE
921 * \retval PSA_ERROR_HARDWARE_FAILURE
922 * \retval PSA_ERROR_TAMPERING_DETECTED
923 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100924psa_status_t psa_mac_start(psa_mac_operation_t *operation,
925 psa_key_slot_t key,
926 psa_algorithm_t alg);
927
928psa_status_t psa_mac_update(psa_mac_operation_t *operation,
929 const uint8_t *input,
930 size_t input_length);
931
932psa_status_t psa_mac_finish(psa_mac_operation_t *operation,
933 uint8_t *mac,
934 size_t mac_size,
935 size_t *mac_length);
936
937psa_status_t psa_mac_verify(psa_mac_operation_t *operation,
938 const uint8_t *mac,
939 size_t mac_length);
940
941psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
942
943/**@}*/
944
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100945/** \defgroup cipher Symmetric ciphers
946 * @{
947 */
948
949/** The type of the state data structure for multipart cipher operations.
950 *
951 * This is an implementation-defined \c struct. Applications should not
952 * make any assumptions about the content of this structure except
953 * as directed by the documentation of a specific implementation. */
954typedef struct psa_cipher_operation_s psa_cipher_operation_t;
955
956/** Set the key for a multipart symmetric encryption operation.
957 *
958 * The sequence of operations to encrypt a message with a symmetric cipher
959 * is as follows:
960 * -# Allocate an operation object which will be passed to all the functions
961 * listed here.
962 * -# Call psa_encrypt_setup() to specify the algorithm and key.
963 * The key remains associated with the operation even if the content
964 * of the key slot changes.
965 * -# Call either psa_encrypt_generate_iv() or psa_encrypt_set_iv() to
966 * generate or set the IV (initialization vector). You should use
967 * psa_encrypt_generate_iv() unless the protocol you are implementing
968 * requires a specific IV value.
969 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
970 * of the message each time.
971 * -# Call psa_cipher_finish().
972 *
973 * The application may call psa_cipher_abort() at any time after the operation
974 * has been initialized with psa_encrypt_setup().
975 *
976 * After a successful call to psa_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100977 * eventually terminate the operation. The following events terminate an
978 * operation:
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100979 * - A failed call to psa_encrypt_generate_iv(), psa_encrypt_set_iv()
980 * or psa_cipher_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100981 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100982 *
983 * \param operation
984 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
985 * such that #PSA_ALG_IS_CIPHER(alg) is true).
986 *
987 * \retval PSA_SUCCESS
988 * Success.
989 * \retval PSA_ERROR_EMPTY_SLOT
990 * \retval PSA_ERROR_NOT_PERMITTED
991 * \retval PSA_ERROR_INVALID_ARGUMENT
992 * \c key is not compatible with \c alg.
993 * \retval PSA_ERROR_NOT_SUPPORTED
994 * \c alg is not supported or is not a cipher algorithm.
995 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
996 * \retval PSA_ERROR_COMMUNICATION_FAILURE
997 * \retval PSA_ERROR_HARDWARE_FAILURE
998 * \retval PSA_ERROR_TAMPERING_DETECTED
999 */
1000psa_status_t psa_encrypt_setup(psa_cipher_operation_t *operation,
1001 psa_key_slot_t key,
1002 psa_algorithm_t alg);
1003
1004/** Set the key for a multipart symmetric decryption operation.
1005 *
1006 * The sequence of operations to decrypt a message with a symmetric cipher
1007 * is as follows:
1008 * -# Allocate an operation object which will be passed to all the functions
1009 * listed here.
1010 * -# Call psa_decrypt_setup() to specify the algorithm and key.
1011 * The key remains associated with the operation even if the content
1012 * of the key slot changes.
1013 * -# Call psa_cipher_update() with the IV (initialization vector) for the
1014 * decryption. If the IV is prepended to the ciphertext, you can call
1015 * psa_cipher_update() on a buffer containing the IV followed by the
1016 * beginning of the message.
1017 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1018 * of the message each time.
1019 * -# Call psa_cipher_finish().
1020 *
1021 * The application may call psa_cipher_abort() at any time after the operation
1022 * has been initialized with psa_encrypt_setup().
1023 *
1024 * After a successful call to psa_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001025 * eventually terminate the operation. The following events terminate an
1026 * operation:
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001027 * - A failed call to psa_cipher_update().
Gilles Peskine19067982018-03-20 17:54:53 +01001028 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001029 *
1030 * \param operation
1031 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
1032 * such that #PSA_ALG_IS_CIPHER(alg) is true).
1033 *
1034 * \retval PSA_SUCCESS
1035 * Success.
1036 * \retval PSA_ERROR_EMPTY_SLOT
1037 * \retval PSA_ERROR_NOT_PERMITTED
1038 * \retval PSA_ERROR_INVALID_ARGUMENT
1039 * \c key is not compatible with \c alg.
1040 * \retval PSA_ERROR_NOT_SUPPORTED
1041 * \c alg is not supported or is not a cipher algorithm.
1042 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1043 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1044 * \retval PSA_ERROR_HARDWARE_FAILURE
1045 * \retval PSA_ERROR_TAMPERING_DETECTED
1046 */
1047psa_status_t psa_decrypt_setup(psa_cipher_operation_t *operation,
1048 psa_key_slot_t key,
1049 psa_algorithm_t alg);
1050
1051psa_status_t psa_encrypt_generate_iv(psa_cipher_operation_t *operation,
1052 unsigned char *iv,
1053 size_t iv_size,
1054 size_t *iv_length);
1055
1056psa_status_t psa_encrypt_set_iv(psa_cipher_operation_t *operation,
1057 const unsigned char *iv,
1058 size_t iv_length);
1059
1060psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1061 const uint8_t *input,
1062 size_t input_length);
1063
1064psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
1065 uint8_t *mac,
1066 size_t mac_size,
1067 size_t *mac_length);
1068
1069psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
1070
1071/**@}*/
1072
Gilles Peskine3b555712018-03-03 21:27:57 +01001073/** \defgroup aead Authenticated encryption with associated data (AEAD)
1074 * @{
1075 */
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001076
1077#define PSA_AEAD_ENCRYPT_OUTPUT_SIZE(alg, plaintext_length) \
1078 ((alg) == PSA_ALG_GCM ? (plaintext_length) + 16 : \
1079 (alg) == PSA_ALG_CCM ? (plaintext_length) + 16 : \
1080 0)
1081
1082/** Process an authenticated encryption operation.
Gilles Peskine3b555712018-03-03 21:27:57 +01001083 *
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001084 * \param key Slot containing the key to use.
1085 * \param alg The AEAD algorithm to compute
1086 * (\c PSA_ALG_XXX value such that
1087 * #PSA_ALG_IS_AEAD(alg) is true).
1088 * \param nonce Nonce or IV to use.
1089 * \param nonce_length Size of the \p nonce buffer in bytes.
1090 * \param additional_data Additional data that will be authenticated
1091 * but not encrypted.
1092 * \param additional_data_length Size of \p additional_data in bytes.
1093 * \param plaintext Data that will be authenticated and
1094 * encrypted.
1095 * \param plaintext_length Size of \p plaintext in bytes.
1096 * \param ciphertext Output buffer for the authenticated and
1097 * encrypted data. The additional data is not
1098 * part of this output. For algorithms where the
1099 * encrypted data and the authentication tag
1100 * are defined as separate outputs, the
1101 * authentication tag is appended to the
1102 * encrypted data.
1103 * \param ciphertext_size Size of the \p ciphertext buffer in bytes.
1104 * This must be at least
1105 * #PSA_AEAD_ENCRYPT_OUTPUT_SIZE(\p alg,
1106 * \p plaintext_length).
1107 * \param ciphertext_length On success, the size of the output
1108 * in the \b ciphertext buffer.
Gilles Peskine3b555712018-03-03 21:27:57 +01001109 *
1110 * \retval PSA_SUCCESS
1111 * Success.
1112 * \retval PSA_ERROR_EMPTY_SLOT
1113 * \retval PSA_ERROR_NOT_PERMITTED
1114 * \retval PSA_ERROR_INVALID_ARGUMENT
1115 * \c key is not compatible with \c alg.
1116 * \retval PSA_ERROR_NOT_SUPPORTED
Gilles Peskine19067982018-03-20 17:54:53 +01001117 * \c alg is not supported or is not an AEAD algorithm.
Gilles Peskine3b555712018-03-03 21:27:57 +01001118 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1119 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1120 * \retval PSA_ERROR_HARDWARE_FAILURE
1121 * \retval PSA_ERROR_TAMPERING_DETECTED
1122 */
mohammad160339ee8712018-04-26 00:51:02 +03001123psa_status_t psa_aead_encrypt( psa_key_slot_t key,
1124 psa_algorithm_t alg,
1125 const uint8_t *nonce,
1126 size_t nonce_length,
1127 const uint8_t *additional_data,
1128 size_t additional_data_length,
1129 const uint8_t *plaintext,
1130 size_t plaintext_length,
1131 uint8_t *ciphertext,
1132 size_t ciphertext_size,
1133 size_t *ciphertext_length );
Gilles Peskine3b555712018-03-03 21:27:57 +01001134
Gilles Peskine1e7d8f12018-06-01 16:29:38 +02001135#define PSA_AEAD_DECRYPT_OUTPUT_SIZE(alg, ciphertext_length) \
1136 ((alg) == PSA_ALG_GCM ? (ciphertext_length) - 16 : \
1137 (alg) == PSA_ALG_CCM ? (ciphertext_length) - 16 : \
1138 0)
1139
1140/** Process an authenticated decryption operation.
1141 *
1142 * \param key Slot containing the key to use.
1143 * \param alg The AEAD algorithm to compute
1144 * (\c PSA_ALG_XXX value such that
1145 * #PSA_ALG_IS_AEAD(alg) is true).
1146 * \param nonce Nonce or IV to use.
1147 * \param nonce_length Size of the \p nonce buffer in bytes.
1148 * \param additional_data Additional data that has been authenticated
1149 * but not encrypted.
1150 * \param additional_data_length Size of \p additional_data in bytes.
1151 * \param ciphertext Data that has been authenticated and
1152 * encrypted. For algorithms where the
1153 * encrypted data and the authentication tag
1154 * are defined as separate inputs, the buffer
1155 * must contain the encrypted data followed
1156 * by the authentication tag.
1157 * \param ciphertext_length Size of \p ciphertext in bytes.
1158 * \param plaintext Output buffer for the decrypted data.
1159 * \param plaintext_size Size of the \p plaintext buffer in bytes.
1160 * This must be at least
1161 * #PSA_AEAD_DECRYPT_OUTPUT_SIZE(\p alg,
1162 * \p ciphertext_length).
1163 * \param plaintext_length On success, the size of the output
1164 * in the \b plainrtext buffer.
1165 *
1166 * \retval PSA_SUCCESS
1167 * Success.
1168 * \retval PSA_ERROR_EMPTY_SLOT
1169 * \retval PSA_ERROR_INVALID_SIGNATURE
1170 * The ciphertext is not authentic.
1171 * \retval PSA_ERROR_NOT_PERMITTED
1172 * \retval PSA_ERROR_INVALID_ARGUMENT
1173 * \c key is not compatible with \c alg.
1174 * \retval PSA_ERROR_NOT_SUPPORTED
1175 * \c alg is not supported or is not an AEAD algorithm.
1176 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1177 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1178 * \retval PSA_ERROR_HARDWARE_FAILURE
1179 * \retval PSA_ERROR_TAMPERING_DETECTED
1180 */
mohammad160339ee8712018-04-26 00:51:02 +03001181psa_status_t psa_aead_decrypt( psa_key_slot_t key,
1182 psa_algorithm_t alg,
1183 const uint8_t *nonce,
1184 size_t nonce_length,
1185 const uint8_t *additional_data,
1186 size_t additional_data_length,
1187 const uint8_t *ciphertext,
1188 size_t ciphertext_length,
1189 uint8_t *plaintext,
1190 size_t plaintext_size,
1191 size_t *plaintext_length );
Gilles Peskine3b555712018-03-03 21:27:57 +01001192
1193/**@}*/
1194
Gilles Peskine20035e32018-02-03 22:44:14 +01001195/** \defgroup asymmetric Asymmetric cryptography
1196 * @{
1197 */
1198
1199/**
Gilles Peskine0189e752018-02-03 23:57:22 +01001200 * \brief Maximum ECDSA signature size for a given curve bit size
1201 *
1202 * \param curve_bits Curve size in bits
1203 * \return Maximum signature size in bytes
1204 *
1205 * \note This macro returns a compile-time constant if its argument is one.
1206 *
1207 * \warning This macro may evaluate its argument multiple times.
1208 */
1209/*
1210 * RFC 4492 page 20:
1211 *
1212 * Ecdsa-Sig-Value ::= SEQUENCE {
1213 * r INTEGER,
1214 * s INTEGER
1215 * }
1216 *
1217 * Size is at most
1218 * 1 (tag) + 1 (len) + 1 (initial 0) + curve_bytes for each of r and s,
1219 * twice that + 1 (tag) + 2 (len) for the sequence
1220 * (assuming curve_bytes is less than 126 for r and s,
1221 * and less than 124 (total len <= 255) for the sequence)
1222 */
1223#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
1224 ( /*T,L of SEQUENCE*/ ((curve_bits) >= 61 * 8 ? 3 : 2) + \
1225 /*T,L of r,s*/ 2 * (((curve_bits) >= 127 * 8 ? 3 : 2) + \
1226 /*V of r,s*/ ((curve_bits) + 8) / 8))
1227
1228
Gilles Peskine308b91d2018-02-08 09:47:44 +01001229/** Safe signature buffer size for psa_asymmetric_sign().
1230 *
1231 * This macro returns a safe buffer size for a signature using a key
1232 * of the specified type and size, with the specified algorithm.
1233 * Note that the actual size of the signature may be smaller
1234 * (some algorithms produce a variable-size signature).
1235 *
1236 * \warning This function may call its arguments multiple times or
1237 * zero times, so you should not pass arguments that contain
1238 * side effects.
1239 *
1240 * \param key_type An asymmetric key type (this may indifferently be a
1241 * key pair type or a public key type).
1242 * \param key_bits The size of the key in bits.
1243 * \param alg The signature algorithm.
1244 *
1245 * \return If the parameters are valid and supported, return
1246 * a buffer size in bytes that guarantees that
1247 * psa_asymmetric_sign() will not fail with
1248 * #PSA_ERROR_BUFFER_TOO_SMALL.
1249 * If the parameters are a valid combination that is not supported
1250 * by the implementation, this macro either shall return either a
1251 * sensible size or 0.
1252 * If the parameters are not valid, the
1253 * return value is unspecified.
1254 *
1255 */
Gilles Peskine0189e752018-02-03 23:57:22 +01001256#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
Gilles Peskine2905a7a2018-03-07 16:39:31 +01001257 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
Gilles Peskine0189e752018-02-03 23:57:22 +01001258 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
Gilles Peskine84845652018-03-28 14:17:40 +02001259 ((void)alg, 0))
Gilles Peskine0189e752018-02-03 23:57:22 +01001260
1261/**
Gilles Peskine20035e32018-02-03 22:44:14 +01001262 * \brief Sign a hash or short message with a private key.
1263 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001264 * \param key Key slot containing an asymmetric key pair.
1265 * \param alg A signature algorithm that is compatible with
1266 * the type of \c key.
1267 * \param hash The message to sign.
1268 * \param hash_length Size of the \c hash buffer in bytes.
1269 * \param salt A salt or label, if supported by the signature
1270 * algorithm.
1271 * If the signature algorithm does not support a
1272 * salt, pass \c NULL.
1273 * If the signature algorithm supports an optional
1274 * salt and you do not want to pass a salt,
1275 * pass \c NULL.
1276 * \param salt_length Size of the \c salt buffer in bytes.
1277 * If \c salt is \c NULL, pass 0.
1278 * \param signature Buffer where the signature is to be written.
1279 * \param signature_size Size of the \c signature buffer in bytes.
1280 * \param signature_length On success, the number of bytes
1281 * that make up the returned signature value.
Gilles Peskine308b91d2018-02-08 09:47:44 +01001282 *
1283 * \retval PSA_SUCCESS
1284 * \retval PSA_ERROR_BUFFER_TOO_SMALL
1285 * The size of the \c signature buffer is too small. You can
1286 * determine a sufficient buffer size by calling
1287 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
1288 * where \c key_type and \c key_bits are the type and bit-size
1289 * respectively of \c key.
1290 * \retval PSA_ERROR_NOT_SUPPORTED
1291 * \retval PSA_ERROR_INVALID_ARGUMENT
1292 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1293 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1294 * \retval PSA_ERROR_HARDWARE_FAILURE
1295 * \retval PSA_ERROR_TAMPERING_DETECTED
1296 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskine20035e32018-02-03 22:44:14 +01001297 */
1298psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
1299 psa_algorithm_t alg,
1300 const uint8_t *hash,
1301 size_t hash_length,
1302 const uint8_t *salt,
1303 size_t salt_length,
1304 uint8_t *signature,
1305 size_t signature_size,
1306 size_t *signature_length);
1307
1308/**
1309 * \brief Verify the signature a hash or short message using a public key.
1310 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001311 * \param key Key slot containing a public key or an
1312 * asymmetric key pair.
1313 * \param alg A signature algorithm that is compatible with
1314 * the type of \c key.
1315 * \param hash The message whose signature is to be verified.
1316 * \param hash_length Size of the \c hash buffer in bytes.
1317 * \param salt A salt or label, if supported by the signature
1318 * algorithm.
1319 * If the signature algorithm does not support a
1320 * salt, pass \c NULL.
1321 * If the signature algorithm supports an optional
1322 * salt and you do not want to pass a salt,
1323 * pass \c NULL.
1324 * \param salt_length Size of the \c salt buffer in bytes.
1325 * If \c salt is \c NULL, pass 0.
1326 * \param signature Buffer containing the signature to verify.
1327 * \param signature_size Size of the \c signature buffer in bytes.
1328 *
1329 * \retval PSA_SUCCESS
1330 * The signature is valid.
1331 * \retval PSA_ERROR_INVALID_SIGNATURE
1332 * The calculation was perfomed successfully, but the passed
1333 * signature is not a valid signature.
1334 * \retval PSA_ERROR_NOT_SUPPORTED
1335 * \retval PSA_ERROR_INVALID_ARGUMENT
1336 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1337 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1338 * \retval PSA_ERROR_HARDWARE_FAILURE
1339 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine20035e32018-02-03 22:44:14 +01001340 */
1341psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
1342 psa_algorithm_t alg,
1343 const uint8_t *hash,
1344 size_t hash_length,
1345 const uint8_t *salt,
1346 size_t salt_length,
1347 uint8_t *signature,
1348 size_t signature_size);
1349
Gilles Peskine6944f9a2018-03-28 14:18:39 +02001350#define PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
Gilles Peskine06297932018-04-11 16:58:22 +02001351 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
1352 ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
1353 0)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02001354#define PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg) \
Gilles Peskine06297932018-04-11 16:58:22 +02001355 (PSA_KEY_TYPE_IS_RSA(key_type) ? \
1356 PSA_BITS_TO_BYTES(key_bits) - ((alg) == PSA_ALG_IS_RSA_OAEP_MGF1 ? \
1357 2 * (PSA_ALG_RSA_GET_HASH(alg) + 1) : \
1358 11 /*PKCS#1v1.5*/) : \
1359 0)
Gilles Peskine6944f9a2018-03-28 14:18:39 +02001360
1361/**
1362 * \brief Encrypt a short message with a public key.
1363 *
1364 * \param key Key slot containing a public key or an asymmetric
1365 * key pair.
1366 * \param alg An asymmetric encryption algorithm that is
1367 * compatible with the type of \c key.
1368 * \param input The message to encrypt.
1369 * \param input_length Size of the \c input buffer in bytes.
1370 * \param salt A salt or label, if supported by the encryption
1371 * algorithm.
1372 * If the algorithm does not support a
1373 * salt, pass \c NULL.
1374 * If the algorithm supports an optional
1375 * salt and you do not want to pass a salt,
1376 * pass \c NULL.
1377 *
1378 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
1379 * supported.
1380 * \param salt_length Size of the \c salt buffer in bytes.
1381 * If \c salt is \c NULL, pass 0.
1382 * \param output Buffer where the encrypted message is to be written.
1383 * \param output_size Size of the \c output buffer in bytes.
1384 * \param output_length On success, the number of bytes
1385 * that make up the returned output.
1386 *
1387 * \retval PSA_SUCCESS
1388 * \retval PSA_ERROR_BUFFER_TOO_SMALL
1389 * The size of the \c output buffer is too small. You can
1390 * determine a sufficient buffer size by calling
1391 * #PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE(key_type, key_bits, alg)
1392 * where \c key_type and \c key_bits are the type and bit-size
1393 * respectively of \c key.
1394 * \retval PSA_ERROR_NOT_SUPPORTED
1395 * \retval PSA_ERROR_INVALID_ARGUMENT
1396 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1397 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1398 * \retval PSA_ERROR_HARDWARE_FAILURE
1399 * \retval PSA_ERROR_TAMPERING_DETECTED
1400 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
1401 */
1402psa_status_t psa_asymmetric_encrypt(psa_key_slot_t key,
1403 psa_algorithm_t alg,
1404 const uint8_t *input,
1405 size_t input_length,
1406 const uint8_t *salt,
1407 size_t salt_length,
1408 uint8_t *output,
1409 size_t output_size,
1410 size_t *output_length);
1411
1412/**
1413 * \brief Decrypt a short message with a private key.
1414 *
1415 * \param key Key slot containing an asymmetric key pair.
1416 * \param alg An asymmetric encryption algorithm that is
1417 * compatible with the type of \c key.
1418 * \param input The message to decrypt.
1419 * \param input_length Size of the \c input buffer in bytes.
1420 * \param salt A salt or label, if supported by the encryption
1421 * algorithm.
1422 * If the algorithm does not support a
1423 * salt, pass \c NULL.
1424 * If the algorithm supports an optional
1425 * salt and you do not want to pass a salt,
1426 * pass \c NULL.
1427 *
1428 * - For #PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is
1429 * supported.
1430 * \param salt_length Size of the \c salt buffer in bytes.
1431 * If \c salt is \c NULL, pass 0.
Gilles Peskinef48af7f2018-03-28 18:44:14 +02001432 * \param output Buffer where the decrypted message is to be written.
Gilles Peskine6944f9a2018-03-28 14:18:39 +02001433 * \param output_size Size of the \c output buffer in bytes.
1434 * \param output_length On success, the number of bytes
1435 * that make up the returned output.
1436 *
1437 * \retval PSA_SUCCESS
1438 * \retval PSA_ERROR_BUFFER_TOO_SMALL
1439 * The size of the \c output buffer is too small. You can
1440 * determine a sufficient buffer size by calling
1441 * #PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE(key_type, key_bits, alg)
1442 * where \c key_type and \c key_bits are the type and bit-size
1443 * respectively of \c key.
1444 * \retval PSA_ERROR_NOT_SUPPORTED
1445 * \retval PSA_ERROR_INVALID_ARGUMENT
1446 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1447 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1448 * \retval PSA_ERROR_HARDWARE_FAILURE
1449 * \retval PSA_ERROR_TAMPERING_DETECTED
1450 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
1451 * \retval PSA_ERROR_INVALID_PADDING
1452 */
1453psa_status_t psa_asymmetric_decrypt(psa_key_slot_t key,
1454 psa_algorithm_t alg,
1455 const uint8_t *input,
1456 size_t input_length,
1457 const uint8_t *salt,
1458 size_t salt_length,
1459 uint8_t *output,
1460 size_t output_size,
1461 size_t *output_length);
1462
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01001463/**@}*/
1464
Gilles Peskine9e7dc712018-03-28 14:18:50 +02001465/** \defgroup generation Key generation
1466 * @{
1467 */
1468
1469/**
1470 * \brief Generate random bytes.
1471 *
1472 * \warning This function **can** fail! Callers MUST check the return status
1473 * and MUST NOT use the content of the output buffer if the return
1474 * status is not #PSA_SUCCESS.
1475 *
1476 * \note To generate a key, use psa_generate_key() instead.
1477 *
1478 * \param output Output buffer for the generated data.
1479 * \param output_size Number of bytes to generate and output.
1480 *
1481 * \retval PSA_SUCCESS
1482 * \retval PSA_ERROR_NOT_SUPPORTED
1483 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
1484 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1485 * \retval PSA_ERROR_HARDWARE_FAILURE
1486 * \retval PSA_ERROR_TAMPERING_DETECTED
1487 */
1488psa_status_t psa_generate_random(uint8_t *output,
1489 size_t output_size);
1490
1491/**
1492 * \brief Generate a key or key pair.
1493 *
1494 * \param key Slot where the key will be stored. This must be a
1495 * valid slot for a key of the chosen type. It must
1496 * be unoccupied.
1497 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
1498 * \param bits Key size in bits.
1499 * \param parameters Extra parameters for key generation. The interpretation
1500 * of this parameter depends on \c type. All types support
1501 * \c NULL to use default parameters specified below.
1502 *
1503 * For any symmetric key type (type such that
1504 * `PSA_KEY_TYPE_IS_ASYMMETRIC(type)` is false), \c parameters must be
1505 * \c NULL. For asymmetric key types defined by this specification,
1506 * the parameter type and the default parameters are defined by the
1507 * table below. For vendor-defined key types, the vendor documentation
1508 * shall define the parameter type and the default parameters.
1509 *
Gilles Peskinef48af7f2018-03-28 18:44:14 +02001510 * Type | Parameter type | Meaning | Parameters used if `parameters == NULL`
1511 * ---- | -------------- | ------- | ---------------------------------------
1512 * `PSA_KEY_TYPE_RSA_KEYPAIR` | `unsigned int` | Public exponent | 65537
Gilles Peskine9e7dc712018-03-28 14:18:50 +02001513 *
1514 * \retval PSA_SUCCESS
1515 * \retval PSA_ERROR_NOT_SUPPORTED
1516 * \retval PSA_ERROR_INVALID_ARGUMENT
1517 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1518 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
1519 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1520 * \retval PSA_ERROR_HARDWARE_FAILURE
1521 * \retval PSA_ERROR_TAMPERING_DETECTED
1522 */
1523psa_status_t psa_generate_key(psa_key_slot_t key,
1524 psa_key_type_t type,
1525 size_t bits,
1526 const void *parameters);
1527
1528/**@}*/
1529
Gilles Peskinee59236f2018-01-27 23:32:46 +01001530#ifdef __cplusplus
1531}
1532#endif
1533
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001534/* The file "crypto_struct.h" contains definitions for
1535 * implementation-specific structs that are declared above. */
1536#include "crypto_struct.h"
1537
1538/* The file "crypto_extra.h" contains vendor-specific definitions. This
1539 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01001540#include "crypto_extra.h"
1541
1542#endif /* PSA_CRYPTO_H */