mbed TLS v2.24.0
crypto.h
Go to the documentation of this file.
1 
5 /*
6  * Copyright The Mbed TLS Contributors
7  * SPDX-License-Identifier: Apache-2.0
8  *
9  * Licensed under the Apache License, Version 2.0 (the "License"); you may
10  * not use this file except in compliance with the License.
11  * You may obtain a copy of the License at
12  *
13  * http://www.apache.org/licenses/LICENSE-2.0
14  *
15  * Unless required by applicable law or agreed to in writing, software
16  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18  * See the License for the specific language governing permissions and
19  * limitations under the License.
20  */
21 
22 #ifndef PSA_CRYPTO_H
23 #define PSA_CRYPTO_H
24 
25 #include "crypto_platform.h"
26 
27 #include <stddef.h>
28 
29 #ifdef __DOXYGEN_ONLY__
30 /* This __DOXYGEN_ONLY__ block contains mock definitions for things that
31  * must be defined in the crypto_platform.h header. These mock definitions
32  * are present in this file as a convenience to generate pretty-printed
33  * documentation that includes those definitions. */
34 
47 typedef _unsigned_integral_type_ psa_key_handle_t;
48 
50 #endif /* __DOXYGEN_ONLY__ */
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55 
56 /* The file "crypto_types.h" declares types that encode errors,
57  * algorithms, key types, policies, etc. */
58 #include "crypto_types.h"
59 
67 #define PSA_CRYPTO_API_VERSION_MAJOR 1
68 
72 #define PSA_CRYPTO_API_VERSION_MINOR 0
73 
76 /* The file "crypto_values.h" declares macros to build and analyze values
77  * of integral types defined in "crypto_types.h". */
78 #include "crypto_values.h"
79 
109 
121 #ifdef __DOXYGEN_ONLY__
122 /* This is an example definition for documentation purposes.
123  * Implementations should define a suitable value in `crypto_struct.h`.
124  */
125 #define PSA_KEY_ATTRIBUTES_INIT {0}
126 #endif
127 
131 
152 static void psa_set_key_id(psa_key_attributes_t *attributes,
153  psa_key_id_t id);
154 
180 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
181  psa_key_lifetime_t lifetime);
182 
195 static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes);
196 
208  const psa_key_attributes_t *attributes);
209 
226 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
227  psa_key_usage_t usage_flags);
228 
240  const psa_key_attributes_t *attributes);
241 
264 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
265  psa_algorithm_t alg);
266 
267 
279  const psa_key_attributes_t *attributes);
280 
295 static void psa_set_key_type(psa_key_attributes_t *attributes,
296  psa_key_type_t type);
297 
298 
313 static void psa_set_key_bits(psa_key_attributes_t *attributes,
314  size_t bits);
315 
326 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
327 
338 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
339 
367  psa_key_attributes_t *attributes);
368 
382 
440  psa_key_handle_t *handle);
441 
442 
476 
562  const psa_key_attributes_t *attributes,
563  psa_key_handle_t *target_handle);
564 
565 
614 
691  const uint8_t *data,
692  size_t data_length,
693  psa_key_handle_t *handle);
694 
695 
696 
782  uint8_t *data,
783  size_t data_size,
784  size_t *data_length);
785 
852  uint8_t *data,
853  size_t data_size,
854  size_t *data_length);
855 
856 
857 
897  const uint8_t *input,
898  size_t input_length,
899  uint8_t *hash,
900  size_t hash_size,
901  size_t *hash_length);
902 
933  const uint8_t *input,
934  size_t input_length,
935  const uint8_t *hash,
936  size_t hash_length);
937 
967 
973 #ifdef __DOXYGEN_ONLY__
974 /* This is an example definition for documentation purposes.
975  * Implementations should define a suitable value in `crypto_struct.h`.
976  */
977 #define PSA_HASH_OPERATION_INIT {0}
978 #endif
979 
983 
1035 
1061  const uint8_t *input,
1062  size_t input_length);
1063 
1108  uint8_t *hash,
1109  size_t hash_size,
1110  size_t *hash_length);
1111 
1150  const uint8_t *hash,
1151  size_t hash_length);
1152 
1179 
1209 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1210  psa_hash_operation_t *target_operation);
1211 
1261  const uint8_t *input,
1262  size_t input_length,
1263  uint8_t *mac,
1264  size_t mac_size,
1265  size_t *mac_length);
1266 
1301  const uint8_t *input,
1302  size_t input_length,
1303  const uint8_t *mac,
1304  size_t mac_length);
1305 
1335 
1341 #ifdef __DOXYGEN_ONLY__
1342 /* This is an example definition for documentation purposes.
1343  * Implementations should define a suitable value in `crypto_struct.h`.
1344  */
1345 #define PSA_MAC_OPERATION_INIT {0}
1346 #endif
1347 
1351 
1412  psa_key_handle_t handle,
1414 
1474  psa_key_handle_t handle,
1476 
1505  const uint8_t *input,
1506  size_t input_length);
1507 
1555  uint8_t *mac,
1556  size_t mac_size,
1557  size_t *mac_length);
1558 
1599  const uint8_t *mac,
1600  size_t mac_length);
1601 
1628 
1677  const uint8_t *input,
1678  size_t input_length,
1679  uint8_t *output,
1680  size_t output_size,
1681  size_t *output_length);
1682 
1723  const uint8_t *input,
1724  size_t input_length,
1725  uint8_t *output,
1726  size_t output_size,
1727  size_t *output_length);
1728 
1758 
1764 #ifdef __DOXYGEN_ONLY__
1765 /* This is an example definition for documentation purposes.
1766  * Implementations should define a suitable value in `crypto_struct.h`.
1767  */
1768 #define PSA_CIPHER_OPERATION_INIT {0}
1769 #endif
1770 
1774 
1835  psa_key_handle_t handle,
1837 
1898  psa_key_handle_t handle,
1900 
1936  uint8_t *iv,
1937  size_t iv_size,
1938  size_t *iv_length);
1939 
1978  const uint8_t *iv,
1979  size_t iv_length);
1980 
2020  const uint8_t *input,
2021  size_t input_length,
2022  uint8_t *output,
2023  size_t output_size,
2024  size_t *output_length);
2025 
2073  uint8_t *output,
2074  size_t output_size,
2075  size_t *output_length);
2076 
2103 
2160  const uint8_t *nonce,
2161  size_t nonce_length,
2162  const uint8_t *additional_data,
2163  size_t additional_data_length,
2164  const uint8_t *plaintext,
2165  size_t plaintext_length,
2166  uint8_t *ciphertext,
2167  size_t ciphertext_size,
2168  size_t *ciphertext_length);
2169 
2220  const uint8_t *nonce,
2221  size_t nonce_length,
2222  const uint8_t *additional_data,
2223  size_t additional_data_length,
2224  const uint8_t *ciphertext,
2225  size_t ciphertext_length,
2226  uint8_t *plaintext,
2227  size_t plaintext_size,
2228  size_t *plaintext_length);
2229 
2259 
2265 #ifdef __DOXYGEN_ONLY__
2266 /* This is an example definition for documentation purposes.
2267  * Implementations should define a suitable value in `crypto_struct.h`.
2268  */
2269 #define PSA_AEAD_OPERATION_INIT {0}
2270 #endif
2271 
2275 
2342  psa_key_handle_t handle,
2344 
2408  psa_key_handle_t handle,
2410 
2448  uint8_t *nonce,
2449  size_t nonce_size,
2450  size_t *nonce_length);
2451 
2489  const uint8_t *nonce,
2490  size_t nonce_length);
2491 
2535  size_t ad_length,
2536  size_t plaintext_length);
2537 
2584  const uint8_t *input,
2585  size_t input_length);
2586 
2662  const uint8_t *input,
2663  size_t input_length,
2664  uint8_t *output,
2665  size_t output_size,
2666  size_t *output_length);
2667 
2738  uint8_t *ciphertext,
2739  size_t ciphertext_size,
2740  size_t *ciphertext_length,
2741  uint8_t *tag,
2742  size_t tag_size,
2743  size_t *tag_length);
2744 
2818  uint8_t *plaintext,
2819  size_t plaintext_size,
2820  size_t *plaintext_length,
2821  const uint8_t *tag,
2822  size_t tag_length);
2823 
2850 
2901  const uint8_t *hash,
2902  size_t hash_length,
2903  uint8_t *signature,
2904  size_t signature_size,
2905  size_t *signature_length);
2906 
2947  const uint8_t *hash,
2948  size_t hash_length,
2949  const uint8_t *signature,
2950  size_t signature_length);
2951 
3004  const uint8_t *input,
3005  size_t input_length,
3006  const uint8_t *salt,
3007  size_t salt_length,
3008  uint8_t *output,
3009  size_t output_size,
3010  size_t *output_length);
3011 
3064  const uint8_t *input,
3065  size_t input_length,
3066  const uint8_t *salt,
3067  size_t salt_length,
3068  uint8_t *output,
3069  size_t output_size,
3070  size_t *output_length);
3071 
3108 
3114 #ifdef __DOXYGEN_ONLY__
3115 /* This is an example definition for documentation purposes.
3116  * Implementations should define a suitable value in `crypto_struct.h`.
3117  */
3118 #define PSA_KEY_DERIVATION_OPERATION_INIT {0}
3119 #endif
3120 
3124 
3185  psa_key_derivation_operation_t *operation,
3187 
3209  const psa_key_derivation_operation_t *operation,
3210  size_t *capacity);
3211 
3238  psa_key_derivation_operation_t *operation,
3239  size_t capacity);
3240 
3248 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3249 
3293  psa_key_derivation_operation_t *operation,
3295  const uint8_t *data,
3296  size_t data_length);
3297 
3346  psa_key_derivation_operation_t *operation,
3348  psa_key_handle_t handle);
3349 
3415  psa_key_derivation_operation_t *operation,
3417  psa_key_handle_t private_key,
3418  const uint8_t *peer_key,
3419  size_t peer_key_length);
3420 
3460  psa_key_derivation_operation_t *operation,
3461  uint8_t *output,
3462  size_t output_length);
3463 
3599  const psa_key_attributes_t *attributes,
3600  psa_key_derivation_operation_t *operation,
3601  psa_key_handle_t *handle);
3602 
3627  psa_key_derivation_operation_t *operation);
3628 
3680  psa_key_handle_t private_key,
3681  const uint8_t *peer_key,
3682  size_t peer_key_length,
3683  uint8_t *output,
3684  size_t output_size,
3685  size_t *output_length);
3686 
3717 psa_status_t psa_generate_random(uint8_t *output,
3718  size_t output_size);
3719 
3761  psa_key_handle_t *handle);
3762 
3765 #ifdef __cplusplus
3766 }
3767 #endif
3768 
3769 /* The file "crypto_sizes.h" contains definitions for size calculation
3770  * macros whose definitions are implementation-specific. */
3771 #include "crypto_sizes.h"
3772 
3773 /* The file "crypto_struct.h" contains definitions for
3774  * implementation-specific structs that are declared above. */
3775 #include "crypto_struct.h"
3776 
3777 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3778  * can include vendor-defined algorithms, extra functions, etc. */
3779 #include "crypto_extra.h"
3780 
3781 #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)
static void psa_set_key_id(psa_key_attributes_t *attributes, psa_key_id_t id)
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)
static psa_key_derivation_operation_t psa_key_derivation_operation_init(void)
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_algorithm_t alg
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.
static void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits)
psa_algorithm_t alg
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:380
PSA cryptography module: Mbed TLS structured type implementations.
PSA cryptography module: Mbed TLS vendor extensions.
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)
static psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *attributes)
static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
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)
static void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
static psa_hash_operation_t psa_hash_operation_init(void)
psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_length)
static psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *attributes)
psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity)
static void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t type)
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)
static psa_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes)
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.
static size_t psa_get_key_bits(const psa_key_attributes_t *attributes)
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)
uint16_t psa_key_handle_t
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_status_t psa_aead_set_lengths(psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length)
psa_algorithm_t alg
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:96
psa_algorithm_t alg
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)
static psa_cipher_operation_t psa_cipher_operation_init(void)
psa_status_t psa_hash_setup(psa_hash_operation_t *operation, psa_algorithm_t alg)
PSA cryptography module: Mbed TLS platform definitions.
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:246
static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg)
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:64
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)
static psa_aead_operation_t psa_aead_operation_init(void)
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.
static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes)
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)
static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes)
psa_status_t psa_hash_abort(psa_hash_operation_t *operation)
static psa_key_attributes_t psa_key_attributes_init(void)
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:139
static psa_mac_operation_t psa_mac_operation_init(void)
psa_algorithm_t alg
Definition: crypto_struct.h:82
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:53
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)