TF-M Reference Manual  1.2.0
TrustedFirmware-M
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
crypto.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018-2020, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
12 #ifndef PSA_CRYPTO_H
13 #define PSA_CRYPTO_H
14 
15 #include <stddef.h>
16 
17 #ifdef __DOXYGEN_ONLY__
18 /* This __DOXYGEN_ONLY__ block contains mock definitions for things that
19  * must be defined in the crypto_platform.h header. These mock definitions
20  * are present in this file as a convenience to generate pretty-printed
21  * documentation that includes those definitions. */
22 
35 typedef _unsigned_integral_type_ psa_key_handle_t;
36 
38 #endif /* __DOXYGEN_ONLY__ */
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 /* The file "crypto_types.h" declares types that encode errors,
45  * algorithms, key types, policies, etc. */
46 #include "psa/crypto_types.h"
47 
55 #define PSA_CRYPTO_API_VERSION_MAJOR 1
56 
60 #define PSA_CRYPTO_API_VERSION_MINOR 0
61 
64 /* The file "crypto_values.h" declares macros to build and analyze values
65  * of integral types defined in "crypto_types.h". */
66 #include "psa/crypto_values.h"
67 
97 
109 #ifdef __DOXYGEN_ONLY__
110 /* This is an example definition for documentation purposes.
111  * Implementations should define a suitable value in `crypto_struct.h`.
112  */
113 #define PSA_KEY_ATTRIBUTES_INIT {0}
114 #endif
115 
118 static psa_key_attributes_t psa_key_attributes_init(void);
119 
140 static void psa_set_key_id(psa_key_attributes_t *attributes,
141  psa_key_id_t id);
142 
168 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
169  psa_key_lifetime_t lifetime);
170 
183 static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
184 
195 static psa_key_lifetime_t psa_get_key_lifetime(
196  const psa_key_attributes_t *attributes);
197 
214 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
215  psa_key_usage_t usage_flags);
216 
227 static psa_key_usage_t psa_get_key_usage_flags(
228  const psa_key_attributes_t *attributes);
229 
252 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
253  psa_algorithm_t alg);
254 
255 
266 static psa_algorithm_t psa_get_key_algorithm(
267  const psa_key_attributes_t *attributes);
268 
283 static void psa_set_key_type(psa_key_attributes_t *attributes,
284  psa_key_type_t type);
285 
286 
301 static void psa_set_key_bits(psa_key_attributes_t *attributes,
302  size_t bits);
303 
314 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
315 
326 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
327 
355  psa_key_attributes_t *attributes);
356 
370 
428  psa_key_handle_t *handle);
429 
430 
464 
550  const psa_key_attributes_t *attributes,
551  psa_key_handle_t *target_handle);
552 
553 
602 
679  const uint8_t *data,
680  size_t data_length,
681  psa_key_handle_t *handle);
682 
683 
684 
770  uint8_t *data,
771  size_t data_size,
772  size_t *data_length);
773 
840  uint8_t *data,
841  size_t data_size,
842  size_t *data_length);
843 
844 
845 
885  const uint8_t *input,
886  size_t input_length,
887  uint8_t *hash,
888  size_t hash_size,
889  size_t *hash_length);
890 
921  const uint8_t *input,
922  size_t input_length,
923  const uint8_t *hash,
924  size_t hash_length);
925 
955 
961 #ifdef __DOXYGEN_ONLY__
962 /* This is an example definition for documentation purposes.
963  * Implementations should define a suitable value in `crypto_struct.h`.
964  */
965 #define PSA_HASH_OPERATION_INIT {0}
966 #endif
967 
971 
1022  psa_algorithm_t alg);
1023 
1049  const uint8_t *input,
1050  size_t input_length);
1051 
1096  uint8_t *hash,
1097  size_t hash_size,
1098  size_t *hash_length);
1099 
1138  const uint8_t *hash,
1139  size_t hash_length);
1140 
1167 
1197 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1198  psa_hash_operation_t *target_operation);
1199 
1248  psa_algorithm_t alg,
1249  const uint8_t *input,
1250  size_t input_length,
1251  uint8_t *mac,
1252  size_t mac_size,
1253  size_t *mac_length);
1254 
1288  psa_algorithm_t alg,
1289  const uint8_t *input,
1290  size_t input_length,
1291  const uint8_t *mac,
1292  size_t mac_length);
1293 
1323 
1329 #ifdef __DOXYGEN_ONLY__
1330 /* This is an example definition for documentation purposes.
1331  * Implementations should define a suitable value in `crypto_struct.h`.
1332  */
1333 #define PSA_MAC_OPERATION_INIT {0}
1334 #endif
1335 
1339 
1401  psa_algorithm_t alg);
1402 
1463  psa_algorithm_t alg);
1464 
1493  const uint8_t *input,
1494  size_t input_length);
1495 
1543  uint8_t *mac,
1544  size_t mac_size,
1545  size_t *mac_length);
1546 
1587  const uint8_t *mac,
1588  size_t mac_length);
1589 
1616 
1664  psa_algorithm_t alg,
1665  const uint8_t *input,
1666  size_t input_length,
1667  uint8_t *output,
1668  size_t output_size,
1669  size_t *output_length);
1670 
1710  psa_algorithm_t alg,
1711  const uint8_t *input,
1712  size_t input_length,
1713  uint8_t *output,
1714  size_t output_size,
1715  size_t *output_length);
1716 
1746 
1752 #ifdef __DOXYGEN_ONLY__
1753 /* This is an example definition for documentation purposes.
1754  * Implementations should define a suitable value in `crypto_struct.h`.
1755  */
1756 #define PSA_CIPHER_OPERATION_INIT {0}
1757 #endif
1758 
1762 
1824  psa_algorithm_t alg);
1825 
1887  psa_algorithm_t alg);
1888 
1924  uint8_t *iv,
1925  size_t iv_size,
1926  size_t *iv_length);
1927 
1966  const uint8_t *iv,
1967  size_t iv_length);
1968 
2008  const uint8_t *input,
2009  size_t input_length,
2010  uint8_t *output,
2011  size_t output_size,
2012  size_t *output_length);
2013 
2061  uint8_t *output,
2062  size_t output_size,
2063  size_t *output_length);
2064 
2091 
2147  psa_algorithm_t alg,
2148  const uint8_t *nonce,
2149  size_t nonce_length,
2150  const uint8_t *additional_data,
2151  size_t additional_data_length,
2152  const uint8_t *plaintext,
2153  size_t plaintext_length,
2154  uint8_t *ciphertext,
2155  size_t ciphertext_size,
2156  size_t *ciphertext_length);
2157 
2207  psa_algorithm_t alg,
2208  const uint8_t *nonce,
2209  size_t nonce_length,
2210  const uint8_t *additional_data,
2211  size_t additional_data_length,
2212  const uint8_t *ciphertext,
2213  size_t ciphertext_length,
2214  uint8_t *plaintext,
2215  size_t plaintext_size,
2216  size_t *plaintext_length);
2217 
2247 
2253 #ifdef __DOXYGEN_ONLY__
2254 /* This is an example definition for documentation purposes.
2255  * Implementations should define a suitable value in `crypto_struct.h`.
2256  */
2257 #define PSA_AEAD_OPERATION_INIT {0}
2258 #endif
2259 
2262 static psa_aead_operation_t psa_aead_operation_init(void);
2263 
2331  psa_algorithm_t alg);
2332 
2397  psa_algorithm_t alg);
2398 
2436  uint8_t *nonce,
2437  size_t nonce_size,
2438  size_t *nonce_length);
2439 
2477  const uint8_t *nonce,
2478  size_t nonce_length);
2479 
2523  size_t ad_length,
2524  size_t plaintext_length);
2525 
2572  const uint8_t *input,
2573  size_t input_length);
2574 
2650  const uint8_t *input,
2651  size_t input_length,
2652  uint8_t *output,
2653  size_t output_size,
2654  size_t *output_length);
2655 
2726  uint8_t *ciphertext,
2727  size_t ciphertext_size,
2728  size_t *ciphertext_length,
2729  uint8_t *tag,
2730  size_t tag_size,
2731  size_t *tag_length);
2732 
2806  uint8_t *plaintext,
2807  size_t plaintext_size,
2808  size_t *plaintext_length,
2809  const uint8_t *tag,
2810  size_t tag_length);
2811 
2838 
2888  psa_algorithm_t alg,
2889  const uint8_t *hash,
2890  size_t hash_length,
2891  uint8_t *signature,
2892  size_t signature_size,
2893  size_t *signature_length);
2894 
2934  psa_algorithm_t alg,
2935  const uint8_t *hash,
2936  size_t hash_length,
2937  const uint8_t *signature,
2938  size_t signature_length);
2939 
2991  psa_algorithm_t alg,
2992  const uint8_t *input,
2993  size_t input_length,
2994  const uint8_t *salt,
2995  size_t salt_length,
2996  uint8_t *output,
2997  size_t output_size,
2998  size_t *output_length);
2999 
3051  psa_algorithm_t alg,
3052  const uint8_t *input,
3053  size_t input_length,
3054  const uint8_t *salt,
3055  size_t salt_length,
3056  uint8_t *output,
3057  size_t output_size,
3058  size_t *output_length);
3059 
3096 
3102 #ifdef __DOXYGEN_ONLY__
3103 /* This is an example definition for documentation purposes.
3104  * Implementations should define a suitable value in `crypto_struct.h`.
3105  */
3106 #define PSA_KEY_DERIVATION_OPERATION_INIT {0}
3107 #endif
3108 
3111 static psa_key_derivation_operation_t psa_key_derivation_operation_init(void);
3112 
3173  psa_key_derivation_operation_t *operation,
3174  psa_algorithm_t alg);
3175 
3197  const psa_key_derivation_operation_t *operation,
3198  size_t *capacity);
3199 
3226  psa_key_derivation_operation_t *operation,
3227  size_t capacity);
3228 
3236 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3237 
3281  psa_key_derivation_operation_t *operation,
3283  const uint8_t *data,
3284  size_t data_length);
3285 
3334  psa_key_derivation_operation_t *operation,
3337 
3403  psa_key_derivation_operation_t *operation,
3405  psa_key_handle_t private_key,
3406  const uint8_t *peer_key,
3407  size_t peer_key_length);
3408 
3448  psa_key_derivation_operation_t *operation,
3449  uint8_t *output,
3450  size_t output_length);
3451 
3587  const psa_key_attributes_t *attributes,
3588  psa_key_derivation_operation_t *operation,
3590 
3615  psa_key_derivation_operation_t *operation);
3616 
3668  psa_key_handle_t private_key,
3669  const uint8_t *peer_key,
3670  size_t peer_key_length,
3671  uint8_t *output,
3672  size_t output_size,
3673  size_t *output_length);
3674 
3705 psa_status_t psa_generate_random(uint8_t *output,
3706  size_t output_size);
3707 
3750 
3753 #ifdef __cplusplus
3754 }
3755 #endif
3756 
3757 /* The file "crypto_sizes.h" contains definitions for size calculation
3758  * macros whose definitions are implementation-specific. */
3759 #include "psa/crypto_sizes.h"
3760 
3761 /* The file "crypto_client_struct.h" contains definitions for structures
3762  * whose definitions differ in the client view and the PSA server
3763  * implementation in TF-M. */
3764 #include "psa/crypto_client_struct.h"
3765 
3766 
3767 /* The file "crypto_struct.h" contains definitions for
3768  * implementation-specific structs that are declared above. */
3769 #include "psa/crypto_struct.h"
3770 
3771 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3772  * can include vendor-defined algorithms, extra functions, etc. */
3773 #include "psa/crypto_extra.h"
3774 
3775 #endif /* PSA_CRYPTO_H */
psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
void psa_reset_key_attributes(psa_key_attributes_t *attributes)
psa_status_t psa_cipher_update(psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t psa_generate_random(uint8_t *output, size_t output_size)
Generate random bytes.
psa_status_t psa_export_key(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
Export a key in binary format.
psa_status_t psa_mac_sign_finish(psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_length)
psa_status_t psa_destroy_key(psa_key_handle_t handle)
Destroy a key.
psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
psa_status_t psa_sign_hash(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
Sign a hash or short message with a private key.
psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t *operation, size_t capacity)
psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t psa_close_key(psa_key_handle_t handle)
psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t *operation)
psa_status_t psa_cipher_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
psa_status_t psa_export_public_key(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
Export a public key or the public part of a key pair in binary format.
PSA cryptography module: type aliases.
psa_status_t psa_mac_abort(psa_mac_operation_t *operation)
uint16_t psa_key_derivation_step_t
Encoding of the step of a key derivation.
Definition: crypto_types.h:356
#define psa_mac_operation_init
Definition: crypto_spe.h:105
PSA cryptography module: structured type implementations.
PSA cryptography module: vendor extensions.
uint32_t psa_key_id_t
Definition: crypto_types.h:223
#define psa_cipher_operation_init
Definition: crypto_spe.h:71
psa_status_t psa_verify_hash(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
Verify the signature a hash or short message using a public key.
psa_status_t psa_hash_compute(psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *hash, size_t hash_size, size_t *hash_length)
psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, psa_key_handle_t handle)
psa_status_t psa_hash_update(psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length)
psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity)
psa_status_t psa_aead_finish(psa_aead_operation_t *operation, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length, uint8_t *tag, size_t tag_size, size_t *tag_length)
psa_status_t psa_asymmetric_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
Encrypt a short message with a public key.
psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
psa_status_t psa_asymmetric_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *salt, size_t salt_length, uint8_t *output, size_t output_size, size_t *output_length)
Decrypt a short message with a private key.
PSA cryptography module: macros to build and analyze integer values.
psa_status_t psa_cipher_finish(psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t psa_aead_update_ad(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, psa_key_handle_t *handle)
Import a key in binary format.
psa_status_t psa_hash_verify(psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)
PSA cryptography client key attribute definitions.
psa_status_t psa_aead_set_lengths(psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length)
psa_status_t psa_aead_decrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *ciphertext, size_t ciphertext_length, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length)
psa_status_t psa_mac_verify(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *mac, size_t mac_length)
psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
psa_status_t psa_copy_key(psa_key_handle_t source_handle, const psa_key_attributes_t *attributes, psa_key_handle_t *target_handle)
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:90
psa_status_t psa_aead_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *nonce, size_t nonce_length, const uint8_t *additional_data, size_t additional_data_length, const uint8_t *plaintext, size_t plaintext_length, uint8_t *ciphertext, size_t ciphertext_size, size_t *ciphertext_length)
psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length)
psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation, uint8_t *nonce, size_t nonce_size, size_t *nonce_length)
psa_status_t psa_hash_setup(psa_hash_operation_t *operation, psa_algorithm_t alg)
psa_status_t psa_aead_decrypt_setup(psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
psa_status_t psa_cipher_generate_iv(psa_cipher_operation_t *operation, uint8_t *iv, size_t iv_size, size_t *iv_length)
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: crypto_types.h:233
psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
uint16_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:58
psa_status_t psa_get_key_attributes(psa_key_handle_t handle, psa_key_attributes_t *attributes)
psa_status_t psa_crypto_init(void)
Library initialization.
psa_status_t psa_key_derivation_output_bytes(psa_key_derivation_operation_t *operation, uint8_t *output, size_t output_length)
_unsigned_integral_type_ psa_key_handle_t
Key handle.
Definition: crypto.h:35
psa_status_t psa_key_derivation_input_bytes(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length)
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, psa_key_handle_t *handle)
Generate a key or key pair.
PSA cryptography module: Mbed TLS buffer size macros.
psa_status_t psa_aead_verify(psa_aead_operation_t *operation, uint8_t *plaintext, size_t plaintext_size, size_t *plaintext_length, const uint8_t *tag, size_t tag_length)
psa_status_t psa_key_derivation_key_agreement(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length)
#define psa_hash_operation_init
Definition: crypto_spe.h:87
psa_status_t psa_hash_abort(psa_hash_operation_t *operation)
psa_status_t psa_open_key(psa_key_id_t id, psa_key_handle_t *handle)
psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg)
psa_status_t psa_mac_compute(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *mac, size_t mac_size, size_t *mac_length)
psa_status_t psa_aead_abort(psa_aead_operation_t *operation)
psa_status_t psa_aead_update(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
uint32_t psa_key_lifetime_t
Definition: crypto_types.h:133
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:43
psa_status_t psa_mac_update(psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation)
psa_status_t psa_hash_compare(psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *hash, size_t hash_length)
psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t *attributes, psa_key_derivation_operation_t *operation, psa_key_handle_t *handle)
psa_status_t psa_cipher_encrypt(psa_key_handle_t handle, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *output, size_t output_size, size_t *output_length)
psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)