blob: c1eb60ff8929498f8b96d2264bce366b48485aed [file] [log] [blame]
Gilles Peskinee59236f2018-01-27 23:32:46 +01001/**
2 * \file psa/crypto.h
3 * \brief Platform Security Architecture cryptography module
4 */
5
6#ifndef PSA_CRYPTO_H
7#define PSA_CRYPTO_H
8
9#include "crypto_platform.h"
10
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010011#include <stddef.h>
12
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010013#ifdef __DOXYGEN_ONLY__
14/** \defgroup platform Implementation-specific definitions
15 * @{
16 */
17
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +010018/** \brief Key slot number.
19 *
20 * This type represents key slots. It must be an unsigned integral
21 * type.* The choice of type is implementation-dependent.
22 * 0 is not a valid key slot number. The meaning of other values is
23 * implementation dependent.
24 *
25 * At any given point in time, each key slot either contains a
26 * cryptographic object, or is empty. Key slots are persistent:
27 * once set, the cryptographic object remains in the key slot until
28 * explicitly destroyed.
29 */
30typedef _unsigned_integral_type_ psa_key_slot_t;
31
Gilles Peskine62a7e7e2018-02-07 21:54:47 +010032/**@}*/
33#endif
34
Gilles Peskinee59236f2018-01-27 23:32:46 +010035#ifdef __cplusplus
36extern "C" {
37#endif
38
39/** \defgroup basic Basic definitions
40 * @{
41 */
42
43/**
44 * \brief Function return status.
45 *
46 * Zero indicates success, anything else indicates an error.
47 */
48typedef enum {
49 /** The action was completed successfully. */
50 PSA_SUCCESS = 0,
51 /** The requested operation or a parameter is not supported
52 by this implementation. */
53 PSA_ERROR_NOT_SUPPORTED,
54 /** The requested action is denied by a policy. */
55 PSA_ERROR_NOT_PERMITTED,
56 /** An output buffer is too small. */
57 PSA_ERROR_BUFFER_TOO_SMALL,
58 /** A slot is occupied, but must be empty to carry out the
59 requested action. */
60 PSA_ERROR_OCCUPIED_SLOT,
61 /** A slot is empty, but must be occupied to carry out the
62 requested action. */
63 PSA_ERROR_EMPTY_SLOT,
64 /** The requested action cannot be performed in the current state. */
65 PSA_ERROR_BAD_STATE,
66 /** The parameters passed to the function are invalid. */
67 PSA_ERROR_INVALID_ARGUMENT,
68 /** There is not enough runtime memory. */
69 PSA_ERROR_INSUFFICIENT_MEMORY,
70 /** There is not enough persistent storage. */
71 PSA_ERROR_INSUFFICIENT_STORAGE,
72 /** There was a communication failure inside the implementation. */
73 PSA_ERROR_COMMUNICATION_FAILURE,
Gilles Peskinea5905292018-02-07 20:59:33 +010074 /** There was a storage failure that may have led to data loss. */
75 PSA_ERROR_STORAGE_FAILURE,
Gilles Peskinee59236f2018-01-27 23:32:46 +010076 /** A hardware failure was detected. */
77 PSA_ERROR_HARDWARE_FAILURE,
78 /** A tampering attempt was detected. */
79 PSA_ERROR_TAMPERING_DETECTED,
80 /** There is not enough entropy to generate random data needed
81 for the requested action. */
82 PSA_ERROR_INSUFFICIENT_ENTROPY,
Gilles Peskinea5905292018-02-07 20:59:33 +010083 /** The signature, MAC or hash is incorrect. */
Gilles Peskinee59236f2018-01-27 23:32:46 +010084 PSA_ERROR_INVALID_SIGNATURE,
Gilles Peskinea5905292018-02-07 20:59:33 +010085 /** The decrypted padding is incorrect. */
86 PSA_ERROR_INVALID_PADDING,
Gilles Peskinee59236f2018-01-27 23:32:46 +010087 /** An error occurred that does not correspond to any defined
88 failure cause. */
89 PSA_ERROR_UNKNOWN_ERROR,
90} psa_status_t;
91
92/**
93 * \brief Library initialization.
94 *
95 * Applications must call this function before calling any other
96 * function in this module.
97 *
98 * Applications may call this function more than once. Once a call
99 * succeeds, subsequent calls are guaranteed to succeed.
100 *
101 * \return * \c PSA_SUCCESS: success.
102 * * \c PSA_ERROR_INSUFFICIENT_MEMORY
103 * * \c PSA_ERROR_COMMUNICATION_FAILURE
104 * * \c PSA_ERROR_HARDWARE_FAILURE
105 * * \c PSA_ERROR_TAMPERING_DETECTED
106 * * \c PSA_ERROR_INSUFFICIENT_ENTROPY
107 */
108psa_status_t psa_crypto_init(void);
109
Gilles Peskine0189e752018-02-03 23:57:22 +0100110#define BITS_TO_BYTES(bits) (((bits) + 7) / 8)
111#define BYTES_TO_BITS(bytes) ((bytes) * 8)
112
Gilles Peskinee59236f2018-01-27 23:32:46 +0100113/**@}*/
114
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100115/** \defgroup crypto_types Key and algorithm types
116 * @{
117 */
118
119typedef uint32_t psa_key_type_t;
120
Gilles Peskine98f0a242018-02-06 18:57:29 +0100121#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x00000000)
122#define PSA_KEY_TYPE_VENDOR_FLAG ((psa_key_type_t)0x80000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100123
Gilles Peskine98f0a242018-02-06 18:57:29 +0100124#define PSA_KEY_TYPE_CATEGORY_MASK ((psa_key_type_t)0x7e000000)
125#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x02000000)
126#define PSA_KEY_TYPE_CATEGORY_SYMMETRIC ((psa_key_type_t)0x04000000)
127#define PSA_KEY_TYPE_CATEGORY_ASYMMETRIC ((psa_key_type_t)0x06000000)
128#define PSA_KEY_TYPE_PAIR_FLAG ((psa_key_type_t)0x01000000)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100129
Gilles Peskine98f0a242018-02-06 18:57:29 +0100130#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x02000001)
131#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x04000001)
132#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x04000002)
133#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x04000003)
134#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x04000004)
135
136#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x06010000)
137#define PSA_KEY_TYPE_RSA_KEYPAIR ((psa_key_type_t)0x07010000)
138#define PSA_KEY_TYPE_ECC_BASE ((psa_key_type_t)0x06030000)
139#define PSA_KEY_TYPE_ECC_CURVE_MASK ((psa_key_type_t)0x0000ffff)
140
141#define PSA_KEY_TYPE_IS_VENDOR_DEFINED(type) \
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100142 (((type) & PSA_KEY_TYPE_VENDOR_FLAG) != 0)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100143#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) \
144 (((type) & PSA_KEY_TYPE_CATEGORY_MASK) == PSA_KEY_TYPE_CATEGORY_ASYMMETRIC)
145#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \
146 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG) == \
147 PSA_KEY_TYPE_CATEGORY_ASYMMETRIC))
148#define PSA_KEY_TYPE_IS_KEYPAIR(type) \
149 (((type) & (PSA_KEY_TYPE_CATEGORY_MASK | PSA_KEY_TYPE_PAIR_FLAG)) == \
150 (PSA_KEY_TYPE_CATEGORY_ASYMMETRIC | PSA_KEY_TYPE_PAIR_FLAG))
Gilles Peskine0189e752018-02-03 23:57:22 +0100151#define PSA_KEY_TYPE_IS_RSA(type) \
Gilles Peskine98f0a242018-02-06 18:57:29 +0100152 (((type) & ~PSA_KEY_TYPE_PAIR_FLAG) == PSA_KEY_TYPE_RSA_PUBLIC_KEY)
Gilles Peskinec66ea6a2018-02-03 22:43:28 +0100153#define PSA_KEY_TYPE_IS_ECC(type) \
Gilles Peskine98f0a242018-02-06 18:57:29 +0100154 (((type) & ~PSA_KEY_TYPE_ECC_CURVE_MASK) == PSA_KEY_TYPE_ECC_BASE)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100155
Gilles Peskine20035e32018-02-03 22:44:14 +0100156typedef uint32_t psa_algorithm_t;
157
Gilles Peskine98f0a242018-02-06 18:57:29 +0100158#define PSA_ALG_VENDOR_FLAG ((psa_algorithm_t)0x80000000)
159#define PSA_ALG_CATEGORY_MASK ((psa_algorithm_t)0x7f000000)
160#define PSA_ALG_CATEGORY_HASH ((psa_algorithm_t)0x01000000)
161#define PSA_ALG_CATEGORY_MAC ((psa_algorithm_t)0x02000000)
162#define PSA_ALG_CATEGORY_CIPHER ((psa_algorithm_t)0x04000000)
163#define PSA_ALG_CATEGORY_AEAD ((psa_algorithm_t)0x06000000)
164#define PSA_ALG_CATEGORY_SIGN ((psa_algorithm_t)0x10000000)
165#define PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION ((psa_algorithm_t)0x12000000)
166#define PSA_ALG_CATEGORY_KEY_AGREEMENT ((psa_algorithm_t)0x22000000)
167#define PSA_ALG_CATEGORY_KEY_DERIVATION ((psa_algorithm_t)0x30000000)
Gilles Peskine20035e32018-02-03 22:44:14 +0100168
Gilles Peskine98f0a242018-02-06 18:57:29 +0100169#define PSA_ALG_IS_VENDOR_DEFINED(alg) \
170 (((alg) & PSA_ALG_VENDOR_FLAG) != 0)
171#define PSA_ALG_IS_HASH(alg) \
172 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_HASH)
173#define PSA_ALG_IS_MAC(alg) \
174 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_MAC)
175#define PSA_ALG_IS_CIPHER(alg) \
176 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_CIPHER)
177#define PSA_ALG_IS_AEAD(alg) \
178 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_AEAD)
179#define PSA_ALG_IS_SIGN(alg) \
180 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_SIGN)
181#define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) \
182 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_ASYMMETRIC_ENCRYPTION)
183#define PSA_ALG_IS_KEY_AGREEMENT(alg) \
184 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_AGREEMENT)
185#define PSA_ALG_IS_KEY_DERIVATION(alg) \
186 (((alg) & PSA_ALG_CATEGORY_MASK) == PSA_ALG_CATEGORY_KEY_DERIVATION)
187
188#define PSA_ALG_HASH_MASK ((psa_algorithm_t)0x000000ff)
189#define PSA_ALG_MD2 ((psa_algorithm_t)0x01000001)
190#define PSA_ALG_MD4 ((psa_algorithm_t)0x01000002)
191#define PSA_ALG_MD5 ((psa_algorithm_t)0x01000003)
192#define PSA_ALG_SHA_256_128 ((psa_algorithm_t)0x01000004)
193#define PSA_ALG_RIPEMD160 ((psa_algorithm_t)0x01000005)
194#define PSA_ALG_SHA_1 ((psa_algorithm_t)0x01000006)
195#define PSA_ALG_SHA_256_160 ((psa_algorithm_t)0x01000007)
196#define PSA_ALG_SHA_224 ((psa_algorithm_t)0x01000008)
197#define PSA_ALG_SHA_256 ((psa_algorithm_t)0x01000009)
198#define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0100000a)
199#define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0100000b)
200#define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0100000c)
201#define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0100000d)
202#define PSA_ALG_SHA3_224 ((psa_algorithm_t)0x01000010)
203#define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x01000011)
204#define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x01000012)
205#define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x01000013)
206
207#define PSA_ALG_HMAC_BASE ((psa_algorithm_t)0x02800000)
208#define PSA_ALG_HMAC(hash_alg) \
209 (PSA_ALG_HMAC_BASE | (hash_alg))
210#define PSA_ALG_CBC_MAC ((psa_algorithm_t)0x02000001)
211#define PSA_ALG_CMAC ((psa_algorithm_t)0x02000002)
212#define PSA_ALG_GMAC ((psa_algorithm_t)0x02000003)
213
214#define PSA_ALG_BLOCK_CIPHER_BASE_MASK ((psa_algorithm_t)0x000000ff)
215#define PSA_ALG_BLOCK_CIPHER_PADDING_MASK ((psa_algorithm_t)0x007f0000)
216#define PSA_ALG_BLOCK_CIPHER_PAD_PKCS7 ((psa_algorithm_t)0x00010000)
217#define PSA_ALG_CBC_BASE ((psa_algorithm_t)0x04000001)
218#define PSA_ALG_CFB_BASE ((psa_algorithm_t)0x04000003)
219#define PSA_ALG_OFB_BASE ((psa_algorithm_t)0x04000004)
220#define PSA_ALG_XTS_BASE ((psa_algorithm_t)0x04000005)
221#define PSA_ALG_STREAM_CIPHER ((psa_algorithm_t)0x04800000)
222#define PSA_ALG_CTR ((psa_algorithm_t)0x04800001)
223
224#define PSA_ALG_CCM ((psa_algorithm_t)0x06000002)
225#define PSA_ALG_GCM ((psa_algorithm_t)0x06000003)
226
227#define PSA_ALG_RSA_PKCS1V15_RAW ((psa_algorithm_t)0x10010000)
228#define PSA_ALG_RSA_PSS_MGF1 ((psa_algorithm_t)0x10020000)
229#define PSA_ALG_RSA_OAEP ((psa_algorithm_t)0x12020000)
230#define PSA_ALG_RSA_PKCS1V15(hash_alg) \
231 (PSA_ALG_RSA_PKCS1V15_RAW | ((hash_alg) & PSA_ALG_HASH_MASK))
232#define PSA_ALG_IS_RSA_PKCS1V15(alg) \
Gilles Peskine20035e32018-02-03 22:44:14 +0100233 (((alg) & 0x7fffff00) == PSA_ALG_RSA_PKCS1V15_RAW)
Gilles Peskine98f0a242018-02-06 18:57:29 +0100234#define PSA_ALG_RSA_GET_HASH(alg) \
235 (((alg) & PSA_ALG_HASH_MASK) | PSA_ALG_CATEGORY_HASH)
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100236
237/**@}*/
238
239/** \defgroup key_management Key management
240 * @{
241 */
242
243/**
244 * \brief Import a key in binary format.
245 *
246 * This function supports any output from psa_export_key().
247 *
248 * \return * \c PSA_SUCCESS: success.
249 * * \c PSA_ERROR_NOT_SUPPORTED
250 * * \c PSA_ERROR_INVALID_ARGUMENT
251 * * \c PSA_ERROR_INSUFFICIENT_MEMORY
252 * * \c PSA_ERROR_COMMUNICATION_FAILURE
253 * * \c PSA_ERROR_HARDWARE_FAILURE
254 * * \c PSA_ERROR_TAMPERING_DETECTED
255 */
256psa_status_t psa_import_key(psa_key_slot_t key,
257 psa_key_type_t type,
258 const uint8_t *data,
259 size_t data_length);
260
261/**
262 * \brief Destroy a key.
263 *
264 * \return * \c PSA_SUCCESS: success.
265 * * \c PSA_ERROR_EMPTY_SLOT
266 * * \c PSA_ERROR_COMMUNICATION_FAILURE
267 * * \c PSA_ERROR_HARDWARE_FAILURE
268 * * \c PSA_ERROR_TAMPERING_DETECTED
269 */
270psa_status_t psa_destroy_key(psa_key_slot_t key);
271
272/**
273 * \brief Get basic metadata about a key.
274 *
275 * \return * \c PSA_SUCCESS: success.
276 * * \c PSA_ERROR_EMPTY_SLOT
277 * * \c PSA_ERROR_COMMUNICATION_FAILURE
278 * * \c PSA_ERROR_HARDWARE_FAILURE
279 * * \c PSA_ERROR_TAMPERING_DETECTED
280 */
281psa_status_t psa_get_key_information(psa_key_slot_t key,
282 psa_key_type_t *type,
283 size_t *bits);
284
285/**
286 * \brief Export a key in binary format.
287 *
288 * The output of this function can be passed to psa_import_key() to
289 * create an equivalent object.
290 *
291 * If a key is created with psa_import_key() and then exported with
292 * this function, it is not guaranteed that the resulting data is
293 * identical: the implementation may choose a different representation
294 * of the same key.
295 *
296 * \return * \c PSA_SUCCESS: success.
297 * * \c PSA_ERROR_EMPTY_SLOT
298 * * \c PSA_ERROR_COMMUNICATION_FAILURE
299 * * \c PSA_ERROR_HARDWARE_FAILURE
300 * * \c PSA_ERROR_TAMPERING_DETECTED
301 */
302psa_status_t psa_export_key(psa_key_slot_t key,
303 uint8_t *data,
304 size_t data_size,
305 size_t *data_length);
306
Gilles Peskine20035e32018-02-03 22:44:14 +0100307
308/**@}*/
309
310/** \defgroup asymmetric Asymmetric cryptography
311 * @{
312 */
313
314/**
Gilles Peskine0189e752018-02-03 23:57:22 +0100315 * \brief Maximum ECDSA signature size for a given curve bit size
316 *
317 * \param curve_bits Curve size in bits
318 * \return Maximum signature size in bytes
319 *
320 * \note This macro returns a compile-time constant if its argument is one.
321 *
322 * \warning This macro may evaluate its argument multiple times.
323 */
324/*
325 * RFC 4492 page 20:
326 *
327 * Ecdsa-Sig-Value ::= SEQUENCE {
328 * r INTEGER,
329 * s INTEGER
330 * }
331 *
332 * Size is at most
333 * 1 (tag) + 1 (len) + 1 (initial 0) + curve_bytes for each of r and s,
334 * twice that + 1 (tag) + 2 (len) for the sequence
335 * (assuming curve_bytes is less than 126 for r and s,
336 * and less than 124 (total len <= 255) for the sequence)
337 */
338#define PSA_ECDSA_SIGNATURE_SIZE(curve_bits) \
339 ( /*T,L of SEQUENCE*/ ((curve_bits) >= 61 * 8 ? 3 : 2) + \
340 /*T,L of r,s*/ 2 * (((curve_bits) >= 127 * 8 ? 3 : 2) + \
341 /*V of r,s*/ ((curve_bits) + 8) / 8))
342
343
344#define PSA_ASYMMETRIC_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \
345 (PSA_KEY_TYPE_IS_RSA(key_type) ? ((void)alg, BITS_TO_BYTES(key_bits)) : \
346 PSA_KEY_TYPE_IS_ECC(key_type) ? PSA_ECDSA_SIGNATURE_SIZE(key_bits) : \
347 0)
348
349/**
Gilles Peskine20035e32018-02-03 22:44:14 +0100350 * \brief Sign a hash or short message with a private key.
351 *
352 */
353psa_status_t psa_asymmetric_sign(psa_key_slot_t key,
354 psa_algorithm_t alg,
355 const uint8_t *hash,
356 size_t hash_length,
357 const uint8_t *salt,
358 size_t salt_length,
359 uint8_t *signature,
360 size_t signature_size,
361 size_t *signature_length);
362
363/**
364 * \brief Verify the signature a hash or short message using a public key.
365 *
366 */
367psa_status_t psa_asymmetric_verify(psa_key_slot_t key,
368 psa_algorithm_t alg,
369 const uint8_t *hash,
370 size_t hash_length,
371 const uint8_t *salt,
372 size_t salt_length,
373 uint8_t *signature,
374 size_t signature_size);
375
Gilles Peskine2f9c4dc2018-01-28 13:16:24 +0100376/**@}*/
377
Gilles Peskinee59236f2018-01-27 23:32:46 +0100378#ifdef __cplusplus
379}
380#endif
381
382#include "crypto_extra.h"
383
384#endif /* PSA_CRYPTO_H */