mbed TLS v2.28.2
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
40#endif /* __DOXYGEN_ONLY__ */
41
42#ifdef __cplusplus
43extern "C" {
44#endif
45
46/* The file "crypto_types.h" declares types that encode errors,
47 * algorithms, key types, policies, etc. */
48#include "crypto_types.h"
49
57#define PSA_CRYPTO_API_VERSION_MAJOR 1
58
62#define PSA_CRYPTO_API_VERSION_MINOR 0
63
66/* The file "crypto_values.h" declares macros to build and analyze values
67 * of integral types defined in "crypto_types.h". */
68#include "crypto_values.h"
69
103
115#ifdef __DOXYGEN_ONLY__
116/* This is an example definition for documentation purposes.
117 * Implementations should define a suitable value in `crypto_struct.h`.
118 */
119#define PSA_KEY_ATTRIBUTES_INIT {0}
120#endif
121
125
146static void psa_set_key_id( psa_key_attributes_t *attributes,
148
149#ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
164static void mbedtls_set_key_owner_id( psa_key_attributes_t *attributes,
165 mbedtls_key_owner_id_t owner );
166#endif
167
194 psa_key_lifetime_t lifetime);
195
209 const psa_key_attributes_t *attributes);
210
222 const psa_key_attributes_t *attributes);
223
241 psa_key_usage_t usage_flags);
242
254 const psa_key_attributes_t *attributes);
255
287 psa_algorithm_t alg);
288
289
301 const psa_key_attributes_t *attributes);
302
318 psa_key_type_t type);
319
320
336 size_t bits);
337
349
360static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
361
391 psa_key_attributes_t *attributes);
392
406
435
525 const psa_key_attributes_t *attributes,
526 mbedtls_svc_key_id_t *target_key);
527
528
575
654 const uint8_t *data,
655 size_t data_length,
657
658
659
749 uint8_t *data,
750 size_t data_size,
751 size_t *data_length);
752
824 uint8_t *data,
825 size_t data_size,
826 size_t *data_length);
827
828
829
868 const uint8_t *input,
869 size_t input_length,
870 uint8_t *hash,
871 size_t hash_size,
872 size_t *hash_length);
873
903 const uint8_t *input,
904 size_t input_length,
905 const uint8_t *hash,
906 size_t hash_length);
907
937
943#ifdef __DOXYGEN_ONLY__
944/* This is an example definition for documentation purposes.
945 * Implementations should define a suitable value in `crypto_struct.h`.
946 */
947#define PSA_HASH_OPERATION_INIT {0}
948#endif
949
953
1003 psa_algorithm_t alg);
1004
1029 const uint8_t *input,
1030 size_t input_length);
1031
1075 uint8_t *hash,
1076 size_t hash_size,
1077 size_t *hash_length);
1078
1116 const uint8_t *hash,
1117 size_t hash_length);
1118
1145
1174 psa_hash_operation_t *target_operation);
1175
1225 psa_algorithm_t alg,
1226 const uint8_t *input,
1227 size_t input_length,
1228 uint8_t *mac,
1229 size_t mac_size,
1230 size_t *mac_length);
1231
1266 psa_algorithm_t alg,
1267 const uint8_t *input,
1268 size_t input_length,
1269 const uint8_t *mac,
1270 size_t mac_length);
1271
1301
1307#ifdef __DOXYGEN_ONLY__
1308/* This is an example definition for documentation purposes.
1309 * Implementations should define a suitable value in `crypto_struct.h`.
1310 */
1311#define PSA_MAC_OPERATION_INIT {0}
1312#endif
1313
1317
1378 psa_algorithm_t alg);
1379
1440 psa_algorithm_t alg);
1441
1469 const uint8_t *input,
1470 size_t input_length);
1471
1518 uint8_t *mac,
1519 size_t mac_size,
1520 size_t *mac_length);
1521
1561 const uint8_t *mac,
1562 size_t mac_length);
1563
1590
1637 psa_algorithm_t alg,
1638 const uint8_t *input,
1639 size_t input_length,
1640 uint8_t *output,
1641 size_t output_size,
1642 size_t *output_length);
1643
1684 psa_algorithm_t alg,
1685 const uint8_t *input,
1686 size_t input_length,
1687 uint8_t *output,
1688 size_t output_size,
1689 size_t *output_length);
1690
1720
1726#ifdef __DOXYGEN_ONLY__
1727/* This is an example definition for documentation purposes.
1728 * Implementations should define a suitable value in `crypto_struct.h`.
1729 */
1730#define PSA_CIPHER_OPERATION_INIT {0}
1731#endif
1732
1736
1798 psa_algorithm_t alg);
1799
1861 psa_algorithm_t alg);
1862
1898 uint8_t *iv,
1899 size_t iv_size,
1900 size_t *iv_length);
1901
1939 const uint8_t *iv,
1940 size_t iv_length);
1941
1980 const uint8_t *input,
1981 size_t input_length,
1982 uint8_t *output,
1983 size_t output_size,
1984 size_t *output_length);
1985
2032 uint8_t *output,
2033 size_t output_size,
2034 size_t *output_length);
2035
2062
2131 psa_algorithm_t alg,
2132 const uint8_t *nonce,
2133 size_t nonce_length,
2134 const uint8_t *additional_data,
2135 size_t additional_data_length,
2136 const uint8_t *plaintext,
2137 size_t plaintext_length,
2138 uint8_t *ciphertext,
2139 size_t ciphertext_size,
2140 size_t *ciphertext_length);
2141
2204 psa_algorithm_t alg,
2205 const uint8_t *nonce,
2206 size_t nonce_length,
2207 const uint8_t *additional_data,
2208 size_t additional_data_length,
2209 const uint8_t *ciphertext,
2210 size_t ciphertext_length,
2211 uint8_t *plaintext,
2212 size_t plaintext_size,
2213 size_t *plaintext_length);
2214
2244
2250#ifdef __DOXYGEN_ONLY__
2251/* This is an example definition for documentation purposes.
2252 * Implementations should define a suitable value in `crypto_struct.h`.
2253 */
2254#define PSA_AEAD_OPERATION_INIT {0}
2255#endif
2256
2260
2330
2396
2433 uint8_t *nonce,
2434 size_t nonce_size,
2435 size_t *nonce_length);
2436
2473 const uint8_t *nonce,
2474 size_t nonce_length);
2475
2518 size_t ad_length,
2519 size_t plaintext_length);
2520
2566 const uint8_t *input,
2567 size_t input_length);
2568
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
2736 uint8_t *ciphertext,
2737 size_t ciphertext_size,
2738 size_t *ciphertext_length,
2739 uint8_t *tag,
2740 size_t tag_size,
2741 size_t *tag_length);
2742
2819 uint8_t *plaintext,
2820 size_t plaintext_size,
2821 size_t *plaintext_length,
2822 const uint8_t *tag,
2823 size_t tag_length);
2824
2851
2918 const uint8_t * input,
2919 size_t input_length,
2920 uint8_t * signature,
2921 size_t signature_size,
2922 size_t * signature_length );
2923
2970 const uint8_t * input,
2971 size_t input_length,
2972 const uint8_t * signature,
2973 size_t signature_length );
2974
3023 const uint8_t *hash,
3024 size_t hash_length,
3025 uint8_t *signature,
3026 size_t signature_size,
3027 size_t *signature_length);
3028
3074 const uint8_t *hash,
3075 size_t hash_length,
3076 const uint8_t *signature,
3077 size_t signature_length);
3078
3132 const uint8_t *input,
3133 size_t input_length,
3134 const uint8_t *salt,
3135 size_t salt_length,
3136 uint8_t *output,
3137 size_t output_size,
3138 size_t *output_length);
3139
3193 const uint8_t *input,
3194 size_t input_length,
3195 const uint8_t *salt,
3196 size_t salt_length,
3197 uint8_t *output,
3198 size_t output_size,
3199 size_t *output_length);
3200
3237
3243#ifdef __DOXYGEN_ONLY__
3244/* This is an example definition for documentation purposes.
3245 * Implementations should define a suitable value in `crypto_struct.h`.
3246 */
3247#define PSA_KEY_DERIVATION_OPERATION_INIT {0}
3248#endif
3249
3253
3315
3336 const psa_key_derivation_operation_t *operation,
3337 size_t *capacity);
3338
3365 size_t capacity);
3366
3374#define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3375
3419 const uint8_t *data,
3420 size_t data_length);
3421
3471
3538 mbedtls_svc_key_id_t private_key,
3539 const uint8_t *peer_key,
3540 size_t peer_key_length);
3541
3581 uint8_t *output,
3582 size_t output_length);
3583
3724 const psa_key_attributes_t *attributes,
3727
3753
3805 mbedtls_svc_key_id_t private_key,
3806 const uint8_t *peer_key,
3807 size_t peer_key_length,
3808 uint8_t *output,
3809 size_t output_size,
3810 size_t *output_length);
3811
3843 size_t output_size);
3844
3891
3894#ifdef __cplusplus
3895}
3896#endif
3897
3898/* The file "crypto_sizes.h" contains definitions for size calculation
3899 * macros whose definitions are implementation-specific. */
3900#include "crypto_sizes.h"
3901
3902/* The file "crypto_struct.h" contains definitions for
3903 * implementation-specific structs that are declared above. */
3904#include "crypto_struct.h"
3905
3906/* The file "crypto_extra.h" contains vendor-specific definitions. This
3907 * can include vendor-defined algorithms, extra functions, etc. */
3908#include "crypto_extra.h"
3909
3910#endif /* PSA_CRYPTO_H */
PSA cryptography module: Mbed TLS vendor extensions.
PSA cryptography module: Mbed TLS platform definitions.
PSA cryptography module: Mbed TLS buffer size macros.
PSA cryptography module: Mbed TLS structured type implementations.
PSA cryptography module: type aliases.
PSA cryptography module: macros to build and analyze integer values.
psa_status_t psa_mac_sign_setup(psa_mac_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
psa_status_t psa_mac_verify_setup(psa_mac_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
static psa_mac_operation_t psa_mac_operation_init(void)
psa_status_t psa_mac_update(psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_mac_compute(mbedtls_svc_key_id_t key, 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_mac_sign_finish(psa_mac_operation_t *operation, uint8_t *mac, size_t mac_size, size_t *mac_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_mac_abort(psa_mac_operation_t *operation)
psa_status_t psa_mac_verify(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *mac, size_t mac_length)
psa_status_t psa_aead_encrypt_setup(psa_aead_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
static psa_aead_operation_t psa_aead_operation_init(void)
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_aead_set_nonce(psa_aead_operation_t *operation, const uint8_t *nonce, size_t nonce_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_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_aead_decrypt_setup(psa_aead_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
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_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_aead_encrypt(mbedtls_svc_key_id_t key, 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_aead_decrypt(mbedtls_svc_key_id_t key, 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_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)
psa_status_t psa_verify_message(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *signature, size_t signature_length)
Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.
psa_status_t psa_asymmetric_decrypt(mbedtls_svc_key_id_t key, 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_status_t psa_sign_hash(mbedtls_svc_key_id_t key, 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_sign_message(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *input, size_t input_length, uint8_t *signature, size_t signature_size, size_t *signature_length)
Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.
psa_status_t psa_asymmetric_encrypt(mbedtls_svc_key_id_t key, 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_verify_hash(mbedtls_svc_key_id_t key, psa_algorithm_t alg, const uint8_t *hash, size_t hash_length, const uint8_t *signature, size_t signature_length)
Verify the signature of a hash or short message using a public key.
static psa_key_attributes_t psa_key_attributes_init(void)
void psa_reset_key_attributes(psa_key_attributes_t *attributes)
static void psa_set_key_usage_flags(psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
static size_t psa_get_key_bits(const psa_key_attributes_t *attributes)
static void psa_set_key_type(psa_key_attributes_t *attributes, psa_key_type_t type)
static psa_key_lifetime_t psa_get_key_lifetime(const psa_key_attributes_t *attributes)
static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes)
static void psa_set_key_lifetime(psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
static psa_algorithm_t psa_get_key_algorithm(const psa_key_attributes_t *attributes)
psa_status_t psa_get_key_attributes(mbedtls_svc_key_id_t key, psa_key_attributes_t *attributes)
static void psa_set_key_id(psa_key_attributes_t *attributes, mbedtls_svc_key_id_t key)
static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes)
static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg)
static void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits)
static mbedtls_svc_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes)
static psa_cipher_operation_t psa_cipher_operation_init(void)
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_cipher_generate_iv(psa_cipher_operation_t *operation, uint8_t *iv, size_t iv_size, size_t *iv_length)
psa_status_t psa_cipher_encrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
psa_status_t psa_cipher_encrypt(mbedtls_svc_key_id_t key, 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_cipher_set_iv(psa_cipher_operation_t *operation, const uint8_t *iv, size_t iv_length)
psa_status_t psa_cipher_decrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation)
psa_status_t psa_cipher_decrypt(mbedtls_svc_key_id_t key, 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_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)
uint16_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:81
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:137
uint16_t psa_key_derivation_step_t
Encoding of the step of a key derivation.
Definition: crypto_types.h:460
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:62
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_hash_clone(const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
static psa_hash_operation_t psa_hash_operation_init(void)
psa_status_t psa_hash_update(psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_hash_verify(psa_hash_operation_t *operation, const uint8_t *hash, size_t hash_length)
psa_status_t psa_hash_setup(psa_hash_operation_t *operation, psa_algorithm_t alg)
psa_status_t psa_hash_abort(psa_hash_operation_t *operation)
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_import_key(const psa_key_attributes_t *attributes, const uint8_t *data, size_t data_length, mbedtls_svc_key_id_t *key)
Import a key in binary format.
psa_status_t psa_export_key(mbedtls_svc_key_id_t key, uint8_t *data, size_t data_size, size_t *data_length)
Export a key in binary format.
psa_status_t psa_export_public_key(mbedtls_svc_key_id_t key, 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_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)
psa_status_t psa_raw_key_agreement(psa_algorithm_t alg, mbedtls_svc_key_id_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_key_derivation_key_agreement(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, mbedtls_svc_key_id_t private_key, const uint8_t *peer_key, size_t peer_key_length)
psa_status_t psa_key_derivation_set_capacity(psa_key_derivation_operation_t *operation, size_t capacity)
static psa_key_derivation_operation_t psa_key_derivation_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_key_derivation_abort(psa_key_derivation_operation_t *operation)
psa_status_t psa_key_derivation_get_capacity(const psa_key_derivation_operation_t *operation, size_t *capacity)
psa_status_t psa_key_derivation_input_key(psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, mbedtls_svc_key_id_t key)
psa_status_t psa_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg)
psa_status_t psa_key_derivation_output_key(const psa_key_attributes_t *attributes, psa_key_derivation_operation_t *operation, mbedtls_svc_key_id_t *key)
uint32_t psa_key_lifetime_t
Definition: crypto_types.h:186
psa_key_id_t mbedtls_svc_key_id_t
Definition: crypto_types.h:295
psa_status_t psa_purge_key(mbedtls_svc_key_id_t key)
psa_status_t psa_destroy_key(mbedtls_svc_key_id_t key)
Destroy a key.
psa_status_t psa_copy_key(mbedtls_svc_key_id_t source_key, const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *target_key)
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: crypto_types.h:327
psa_status_t psa_generate_random(uint8_t *output, size_t output_size)
Generate random bytes.
psa_status_t psa_generate_key(const psa_key_attributes_t *attributes, mbedtls_svc_key_id_t *key)
Generate a key or key pair.
psa_algorithm_t alg
psa_algorithm_t alg