blob: 6caa62abf83f61245a1d978cc61219f40d5ed90a [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,
mohammad1603804cd712018-03-20 22:44:08 +020092 /** The key lifetime value is incorrect. */
93 PSA_ERROR_INVALID_LIFETIME,
94 /** The key lifetime can not be changed. */
95 PSA_ERROR_KEY_LIFETIME_CHANGE,
Gilles Peskinee59236f2018-01-27 23:32:46 +010096 /** An error occurred that does not correspond to any defined
97 failure cause. */
98 PSA_ERROR_UNKNOWN_ERROR,
99} psa_status_t;
100
101/**
102 * \brief Library initialization.
103 *
104 * Applications must call this function before calling any other
105 * function in this module.
106 *
107 * Applications may call this function more than once. Once a call
108 * succeeds, subsequent calls are guaranteed to succeed.
109 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100110 * \retval PSA_SUCCESS
111 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
112 * \retval PSA_ERROR_COMMUNICATION_FAILURE
113 * \retval PSA_ERROR_HARDWARE_FAILURE
114 * \retval PSA_ERROR_TAMPERING_DETECTED
115 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskinee59236f2018-01-27 23:32:46 +0100116 */
117psa_status_t psa_crypto_init(void);
118
Gilles Peskine2905a7a2018-03-07 16:39:31 +0100119#define PSA_BITS_TO_BYTES(bits) (((bits) + 7) / 8)
120#define PSA_BYTES_TO_BITS(bytes) ((bytes) * 8)
Gilles Peskine0189e752018-02-03 23:57:22 +0100121
Gilles Peskinee59236f2018-01-27 23:32:46 +0100122/**@}*/
123
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100124/** \defgroup crypto_types Key and algorithm types
125 * @{
126 */
127
Gilles Peskine308b91d2018-02-08 09:47:44 +0100128/** \brief Encoding of a key type.
129 */
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100130typedef uint32_t psa_key_type_t;
131
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100132/** An invalid key type value.
133 *
134 * Zero is not the encoding of any key type.
135 */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100136#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000)
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100137
138/** Vendor-defined flag
139 *
140 * Key types defined by this standard will never have the
141 * #PSA_KEY_TYPE_VENDOR_FLAG bit set. Vendors who define additional key types
142 * must use an encoding with the #PSA_KEY_TYPE_VENDOR_FLAG bit set and should
143 * respect the bitwise structure used by standard encodings whenever practical.
144 */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100145#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100146
Gilles Peskine98f0a242018-02-06 18:57:29 +0100147#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000)
148#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x02000000)
149#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x04000000)
150#define PSA_KEY_TYPE_CATEGORY_ASYMMETRIC ((psa_key_type_t)0x06000000)
151#define PSA_KEY_TYPE_PAIR_FLAG ((psa_key_type_t)0x01000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100152
Gilles Peskine98f0a242018-02-06 18:57:29 +0100153#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001)
154#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x04000001)
155#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x04000002)
156#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003)
157#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x04000004)
158
Gilles Peskine308b91d2018-02-08 09:47:44 +0100159/** RSA public key. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100160#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x06010000)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100161/** RSA key pair (private and public key). */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100162#define PSA_KEY_TYPE_RSA_KEYPAIR ((psa_key_type_t)0x07010000)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100163/** DSA public key. */
164#define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x06020000)
165/** DSA key pair (private and public key). */
166#define PSA_KEY_TYPE_DSA_KEYPAIR ((psa_key_type_t)0x07020000)
167#define PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE ((psa_key_type_t)0x06030000)
168#define PSA_KEY_TYPE_ECC_KEYPAIR_BASE ((psa_key_type_t)0x07030000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100169#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100170#define PSA_KEY_TYPE_ECC_KEYPAIR(curve) \
171 (PSA_KEY_TYPE_ECC_KEYPAIR_BASE | (curve))
172#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) \
173 (PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE | (curve))
Gilles Peskine98f0a242018-02-06 18:57:29 +0100174
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100175/** Whether a key type is vendor-defined. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100176#define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100177 (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100178#define PSA_KEY_TYPE_IS_RAW_BYTES(type) \
179 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_RAW_DATA || \
180 ((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_SYMMETRIC)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100181
182/** Whether a key type is asymmetric: either a key pair or a public key. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100183#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \
184 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_ASYMMETRIC)
Gilles Peskine06dc2632018-03-08 07:47:25 +0100185/** Whether a key type is the public part of a key pair. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100186#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \
187 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG) == \
188 PSA_KEY_TYPE_CATEGORY_ASYMMETRIC))
Gilles Peskine06dc2632018-03-08 07:47:25 +0100189/** Whether a key type is a key pair containing a private part and a public
190 * part. */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100191#define PSA_KEY_TYPE_IS_KEYPAIR(type) \
192 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG)) == \
193 (PSA_KEY_TYPE_CATEGORY_ASYMMETRIC | PSA_KEY_TYPE_PAIR_FLAG))
Gilles Peskine06dc2632018-03-08 07:47:25 +0100194/** Whether a key type is an RSA key pair or public key. */
195/** The key pair type corresponding to a public key type. */
196#define PSA_KEY_TYPE_KEYPAIR_OF_PUBLIC_KEY(type) \
197 ((type) | PSA_KEY_TYPE_PAIR_FLAG)
198/** The public key type corresponding to a key pair type. */
199#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) \
200 ((type) & ~PSA_KEY_TYPE_PAIR_FLAG)
Gilles Peskine0189e752018-02-03 23:57:22 +0100201#define PSA_KEY_TYPE_IS_RSA(type) \
Gilles Peskine06dc2632018-03-08 07:47:25 +0100202 (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) == PSA_KEY_TYPE_RSA_PUBLIC_KEY)
203/** Whether a key type is an elliptic curve key pair or public key. */
Gilles Peskinec66ea6a2018-02-03 22:43:28 +0100204#define PSA_KEY_TYPE_IS_ECC(type) \
Gilles Peskine06dc2632018-03-08 07:47:25 +0100205 ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) & \
206 ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_PUBLIC_KEY_BASE)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100207
Gilles Peskine7e198532018-03-08 07:50:30 +0100208/** The block size of a block cipher.
209 *
210 * \param type A cipher key type (value of type #psa_key_type_t).
211 *
212 * \return The block size for a block cipher, or 1 for a stream cipher.
213 * The return value is undefined if \c type does not identify
214 * a cipher algorithm.
215 *
216 * \note This macro returns a compile-time constant if its argument is one.
217 *
218 * \warning This macro may evaluate its argument multiple times.
219 */
Gilles Peskine03182e92018-03-07 16:40:52 +0100220#define PSA_BLOCK_CIPHER_BLOCK_SIZE(type) \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100221 ( \
222 (type) == PSA_KEY_TYPE_AES ? 16 : \
223 (type) == PSA_KEY_TYPE_DES ? 8 : \
224 (type) == PSA_KEY_TYPE_CAMELLIA ? 16 : \
Gilles Peskine7e198532018-03-08 07:50:30 +0100225 (type) == PSA_KEY_TYPE_ARC4 ? 1 : \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100226 0)
227
Gilles Peskine308b91d2018-02-08 09:47:44 +0100228/** \brief Encoding of a cryptographic algorithm.
229 *
230 * For algorithms that can be applied to multiple key types, this type
231 * does not encode the key type. For example, for symmetric ciphers
232 * based on a block cipher, #psa_algorithm_t encodes the block cipher
233 * mode and the padding mode while the block cipher itself is encoded
234 * via #psa_key_type_t.
235 */
Gilles Peskine20035e32018-02-03 22:44:14 +0100236typedef uint32_t psa_algorithm_t;
237
Gilles Peskine98f0a242018-02-06 18:57:29 +0100238#define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t)0x80000000)
239#define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t)0x7f000000)
240#define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t)0x01000000)
241#define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x02000000)
242#define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000)
243#define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t)0x06000000)
244#define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t)0x10000000)
245#define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t)0x12000000)
246#define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t)0x22000000)
247#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x30000000)
Gilles Peskine20035e32018-02-03 22:44:14 +0100248
Gilles Peskine98f0a242018-02-06 18:57:29 +0100249#define PSA_ALG_IS_VENDOR_DEFINED(alg) \
250 (((alg) & PSA_ALG_VENDOR_FLAG) != 0)
Gilles Peskine308b91d2018-02-08 09:47:44 +0100251/** Whether the specified algorithm is a hash algorithm.
252 *
Gilles Peskine7e198532018-03-08 07:50:30 +0100253 * \param alg An algorithm identifier (value of type #psa_algorithm_t).
Gilles Peskine308b91d2018-02-08 09:47:44 +0100254 *
255 * \return 1 if \c alg is a hash algorithm, 0 otherwise.
256 * This macro may return either 0 or 1 if \c alg is not a valid
Gilles Peskine7e198532018-03-08 07:50:30 +0100257 * algorithm identifier.
258 */
Gilles Peskine98f0a242018-02-06 18:57:29 +0100259#define PSA_ALG_IS_HASH(alg) \
260 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
261#define PSA_ALG_IS_MAC(alg) \
262 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)
263#define PSA_ALG_IS_CIPHER(alg) \
264 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)
265#define PSA_ALG_IS_AEAD(alg) \
266 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD)
267#define PSA_ALG_IS_SIGN(alg) \
268 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)
269#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
270 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)
271#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
272 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)
273#define PSA_ALG_IS_KEY_DERIVATION(alg) \
274 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
275
276#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)
277#define PSA_ALG_MD2 ((psa_algorithm_t)0x01000001)
278#define PSA_ALG_MD4 ((psa_algorithm_t)0x01000002)
279#define PSA_ALG_MD5 ((psa_algorithm_t)0x01000003)
Gilles Peskinee3f694f2018-03-08 07:48:40 +0100280#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x01000004)
281#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x01000005)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100282#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x01000008)
283#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x01000009)
284#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0100000a)
285#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0100000b)
286#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0100000c)
287#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0100000d)
288#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x01000010)
289#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x01000011)
290#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x01000012)
291#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
292
Gilles Peskine8c9def32018-02-08 10:02:12 +0100293#define PSA_ALG_MAC_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100294#define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000)
295#define PSA_ALG_HMAC(hash_alg) \
Gilles Peskine8c9def32018-02-08 10:02:12 +0100296 (PSA_ALG_HMAC_BASE | ((hash_alg) & PSA_ALG_HASH_MASK))
297#define PSA_ALG_HMAC_HASH(hmac_alg) \
298 (PSA_ALG_CATEGORY_HASH | ((hmac_alg) & PSA_ALG_HASH_MASK))
299#define PSA_ALG_IS_HMAC(alg) \
300 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
301 PSA_ALG_HMAC_BASE)
302#define PSA_ALG_CIPHER_MAC_BASE ((psa_algorithm_t)0x02c00000)
303#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02c00001)
304#define PSA_ALG_CMAC ((psa_algorithm_t)0x02c00002)
305#define PSA_ALG_GMAC ((psa_algorithm_t)0x02c00003)
306#define PSA_ALG_IS_CIPHER_MAC(alg) \
307 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_MAC_SUBCATEGORY_MASK)) == \
308 PSA_ALG_CIPHER_MAC_BASE)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100309
Gilles Peskine8c9def32018-02-08 10:02:12 +0100310#define PSA_ALG_CIPHER_SUBCATEGORY_MASK ((psa_algorithm_t)0x00c00000)
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100311#define PSA_ALG_BLOCK_CIPHER_BASE ((psa_algorithm_t)0x04000000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100312#define PSA_ALG_BLOCK_CIPHER_MODE_MASK ((psa_algorithm_t)0x000000ff)
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100313#define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x003f0000)
314#define PSA_ALG_BLOCK_CIPHER_PAD_NONE ((psa_algorithm_t)0x00000000)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100315#define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100316#define PSA_ALG_IS_BLOCK_CIPHER(alg) \
317 (((alg) & (PSA_ALG_CATEGORY_MASK | PSA_ALG_CIPHER_SUBCATEGORY_MASK)) == \
318 PSA_ALG_BLOCK_CIPHER_BASE)
319
Gilles Peskine98f0a242018-02-06 18:57:29 +0100320#define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100321#define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000002)
322#define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000003)
323#define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000004)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100324#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000)
325#define PSA_ALG_CTR ((psa_algorithm_t)0x04800001)
Gilles Peskine8c9def32018-02-08 10:02:12 +0100326#define PSA_ALG_ARC4 ((psa_algorithm_t)0x04800002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100327
Gilles Peskine8c9def32018-02-08 10:02:12 +0100328#define PSA_ALG_CCM ((psa_algorithm_t)0x06000001)
329#define PSA_ALG_GCM ((psa_algorithm_t)0x06000002)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100330
331#define PSA_ALG_RSA_PKCS1V15_RAW ((psa_algorithm_t)0x10010000)
332#define PSA_ALG_RSA_PSS_MGF1 ((psa_algorithm_t)0x10020000)
333#define PSA_ALG_RSA_OAEP ((psa_algorithm_t)0x12020000)
334#define PSA_ALG_RSA_PKCS1V15(hash_alg) \
335 (PSA_ALG_RSA_PKCS1V15_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
336#define PSA_ALG_IS_RSA_PKCS1V15(alg) \
Gilles Peskine20035e32018-02-03 22:44:14 +0100337 (((alg) & 0x7fffff00) == PSA_ALG_RSA_PKCS1V15_RAW)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100338#define PSA_ALG_RSA_GET_HASH(alg) \
339 (((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100340
341/**@}*/
342
343/** \defgroup key_management Key management
344 * @{
345 */
346
347/**
348 * \brief Import a key in binary format.
349 *
Gilles Peskinef5b9fa12018-03-07 16:40:18 +0100350 * This function supports any output from psa_export_key(). Refer to the
351 * documentation of psa_export_key() for the format for each key type.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100352 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100353 * \param key Slot where the key will be stored. This must be a
354 * valid slot for a key of the chosen type. It must
355 * be unoccupied.
356 * \param type Key type (a \c PSA_KEY_TYPE_XXX value).
357 * \param data Buffer containing the key data.
358 * \param data_length Size of the \c data buffer in bytes.
359 *
360 * \retval PSA_SUCCESS
361 * Success.
362 * \retval PSA_ERROR_NOT_SUPPORTED
363 * The key type or key size is not supported.
364 * \retval PSA_ERROR_INVALID_ARGUMENT
365 * The key slot is invalid,
366 * or the key data is not correctly formatted.
367 * \retval PSA_ERROR_OCCUPIED_SLOT
368 There is already a key in the specified slot.
369 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
370 * \retval PSA_ERROR_COMMUNICATION_FAILURE
371 * \retval PSA_ERROR_HARDWARE_FAILURE
372 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100373 */
374psa_status_t psa_import_key(psa_key_slot_t key,
375 psa_key_type_t type,
376 const uint8_t *data,
377 size_t data_length);
378
379/**
380 * \brief Destroy a key.
381 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100382 * \retval PSA_SUCCESS
383 * \retval PSA_ERROR_EMPTY_SLOT
384 * \retval PSA_ERROR_COMMUNICATION_FAILURE
385 * \retval PSA_ERROR_HARDWARE_FAILURE
386 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100387 */
388psa_status_t psa_destroy_key(psa_key_slot_t key);
389
390/**
391 * \brief Get basic metadata about a key.
392 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100393 * \param key Slot whose content is queried. This must
394 * be an occupied key slot.
395 * \param type On success, the key type (a \c PSA_KEY_TYPE_XXX value).
396 * This may be a null pointer, in which case the key type
397 * is not written.
398 * \param bits On success, the key size in bits.
399 * This may be a null pointer, in which case the key type
400 * is not written.
401 *
402 * \retval PSA_SUCCESS
403 * \retval PSA_ERROR_EMPTY_SLOT
404 * \retval PSA_ERROR_COMMUNICATION_FAILURE
405 * \retval PSA_ERROR_HARDWARE_FAILURE
406 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100407 */
408psa_status_t psa_get_key_information(psa_key_slot_t key,
409 psa_key_type_t *type,
410 size_t *bits);
411
412/**
413 * \brief Export a key in binary format.
414 *
415 * The output of this function can be passed to psa_import_key() to
416 * create an equivalent object.
417 *
418 * If a key is created with psa_import_key() and then exported with
419 * this function, it is not guaranteed that the resulting data is
420 * identical: the implementation may choose a different representation
Gilles Peskine92b30732018-03-03 21:29:30 +0100421 * of the same key if the format permits it.
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100422 *
Gilles Peskine308b91d2018-02-08 09:47:44 +0100423 * For standard key types, the output format is as follows:
424 *
425 * - For symmetric keys (including MAC keys), the format is the
426 * raw bytes of the key.
427 * - For DES, the key data consists of 8 bytes. The parity bits must be
428 * correct.
429 * - For Triple-DES, the format is the concatenation of the
430 * two or three DES keys.
Gilles Peskine92b30732018-03-03 21:29:30 +0100431 * - For RSA key pairs (#PSA_KEY_TYPE_RSA_KEYPAIR), the format
Gilles Peskine308b91d2018-02-08 09:47:44 +0100432 * is the non-encrypted DER representation defined by PKCS\#8 (RFC 5208)
433 * as PrivateKeyInfo.
434 * - For RSA public keys (#PSA_KEY_TYPE_RSA_PUBLIC_KEY), the format
Gilles Peskine971f7062018-03-20 17:52:58 +0100435 * is the DER representation defined by RFC 5280 as SubjectPublicKeyInfo.
Gilles Peskine308b91d2018-02-08 09:47:44 +0100436 *
437 * \param key Slot whose content is to be exported. This must
438 * be an occupied key slot.
439 * \param data Buffer where the key data is to be written.
440 * \param data_size Size of the \c data buffer in bytes.
441 * \param data_length On success, the number of bytes
442 * that make up the key data.
443 *
444 * \retval PSA_SUCCESS
445 * \retval PSA_ERROR_EMPTY_SLOT
Gilles Peskine92b30732018-03-03 21:29:30 +0100446 * \retval PSA_ERROR_NOT_PERMITTED
Gilles Peskine308b91d2018-02-08 09:47:44 +0100447 * \retval PSA_ERROR_COMMUNICATION_FAILURE
448 * \retval PSA_ERROR_HARDWARE_FAILURE
449 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100450 */
451psa_status_t psa_export_key(psa_key_slot_t key,
452 uint8_t *data,
453 size_t data_size,
454 size_t *data_length);
455
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100456/**
457 * \brief Export a public key or the public part of a key pair in binary format.
458 *
459 * The output of this function can be passed to psa_import_key() to
460 * create an object that is equivalent to the public key.
461 *
462 * For standard key types, the output format is as follows:
463 *
464 * - For RSA keys (#PSA_KEY_TYPE_RSA_KEYPAIR or #PSA_KEY_TYPE_RSA_PUBLIC_KEY),
Gilles Peskine971f7062018-03-20 17:52:58 +0100465 * is the DER representation of the public key defined by RFC 5280
466 * as SubjectPublicKeyInfo.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100467 *
468 * \param key Slot whose content is to be exported. This must
469 * be an occupied key slot.
470 * \param data Buffer where the key data is to be written.
471 * \param data_size Size of the \c data buffer in bytes.
472 * \param data_length On success, the number of bytes
473 * that make up the key data.
474 *
475 * \retval PSA_SUCCESS
476 * \retval PSA_ERROR_EMPTY_SLOT
477 * \retval PSA_ERROR_INVALID_ARGUMENT
478 * \retval PSA_ERROR_COMMUNICATION_FAILURE
479 * \retval PSA_ERROR_HARDWARE_FAILURE
480 * \retval PSA_ERROR_TAMPERING_DETECTED
481 */
482psa_status_t psa_export_public_key(psa_key_slot_t key,
483 uint8_t *data,
484 size_t data_size,
485 size_t *data_length);
486
487/**@}*/
488
489/** \defgroup policy Key policies
490 * @{
491 */
492
493/** \brief Encoding of permitted usage on a key. */
494typedef uint32_t psa_key_usage_t;
495
Gilles Peskine7e198532018-03-08 07:50:30 +0100496/** Whether the key may be exported.
497 *
498 * A public key or the public part of a key pair may always be exported
499 * regardless of the value of this permission flag.
500 *
501 * If a key does not have export permission, implementations shall not
502 * allow the key to be exported in plain form from the cryptoprocessor,
503 * whether through psa_export_key() or through a proprietary interface.
504 * The key may however be exportable in a wrapped form, i.e. in a form
505 * where it is encrypted by another key.
506 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100507#define PSA_KEY_USAGE_EXPORT ((psa_key_usage_t)0x00000001)
508
Gilles Peskine7e198532018-03-08 07:50:30 +0100509/** Whether the key may be used to encrypt a message.
510 *
511 * For a key pair, this concerns the public key.
512 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100513#define PSA_KEY_USAGE_ENCRYPT ((psa_key_usage_t)0x00000100)
Gilles Peskine7e198532018-03-08 07:50:30 +0100514
515/** Whether the key may be used to decrypt a message.
516 *
517 * For a key pair, this concerns the private key.
518 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100519#define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200)
Gilles Peskine7e198532018-03-08 07:50:30 +0100520
521/** Whether the key may be used to sign a message.
522 *
523 * For a key pair, this concerns the private key.
524 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100525#define PSA_KEY_USAGE_SIGN ((psa_key_usage_t)0x00000400)
Gilles Peskine7e198532018-03-08 07:50:30 +0100526
527/** Whether the key may be used to verify a message signature.
528 *
529 * For a key pair, this concerns the public key.
530 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100531#define PSA_KEY_USAGE_VERIFY ((psa_key_usage_t)0x00000800)
532
533/** The type of the key policy data structure.
534 *
535 * This is an implementation-defined \c struct. Applications should not
536 * make any assumptions about the content of this structure except
537 * as directed by the documentation of a specific implementation. */
538typedef struct psa_key_policy_s psa_key_policy_t;
539
540/** \brief Initialize a key policy structure to a default that forbids all
541 * usage of the key. */
542void psa_key_policy_init(psa_key_policy_t *policy);
543
Gilles Peskine7e198532018-03-08 07:50:30 +0100544/** \brief Set the standard fields of a policy structure.
545 *
546 * Note that this function does not make any consistency check of the
547 * parameters. The values are only checked when applying the policy to
548 * a key slot with psa_set_key_policy().
549 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100550void psa_key_policy_set_usage(psa_key_policy_t *policy,
551 psa_key_usage_t usage,
552 psa_algorithm_t alg);
553
554psa_key_usage_t psa_key_policy_get_usage(psa_key_policy_t *policy);
555
556psa_algorithm_t psa_key_policy_get_algorithm(psa_key_policy_t *policy);
557
558/** \brief Set the usage policy on a key slot.
559 *
560 * This function must be called on an empty key slot, before importing,
561 * generating or creating a key in the slot. Changing the policy of an
562 * existing key is not permitted.
Gilles Peskine7e198532018-03-08 07:50:30 +0100563 *
564 * Implementations may set restrictions on supported key policies
565 * depending on the key type and the key slot.
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100566 */
567psa_status_t psa_set_key_policy(psa_key_slot_t key,
568 const psa_key_policy_t *policy);
569
Gilles Peskine7e198532018-03-08 07:50:30 +0100570/** \brief Get the usage policy for a key slot.
571 */
Gilles Peskine7698bcf2018-03-03 21:30:44 +0100572psa_status_t psa_get_key_policy(psa_key_slot_t key,
573 psa_key_policy_t *policy);
Gilles Peskine20035e32018-02-03 22:44:14 +0100574
575/**@}*/
576
Gilles Peskine609b6a52018-03-03 21:31:50 +0100577/** \defgroup persistence Key lifetime
578 * @{
579 */
580
581/** Encoding of key lifetimes.
582 */
583typedef uint32_t psa_key_lifetime_t;
584
585/** A volatile key slot retains its content as long as the application is
586 * running. It is guaranteed to be erased on a power reset.
587 */
588#define PSA_KEY_LIFETIME_VOLATILE ((psa_key_lifetime_t)0x00000000)
589
590/** A persistent key slot retains its content as long as it is not explicitly
591 * destroyed.
592 */
593#define PSA_KEY_LIFETIME_PERSISTENT ((psa_key_lifetime_t)0x00000001)
594
595/** A write-once key slot may not be modified once a key has been set.
596 * It will retain its content as long as the device remains operational.
597 */
598#define PSA_KEY_LIFETIME_WRITE_ONCE ((psa_key_lifetime_t)0x7fffffff)
599
Gilles Peskined393e182018-03-08 07:49:16 +0100600/** \brief Retrieve the lifetime of a key slot.
601 *
602 * The assignment of lifetimes to slots is implementation-dependent.
mohammad1603804cd712018-03-20 22:44:08 +0200603 *
604 * \param key Slot whose content is to be exported. This must
605 * be an occupied key slot.
606 * \param lifetime On success, the lifetime value.
607 *
608 * \retval PSA_SUCCESS
609 * Success.
610 * \retval PSA_ERROR_INVALID_ARGUMENT
611 * The key slot is invalid,
612 * or the key data is not correctly formatted.
613 * \retval PSA_ERROR_EMPTY_SLOT
614 * The key slot is not occupied.
Gilles Peskined393e182018-03-08 07:49:16 +0100615 */
Gilles Peskine609b6a52018-03-03 21:31:50 +0100616psa_status_t psa_get_key_lifetime(psa_key_slot_t key,
617 psa_key_lifetime_t *lifetime);
618
Gilles Peskined393e182018-03-08 07:49:16 +0100619/** \brief Change the lifetime of a key slot.
mohammad1603804cd712018-03-20 22:44:08 +0200620 *
621 * \note In case a key slot has PSA_KEY_LIFETIME_WRITE_ONCE lifetime,
622 * it can not be changed and trying to set new value will return
623 * an error
Gilles Peskined393e182018-03-08 07:49:16 +0100624 *
mohammad1603804cd712018-03-20 22:44:08 +0200625 * \param key Slot whose content is to be exported. This must
626 * be an occupied key slot.
627 * \param lifetime The lifetime value to be set for the given key.
628 *
629 * \retval PSA_SUCCESS
630 * Success.
631 * \retval PSA_ERROR_INVALID_ARGUMENT
632 * The key slot is invalid,
633 * or the key data is not correctly formatted.
634 * \retval PSA_ERROR_EMPTY_SLOT
635 * The key slot is not occupied.
636 * \retval PSA_ERROR_INVALID_LIFETIME
637 * The lifetime value is not valid.
638 * \retval PSA_ERROR_KEY_LIFETIME_CHANGE
639 * The key slot already has PSA_KEY_LIFETIME_WRITE_ONCE value,
640 * and can not be changed.
Gilles Peskined393e182018-03-08 07:49:16 +0100641 */
642psa_status_t psa_set_key_lifetime(psa_key_slot_t key,
mohammad1603804cd712018-03-20 22:44:08 +0200643 const psa_key_lifetime_t lifetime);
Gilles Peskined393e182018-03-08 07:49:16 +0100644
Gilles Peskine609b6a52018-03-03 21:31:50 +0100645/**@}*/
646
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100647/** \defgroup hash Message digests
648 * @{
649 */
650
Gilles Peskine308b91d2018-02-08 09:47:44 +0100651/** The type of the state data structure for multipart hash operations.
652 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100653 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine308b91d2018-02-08 09:47:44 +0100654 * make any assumptions about the content of this structure except
655 * as directed by the documentation of a specific implementation. */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100656typedef struct psa_hash_operation_s psa_hash_operation_t;
657
Gilles Peskine308b91d2018-02-08 09:47:44 +0100658/** The size of the output of psa_hash_finish(), in bytes.
659 *
660 * This is also the hash size that psa_hash_verify() expects.
661 *
662 * \param alg A hash algorithm (\c PSA_ALG_XXX value such that
663 * #PSA_ALG_IS_HASH(alg) is true).
664 *
665 * \return The hash size for the specified hash algorithm.
666 * If the hash algorithm is not recognized, return 0.
667 * An implementation may return either 0 or the correct size
668 * for a hash algorithm that it recognizes, but does not support.
669 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100670#define PSA_HASH_FINAL_SIZE(alg) \
671 ( \
672 (alg) == PSA_ALG_MD2 ? 16 : \
673 (alg) == PSA_ALG_MD4 ? 16 : \
674 (alg) == PSA_ALG_MD5 ? 16 : \
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100675 (alg) == PSA_ALG_RIPEMD160 ? 20 : \
676 (alg) == PSA_ALG_SHA_1 ? 20 : \
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100677 (alg) == PSA_ALG_SHA_224 ? 28 : \
678 (alg) == PSA_ALG_SHA_256 ? 32 : \
679 (alg) == PSA_ALG_SHA_384 ? 48 : \
680 (alg) == PSA_ALG_SHA_512 ? 64 : \
681 (alg) == PSA_ALG_SHA_512_224 ? 28 : \
682 (alg) == PSA_ALG_SHA_512_256 ? 32 : \
683 (alg) == PSA_ALG_SHA3_224 ? 28 : \
684 (alg) == PSA_ALG_SHA3_256 ? 32 : \
685 (alg) == PSA_ALG_SHA3_384 ? 48 : \
686 (alg) == PSA_ALG_SHA3_512 ? 64 : \
687 0)
688
Gilles Peskine308b91d2018-02-08 09:47:44 +0100689/** Start a multipart hash operation.
690 *
691 * The sequence of operations to calculate a hash (message digest)
692 * is as follows:
693 * -# Allocate an operation object which will be passed to all the functions
694 * listed here.
695 * -# Call psa_hash_start() to specify the algorithm.
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100696 * -# Call psa_hash_update() zero, one or more times, passing a fragment
Gilles Peskine308b91d2018-02-08 09:47:44 +0100697 * of the message each time. The hash that is calculated is the hash
698 * of the concatenation of these messages in order.
699 * -# To calculate the hash, call psa_hash_finish().
700 * To compare the hash with an expected value, call psa_hash_verify().
701 *
702 * The application may call psa_hash_abort() at any time after the operation
703 * has been initialized with psa_hash_start().
704 *
705 * After a successful call to psa_hash_start(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100706 * eventually terminate the operation. The following events terminate an
707 * operation:
Gilles Peskine308b91d2018-02-08 09:47:44 +0100708 * - A failed call to psa_hash_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100709 * - A call to psa_hash_finish(), psa_hash_verify() or psa_hash_abort().
Gilles Peskine308b91d2018-02-08 09:47:44 +0100710 *
711 * \param operation
712 * \param alg The hash algorithm to compute (\c PSA_ALG_XXX value
713 * such that #PSA_ALG_IS_HASH(alg) is true).
714 *
715 * \retval PSA_SUCCESS
716 * Success.
717 * \retval PSA_ERROR_NOT_SUPPORTED
718 * \c alg is not supported or is not a hash algorithm.
719 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
720 * \retval PSA_ERROR_COMMUNICATION_FAILURE
721 * \retval PSA_ERROR_HARDWARE_FAILURE
722 * \retval PSA_ERROR_TAMPERING_DETECTED
723 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100724psa_status_t psa_hash_start(psa_hash_operation_t *operation,
725 psa_algorithm_t alg);
726
Gilles Peskine308b91d2018-02-08 09:47:44 +0100727/** Add a message fragment to a multipart hash operation.
728 *
729 * The application must call psa_hash_start() before calling this function.
730 *
731 * If this function returns an error status, the operation becomes inactive.
732 *
733 * \param operation Active hash operation.
734 * \param input Buffer containing the message fragment to hash.
735 * \param input_length Size of the \c input buffer in bytes.
736 *
737 * \retval PSA_SUCCESS
738 * Success.
739 * \retval PSA_ERROR_BAD_STATE
740 * The operation state is not valid (not started, or already completed).
741 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
742 * \retval PSA_ERROR_COMMUNICATION_FAILURE
743 * \retval PSA_ERROR_HARDWARE_FAILURE
744 * \retval PSA_ERROR_TAMPERING_DETECTED
745 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100746psa_status_t psa_hash_update(psa_hash_operation_t *operation,
747 const uint8_t *input,
748 size_t input_length);
749
Gilles Peskine308b91d2018-02-08 09:47:44 +0100750/** Finish the calculation of the hash of a message.
751 *
752 * The application must call psa_hash_start() before calling this function.
753 * This function calculates the hash of the message formed by concatenating
754 * the inputs passed to preceding calls to psa_hash_update().
755 *
756 * When this function returns, the operation becomes inactive.
757 *
758 * \warning Applications should not call this function if they expect
759 * a specific value for the hash. Call psa_hash_verify() instead.
760 * Beware that comparing integrity or authenticity data such as
761 * hash values with a function such as \c memcmp is risky
762 * because the time taken by the comparison may leak information
763 * about the hashed data which could allow an attacker to guess
764 * a valid hash and thereby bypass security controls.
765 *
766 * \param operation Active hash operation.
767 * \param hash Buffer where the hash is to be written.
768 * \param hash_size Size of the \c hash buffer in bytes.
769 * \param hash_length On success, the number of bytes
770 * that make up the hash value. This is always
771 * #PSA_HASH_FINAL_SIZE(alg) where \c alg is the
772 * hash algorithm that is calculated.
773 *
774 * \retval PSA_SUCCESS
775 * Success.
776 * \retval PSA_ERROR_BAD_STATE
777 * The operation state is not valid (not started, or already completed).
778 * \retval PSA_ERROR_BUFFER_TOO_SMALL
779 * The size of the \c hash buffer is too small. You can determine a
780 * sufficient buffer size by calling #PSA_HASH_FINAL_SIZE(alg)
781 * where \c alg is the hash algorithm that is calculated.
782 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
783 * \retval PSA_ERROR_COMMUNICATION_FAILURE
784 * \retval PSA_ERROR_HARDWARE_FAILURE
785 * \retval PSA_ERROR_TAMPERING_DETECTED
786 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100787psa_status_t psa_hash_finish(psa_hash_operation_t *operation,
788 uint8_t *hash,
789 size_t hash_size,
790 size_t *hash_length);
791
Gilles Peskine308b91d2018-02-08 09:47:44 +0100792/** Finish the calculation of the hash of a message and compare it with
793 * an expected value.
794 *
795 * The application must call psa_hash_start() before calling this function.
796 * This function calculates the hash of the message formed by concatenating
797 * the inputs passed to preceding calls to psa_hash_update(). It then
798 * compares the calculated hash with the expected hash passed as a
799 * parameter to this function.
800 *
801 * When this function returns, the operation becomes inactive.
802 *
Gilles Peskine19067982018-03-20 17:54:53 +0100803 * \note Implementations shall make the best effort to ensure that the
Gilles Peskine308b91d2018-02-08 09:47:44 +0100804 * comparison between the actual hash and the expected hash is performed
805 * in constant time.
806 *
807 * \param operation Active hash operation.
808 * \param hash Buffer containing the expected hash value.
809 * \param hash_length Size of the \c hash buffer in bytes.
810 *
811 * \retval PSA_SUCCESS
812 * The expected hash is identical to the actual hash of the message.
813 * \retval PSA_ERROR_INVALID_SIGNATURE
814 * The hash of the message was calculated successfully, but it
815 * differs from the expected hash.
816 * \retval PSA_ERROR_BAD_STATE
817 * The operation state is not valid (not started, or already completed).
818 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
819 * \retval PSA_ERROR_COMMUNICATION_FAILURE
820 * \retval PSA_ERROR_HARDWARE_FAILURE
821 * \retval PSA_ERROR_TAMPERING_DETECTED
822 */
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100823psa_status_t psa_hash_verify(psa_hash_operation_t *operation,
824 const uint8_t *hash,
825 size_t hash_length);
826
Gilles Peskine308b91d2018-02-08 09:47:44 +0100827/** Abort a hash operation.
828 *
829 * This function may be called at any time after psa_hash_start().
830 * Aborting an operation frees all associated resources except for the
831 * \c operation structure itself.
832 *
833 * Implementation should strive to be robust and handle inactive hash
834 * operations safely (do nothing and return #PSA_ERROR_BAD_STATE). However,
835 * application writers should beware that uninitialized memory may happen
836 * to be indistinguishable from an active hash operation, and the behavior
837 * of psa_hash_abort() is undefined in this case.
838 *
839 * \param operation Active hash operation.
840 *
841 * \retval PSA_SUCCESS
842 * \retval PSA_ERROR_BAD_STATE
843 * \c operation is not an active hash operation.
844 * \retval PSA_ERROR_COMMUNICATION_FAILURE
845 * \retval PSA_ERROR_HARDWARE_FAILURE
846 * \retval PSA_ERROR_TAMPERING_DETECTED
847 */
848psa_status_t psa_hash_abort(psa_hash_operation_t *operation);
Gilles Peskine9ef733f2018-02-07 21:05:37 +0100849
850/**@}*/
851
Gilles Peskine8c9def32018-02-08 10:02:12 +0100852/** \defgroup MAC Message authentication codes
853 * @{
854 */
855
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100856/** The type of the state data structure for multipart MAC operations.
857 *
Gilles Peskine92b30732018-03-03 21:29:30 +0100858 * This is an implementation-defined \c struct. Applications should not
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100859 * make any assumptions about the content of this structure except
860 * as directed by the documentation of a specific implementation. */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100861typedef struct psa_mac_operation_s psa_mac_operation_t;
862
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100863/** The size of the output of psa_mac_finish(), in bytes.
864 *
865 * This is also the MAC size that psa_mac_verify() expects.
866 *
867 * \param alg A MAC algorithm (\c PSA_ALG_XXX value such that
868 * #PSA_ALG_IS_MAC(alg) is true).
869 *
870 * \return The MAC size for the specified algorithm.
871 * If the MAC algorithm is not recognized, return 0.
872 * An implementation may return either 0 or the correct size
873 * for a MAC algorithm that it recognizes, but does not support.
874 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100875#define PSA_MAC_FINAL_SIZE(key_type, key_bits, alg) \
876 (PSA_ALG_IS_HMAC(alg) ? PSA_HASH_FINAL_SIZE(PSA_ALG_HMAC_HASH(alg)) : \
877 PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) ? PSA_BLOCK_CIPHER_BLOCK_SIZE(key_type) : \
878 0)
879
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100880/** Start a multipart MAC operation.
881 *
882 * The sequence of operations to calculate a MAC (message authentication code)
883 * is as follows:
884 * -# Allocate an operation object which will be passed to all the functions
885 * listed here.
886 * -# Call psa_mac_start() to specify the algorithm and key.
887 * The key remains associated with the operation even if the content
888 * of the key slot changes.
889 * -# Call psa_mac_update() zero, one or more times, passing a fragment
890 * of the message each time. The MAC that is calculated is the MAC
891 * of the concatenation of these messages in order.
892 * -# To calculate the MAC, call psa_mac_finish().
893 * To compare the MAC with an expected value, call psa_mac_verify().
894 *
895 * The application may call psa_mac_abort() at any time after the operation
896 * has been initialized with psa_mac_start().
897 *
898 * After a successful call to psa_mac_start(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100899 * eventually terminate the operation. The following events terminate an
900 * operation:
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100901 * - A failed call to psa_mac_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100902 * - A call to psa_mac_finish(), psa_mac_verify() or psa_mac_abort().
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100903 *
904 * \param operation
905 * \param alg The MAC algorithm to compute (\c PSA_ALG_XXX value
906 * such that #PSA_ALG_IS_MAC(alg) is true).
907 *
908 * \retval PSA_SUCCESS
909 * Success.
910 * \retval PSA_ERROR_EMPTY_SLOT
Gilles Peskine92b30732018-03-03 21:29:30 +0100911 * \retval PSA_ERROR_NOT_PERMITTED
Gilles Peskine7e4acc52018-02-16 21:24:11 +0100912 * \retval PSA_ERROR_INVALID_ARGUMENT
913 * \c key is not compatible with \c alg.
914 * \retval PSA_ERROR_NOT_SUPPORTED
915 * \c alg is not supported or is not a MAC algorithm.
916 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
917 * \retval PSA_ERROR_COMMUNICATION_FAILURE
918 * \retval PSA_ERROR_HARDWARE_FAILURE
919 * \retval PSA_ERROR_TAMPERING_DETECTED
920 */
Gilles Peskine8c9def32018-02-08 10:02:12 +0100921psa_status_t psa_mac_start(psa_mac_operation_t *operation,
922 psa_key_slot_t key,
923 psa_algorithm_t alg);
924
925psa_status_t psa_mac_update(psa_mac_operation_t *operation,
926 const uint8_t *input,
927 size_t input_length);
928
929psa_status_t psa_mac_finish(psa_mac_operation_t *operation,
930 uint8_t *mac,
931 size_t mac_size,
932 size_t *mac_length);
933
934psa_status_t psa_mac_verify(psa_mac_operation_t *operation,
935 const uint8_t *mac,
936 size_t mac_length);
937
938psa_status_t psa_mac_abort(psa_mac_operation_t *operation);
939
940/**@}*/
941
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100942/** \defgroup cipher Symmetric ciphers
943 * @{
944 */
945
946/** The type of the state data structure for multipart cipher operations.
947 *
948 * This is an implementation-defined \c struct. Applications should not
949 * make any assumptions about the content of this structure except
950 * as directed by the documentation of a specific implementation. */
951typedef struct psa_cipher_operation_s psa_cipher_operation_t;
952
953/** Set the key for a multipart symmetric encryption operation.
954 *
955 * The sequence of operations to encrypt a message with a symmetric cipher
956 * is as follows:
957 * -# Allocate an operation object which will be passed to all the functions
958 * listed here.
959 * -# Call psa_encrypt_setup() to specify the algorithm and key.
960 * The key remains associated with the operation even if the content
961 * of the key slot changes.
962 * -# Call either psa_encrypt_generate_iv() or psa_encrypt_set_iv() to
963 * generate or set the IV (initialization vector). You should use
964 * psa_encrypt_generate_iv() unless the protocol you are implementing
965 * requires a specific IV value.
966 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
967 * of the message each time.
968 * -# Call psa_cipher_finish().
969 *
970 * The application may call psa_cipher_abort() at any time after the operation
971 * has been initialized with psa_encrypt_setup().
972 *
973 * After a successful call to psa_encrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +0100974 * eventually terminate the operation. The following events terminate an
975 * operation:
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100976 * - A failed call to psa_encrypt_generate_iv(), psa_encrypt_set_iv()
977 * or psa_cipher_update().
Gilles Peskine19067982018-03-20 17:54:53 +0100978 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +0100979 *
980 * \param operation
981 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
982 * such that #PSA_ALG_IS_CIPHER(alg) is true).
983 *
984 * \retval PSA_SUCCESS
985 * Success.
986 * \retval PSA_ERROR_EMPTY_SLOT
987 * \retval PSA_ERROR_NOT_PERMITTED
988 * \retval PSA_ERROR_INVALID_ARGUMENT
989 * \c key is not compatible with \c alg.
990 * \retval PSA_ERROR_NOT_SUPPORTED
991 * \c alg is not supported or is not a cipher algorithm.
992 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
993 * \retval PSA_ERROR_COMMUNICATION_FAILURE
994 * \retval PSA_ERROR_HARDWARE_FAILURE
995 * \retval PSA_ERROR_TAMPERING_DETECTED
996 */
997psa_status_t psa_encrypt_setup(psa_cipher_operation_t *operation,
998 psa_key_slot_t key,
999 psa_algorithm_t alg);
1000
1001/** Set the key for a multipart symmetric decryption operation.
1002 *
1003 * The sequence of operations to decrypt a message with a symmetric cipher
1004 * is as follows:
1005 * -# Allocate an operation object which will be passed to all the functions
1006 * listed here.
1007 * -# Call psa_decrypt_setup() to specify the algorithm and key.
1008 * The key remains associated with the operation even if the content
1009 * of the key slot changes.
1010 * -# Call psa_cipher_update() with the IV (initialization vector) for the
1011 * decryption. If the IV is prepended to the ciphertext, you can call
1012 * psa_cipher_update() on a buffer containing the IV followed by the
1013 * beginning of the message.
1014 * -# Call psa_cipher_update() zero, one or more times, passing a fragment
1015 * of the message each time.
1016 * -# Call psa_cipher_finish().
1017 *
1018 * The application may call psa_cipher_abort() at any time after the operation
1019 * has been initialized with psa_encrypt_setup().
1020 *
1021 * After a successful call to psa_decrypt_setup(), the application must
Gilles Peskineed522972018-03-20 17:54:15 +01001022 * eventually terminate the operation. The following events terminate an
1023 * operation:
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001024 * - A failed call to psa_cipher_update().
Gilles Peskine19067982018-03-20 17:54:53 +01001025 * - A call to psa_cipher_finish() or psa_cipher_abort().
Gilles Peskine428dc5a2018-03-03 21:27:18 +01001026 *
1027 * \param operation
1028 * \param alg The cipher algorithm to compute (\c PSA_ALG_XXX value
1029 * such that #PSA_ALG_IS_CIPHER(alg) is true).
1030 *
1031 * \retval PSA_SUCCESS
1032 * Success.
1033 * \retval PSA_ERROR_EMPTY_SLOT
1034 * \retval PSA_ERROR_NOT_PERMITTED
1035 * \retval PSA_ERROR_INVALID_ARGUMENT
1036 * \c key is not compatible with \c alg.
1037 * \retval PSA_ERROR_NOT_SUPPORTED
1038 * \c alg is not supported or is not a cipher algorithm.
1039 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1040 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1041 * \retval PSA_ERROR_HARDWARE_FAILURE
1042 * \retval PSA_ERROR_TAMPERING_DETECTED
1043 */
1044psa_status_t psa_decrypt_setup(psa_cipher_operation_t *operation,
1045 psa_key_slot_t key,
1046 psa_algorithm_t alg);
1047
1048psa_status_t psa_encrypt_generate_iv(psa_cipher_operation_t *operation,
1049 unsigned char *iv,
1050 size_t iv_size,
1051 size_t *iv_length);
1052
1053psa_status_t psa_encrypt_set_iv(psa_cipher_operation_t *operation,
1054 const unsigned char *iv,
1055 size_t iv_length);
1056
1057psa_status_t psa_cipher_update(psa_cipher_operation_t *operation,
1058 const uint8_t *input,
1059 size_t input_length);
1060
1061psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation,
1062 uint8_t *mac,
1063 size_t mac_size,
1064 size_t *mac_length);
1065
1066psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation);
1067
1068/**@}*/
1069
Gilles Peskine3b555712018-03-03 21:27:57 +01001070/** \defgroup aead Authenticated encryption with associated data (AEAD)
1071 * @{
1072 */
1073
1074/** The type of the state data structure for multipart AEAD operations.
1075 *
1076 * This is an implementation-defined \c struct. Applications should not
1077 * make any assumptions about the content of this structure except
1078 * as directed by the documentation of a specific implementation. */
1079typedef struct psa_aead_operation_s psa_aead_operation_t;
1080
1081/** Set the key for a multipart authenticated encryption operation.
1082 *
1083 * The sequence of operations to authenticate-and-encrypt a message
1084 * is as follows:
1085 * -# Allocate an operation object which will be passed to all the functions
1086 * listed here.
1087 * -# Call psa_aead_encrypt_setup() to specify the algorithm and key.
1088 * The key remains associated with the operation even if the content
1089 * of the key slot changes.
1090 * -# Call either psa_aead_generate_iv() or psa_aead_set_iv() to
1091 * generate or set the IV (initialization vector). You should use
1092 * psa_encrypt_generate_iv() unless the protocol you are implementing
1093 * requires a specific IV value.
1094 * -# Call psa_aead_update_ad() to pass the associated data that is
1095 * to be authenticated but not encrypted. You may omit this step if
1096 * there is no associated data.
1097 * -# Call psa_aead_update() zero, one or more times, passing a fragment
1098 * of the data to encrypt each time.
1099 * -# Call psa_aead_finish().
1100 *
1101 * The application may call psa_aead_abort() at any time after the operation
1102 * has been initialized with psa_aead_encrypt_setup().
1103 *
Gilles Peskineed522972018-03-20 17:54:15 +01001104 * After a successful call to psa_aead_encrypt_setup(), the application must
1105 * eventually terminate the operation. The following events terminate an
1106 * operation:
Gilles Peskine3b555712018-03-03 21:27:57 +01001107 * - A failed call to psa_aead_generate_iv(), psa_aead_set_iv(),
1108 * psa_aead_update_ad() or psa_aead_update().
Gilles Peskine19067982018-03-20 17:54:53 +01001109 * - A call to psa_aead_finish() or psa_aead_abort().
Gilles Peskine3b555712018-03-03 21:27:57 +01001110 *
1111 * \param operation
1112 * \param alg The AEAD algorithm to compute (\c PSA_ALG_XXX value
1113 * such that #PSA_ALG_IS_AEAD(alg) is true).
1114 *
1115 * \retval PSA_SUCCESS
1116 * Success.
1117 * \retval PSA_ERROR_EMPTY_SLOT
1118 * \retval PSA_ERROR_NOT_PERMITTED
1119 * \retval PSA_ERROR_INVALID_ARGUMENT
1120 * \c key is not compatible with \c alg.
1121 * \retval PSA_ERROR_NOT_SUPPORTED
1122 * \c alg is not supported or is not an AEAD algorithm.
1123 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1124 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1125 * \retval PSA_ERROR_HARDWARE_FAILURE
1126 * \retval PSA_ERROR_TAMPERING_DETECTED
1127 */
1128psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation,
1129 psa_key_slot_t key,
1130 psa_algorithm_t alg);
1131
1132/** Set the key for a multipart authenticated decryption operation.
1133 *
1134 * The sequence of operations to authenticated and decrypt a message
1135 * is as follows:
1136 * -# Allocate an operation object which will be passed to all the functions
1137 * listed here.
1138 * -# Call psa_aead_decrypt_setup() to specify the algorithm and key.
1139 * The key remains associated with the operation even if the content
1140 * of the key slot changes.
1141 * -# Call psa_aead_set_iv() to pass the initialization vector (IV)
1142 * for the authenticated decryption.
1143 * -# Call psa_aead_update_ad() to pass the associated data that is
1144 * to be authenticated but not encrypted. You may omit this step if
1145 * there is no associated data.
1146 * -# Call psa_aead_update() zero, one or more times, passing a fragment
1147 * of the data to decrypt each time.
1148 * -# Call psa_aead_finish().
1149 *
1150 * The application may call psa_aead_abort() at any time after the operation
1151 * has been initialized with psa_aead_decrypt_setup().
1152 *
Gilles Peskineed522972018-03-20 17:54:15 +01001153 * After a successful call to psa_aead_decrypt_setup(), the application must
1154 * eventually terminate the operation. The following events terminate an
1155 * operation:
Gilles Peskine3b555712018-03-03 21:27:57 +01001156 * - A failed call to psa_aead_update().
Gilles Peskine19067982018-03-20 17:54:53 +01001157 * - A call to psa_aead_finish() or psa_aead_abort().
Gilles Peskine3b555712018-03-03 21:27:57 +01001158 *
1159 * \param operation
Gilles Peskine19067982018-03-20 17:54:53 +01001160 * \param alg The AEAD algorithm to compute (\c PSA_ALG_XXX value
1161 * such that #PSA_ALG_IS_AEAD(alg) is true).
Gilles Peskine3b555712018-03-03 21:27:57 +01001162 *
1163 * \retval PSA_SUCCESS
1164 * Success.
1165 * \retval PSA_ERROR_EMPTY_SLOT
1166 * \retval PSA_ERROR_NOT_PERMITTED
1167 * \retval PSA_ERROR_INVALID_ARGUMENT
1168 * \c key is not compatible with \c alg.
1169 * \retval PSA_ERROR_NOT_SUPPORTED
Gilles Peskine19067982018-03-20 17:54:53 +01001170 * \c alg is not supported or is not an AEAD algorithm.
Gilles Peskine3b555712018-03-03 21:27:57 +01001171 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1172 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1173 * \retval PSA_ERROR_HARDWARE_FAILURE
1174 * \retval PSA_ERROR_TAMPERING_DETECTED
1175 */
1176psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation,
1177 psa_key_slot_t key,
1178 psa_algorithm_t alg);
1179
1180psa_status_t psa_aead_generate_iv(psa_aead_operation_t *operation,
1181 unsigned char *iv,
1182 size_t iv_size,
1183 size_t *iv_length);
1184
1185psa_status_t psa_aead_set_iv(psa_aead_operation_t *operation,
1186 const unsigned char *iv,
1187 size_t iv_length);
1188
1189psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation,
1190 const uint8_t *input,
1191 size_t input_length);
1192
1193psa_status_t psa_aead_update(psa_aead_operation_t *operation,
1194 const uint8_t *input,
1195 size_t input_length);
1196
1197psa_status_t psa_aead_finish(psa_aead_operation_t *operation,
1198 uint8_t *tag,
1199 size_t tag_size,
1200 size_t *tag_length);
1201
1202psa_status_t psa_aead_verify(psa_aead_operation_t *operation,
1203 uint8_t *tag,
1204 size_t tag_length);
1205
1206psa_status_t psa_aead_abort(psa_aead_operation_t *operation);
1207
1208/**@}*/
1209
Gilles Peskine20035e32018-02-03 22:44:14 +01001210/** \defgroup asymmetric Asymmetric cryptography
1211 * @{
1212 */
1213
1214/**
Gilles Peskine0189e752018-02-03 23:57:22 +01001215 * \brief Maximum ECDSA signature size for a given curve bit size
1216 *
1217 * \param curve_bits Curve size in bits
1218 * \return Maximum signature size in bytes
1219 *
1220 * \note This macro returns a compile-time constant if its argument is one.
1221 *
1222 * \warning This macro may evaluate its argument multiple times.
1223 */
1224/*
1225 * RFC 4492 page 20:
1226 *
1227 * Ecdsa-Sig-Value ::= SEQUENCE {
1228 * r INTEGER,
1229 * s INTEGER
1230 * }
1231 *
1232 * Size is at most
1233 * 1 (tag) + 1 (len) + 1 (initial 0) + curve_bytes for each of r and s,
1234 * twice that + 1 (tag) + 2 (len) for the sequence
1235 * (assuming curve_bytes is less than 126 for r and s,
1236 * and less than 124 (total len <= 255) for the sequence)
1237 */
1238#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
1239 ( /*T,L of SEQUENCE*/ ((curve_bits) >= 61 * 8 ? 3 : 2) + \
1240 /*T,L of r,s*/ 2 * (((curve_bits) >= 127 * 8 ? 3 : 2) + \
1241 /*V of r,s*/ ((curve_bits) + 8) / 8))
1242
1243
Gilles Peskine308b91d2018-02-08 09:47:44 +01001244/** Safe signature buffer size for psa_asymmetric_sign().
1245 *
1246 * This macro returns a safe buffer size for a signature using a key
1247 * of the specified type and size, with the specified algorithm.
1248 * Note that the actual size of the signature may be smaller
1249 * (some algorithms produce a variable-size signature).
1250 *
1251 * \warning This function may call its arguments multiple times or
1252 * zero times, so you should not pass arguments that contain
1253 * side effects.
1254 *
1255 * \param key_type An asymmetric key type (this may indifferently be a
1256 * key pair type or a public key type).
1257 * \param key_bits The size of the key in bits.
1258 * \param alg The signature algorithm.
1259 *
1260 * \return If the parameters are valid and supported, return
1261 * a buffer size in bytes that guarantees that
1262 * psa_asymmetric_sign() will not fail with
1263 * #PSA_ERROR_BUFFER_TOO_SMALL.
1264 * If the parameters are a valid combination that is not supported
1265 * by the implementation, this macro either shall return either a
1266 * sensible size or 0.
1267 * If the parameters are not valid, the
1268 * return value is unspecified.
1269 *
1270 */
Gilles Peskine0189e752018-02-03 23:57:22 +01001271#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
Gilles Peskine2905a7a2018-03-07 16:39:31 +01001272 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, PSA_BITS_TO_BYTES(key_bits)) : \
Gilles Peskine0189e752018-02-03 23:57:22 +01001273 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
1274 0)
1275
1276/**
Gilles Peskine20035e32018-02-03 22:44:14 +01001277 * \brief Sign a hash or short message with a private key.
1278 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001279 * \param key Key slot containing an asymmetric key pair.
1280 * \param alg A signature algorithm that is compatible with
1281 * the type of \c key.
1282 * \param hash The message to sign.
1283 * \param hash_length Size of the \c hash buffer in bytes.
1284 * \param salt A salt or label, if supported by the signature
1285 * algorithm.
1286 * If the signature algorithm does not support a
1287 * salt, pass \c NULL.
1288 * If the signature algorithm supports an optional
1289 * salt and you do not want to pass a salt,
1290 * pass \c NULL.
1291 * \param salt_length Size of the \c salt buffer in bytes.
1292 * If \c salt is \c NULL, pass 0.
1293 * \param signature Buffer where the signature is to be written.
1294 * \param signature_size Size of the \c signature buffer in bytes.
1295 * \param signature_length On success, the number of bytes
1296 * that make up the returned signature value.
1297 * This is at most #PSA_HASH_FINAL_SIZE(alg)
1298 * (note that it may be less).
1299 *
1300 * \retval PSA_SUCCESS
1301 * \retval PSA_ERROR_BUFFER_TOO_SMALL
1302 * The size of the \c signature buffer is too small. You can
1303 * determine a sufficient buffer size by calling
1304 * #PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg)
1305 * where \c key_type and \c key_bits are the type and bit-size
1306 * respectively of \c key.
1307 * \retval PSA_ERROR_NOT_SUPPORTED
1308 * \retval PSA_ERROR_INVALID_ARGUMENT
1309 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1310 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1311 * \retval PSA_ERROR_HARDWARE_FAILURE
1312 * \retval PSA_ERROR_TAMPERING_DETECTED
1313 * \retval PSA_ERROR_INSUFFICIENT_ENTROPY
Gilles Peskine20035e32018-02-03 22:44:14 +01001314 */
1315psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
1316 psa_algorithm_t alg,
1317 const uint8_t *hash,
1318 size_t hash_length,
1319 const uint8_t *salt,
1320 size_t salt_length,
1321 uint8_t *signature,
1322 size_t signature_size,
1323 size_t *signature_length);
1324
1325/**
1326 * \brief Verify the signature a hash or short message using a public key.
1327 *
Gilles Peskine308b91d2018-02-08 09:47:44 +01001328 * \param key Key slot containing a public key or an
1329 * asymmetric key pair.
1330 * \param alg A signature algorithm that is compatible with
1331 * the type of \c key.
1332 * \param hash The message whose signature is to be verified.
1333 * \param hash_length Size of the \c hash buffer in bytes.
1334 * \param salt A salt or label, if supported by the signature
1335 * algorithm.
1336 * If the signature algorithm does not support a
1337 * salt, pass \c NULL.
1338 * If the signature algorithm supports an optional
1339 * salt and you do not want to pass a salt,
1340 * pass \c NULL.
1341 * \param salt_length Size of the \c salt buffer in bytes.
1342 * If \c salt is \c NULL, pass 0.
1343 * \param signature Buffer containing the signature to verify.
1344 * \param signature_size Size of the \c signature buffer in bytes.
1345 *
1346 * \retval PSA_SUCCESS
1347 * The signature is valid.
1348 * \retval PSA_ERROR_INVALID_SIGNATURE
1349 * The calculation was perfomed successfully, but the passed
1350 * signature is not a valid signature.
1351 * \retval PSA_ERROR_NOT_SUPPORTED
1352 * \retval PSA_ERROR_INVALID_ARGUMENT
1353 * \retval PSA_ERROR_INSUFFICIENT_MEMORY
1354 * \retval PSA_ERROR_COMMUNICATION_FAILURE
1355 * \retval PSA_ERROR_HARDWARE_FAILURE
1356 * \retval PSA_ERROR_TAMPERING_DETECTED
Gilles Peskine20035e32018-02-03 22:44:14 +01001357 */
1358psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
1359 psa_algorithm_t alg,
1360 const uint8_t *hash,
1361 size_t hash_length,
1362 const uint8_t *salt,
1363 size_t salt_length,
1364 uint8_t *signature,
1365 size_t signature_size);
1366
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +01001367/**@}*/
1368
Gilles Peskinee59236f2018-01-27 23:32:46 +01001369#ifdef __cplusplus
1370}
1371#endif
1372
Gilles Peskine9ef733f2018-02-07 21:05:37 +01001373/* The file "crypto_struct.h" contains definitions for
1374 * implementation-specific structs that are declared above. */
1375#include "crypto_struct.h"
1376
1377/* The file "crypto_extra.h" contains vendor-specific definitions. This
1378 * can include vendor-defined algorithms, extra functions, etc. */
Gilles Peskinee59236f2018-01-27 23:32:46 +01001379#include "crypto_extra.h"
1380
1381#endif /* PSA_CRYPTO_H */