mbed TLS v2.26.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 
40 #endif /* __DOXYGEN_ONLY__ */
41 
42 #ifdef __cplusplus
43 extern "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 
146 static void psa_set_key_id( psa_key_attributes_t *attributes,
147  mbedtls_svc_key_id_t key );
148 
149 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
150 
164 static void mbedtls_set_key_owner_id( psa_key_attributes_t *attributes,
165  mbedtls_key_owner_id_t owner_id );
166 #endif
167 
193 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
194  psa_key_lifetime_t lifetime);
195 
209  const psa_key_attributes_t *attributes);
210 
222  const psa_key_attributes_t *attributes);
223 
240 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
241  psa_key_usage_t usage_flags);
242 
254  const psa_key_attributes_t *attributes);
255 
286 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
287  psa_algorithm_t alg);
288 
289 
301  const psa_key_attributes_t *attributes);
302 
317 static void psa_set_key_type(psa_key_attributes_t *attributes,
318  psa_key_type_t type);
319 
320 
335 static void psa_set_key_bits(psa_key_attributes_t *attributes,
336  size_t bits);
337 
348 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
349 
360 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
361 
391  psa_key_attributes_t *attributes);
392 
406 
435 
528  const psa_key_attributes_t *attributes,
529  mbedtls_svc_key_id_t *target_key);
530 
531 
578 
659  const uint8_t *data,
660  size_t data_length,
661  mbedtls_svc_key_id_t *key);
662 
663 
664 
752  uint8_t *data,
753  size_t data_size,
754  size_t *data_length);
755 
822  uint8_t *data,
823  size_t data_size,
824  size_t *data_length);
825 
826 
827 
867  const uint8_t *input,
868  size_t input_length,
869  uint8_t *hash,
870  size_t hash_size,
871  size_t *hash_length);
872 
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 
1005 
1031  const uint8_t *input,
1032  size_t input_length);
1033 
1078  uint8_t *hash,
1079  size_t hash_size,
1080  size_t *hash_length);
1081 
1120  const uint8_t *hash,
1121  size_t hash_length);
1122 
1149 
1179 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1180  psa_hash_operation_t *target_operation);
1181 
1232  const uint8_t *input,
1233  size_t input_length,
1234  uint8_t *mac,
1235  size_t mac_size,
1236  size_t *mac_length);
1237 
1273  const uint8_t *input,
1274  size_t input_length,
1275  const uint8_t *mac,
1276  size_t mac_length);
1277 
1307 
1313 #ifdef __DOXYGEN_ONLY__
1314 /* This is an example definition for documentation purposes.
1315  * Implementations should define a suitable value in `crypto_struct.h`.
1316  */
1317 #define PSA_MAC_OPERATION_INIT {0}
1318 #endif
1319 
1323 
1386 
1449 
1478  const uint8_t *input,
1479  size_t input_length);
1480 
1528  uint8_t *mac,
1529  size_t mac_size,
1530  size_t *mac_length);
1531 
1572  const uint8_t *mac,
1573  size_t mac_length);
1574 
1601 
1649  const uint8_t *input,
1650  size_t input_length,
1651  uint8_t *output,
1652  size_t output_size,
1653  size_t *output_length);
1654 
1696  const uint8_t *input,
1697  size_t input_length,
1698  uint8_t *output,
1699  size_t output_size,
1700  size_t *output_length);
1701 
1731 
1737 #ifdef __DOXYGEN_ONLY__
1738 /* This is an example definition for documentation purposes.
1739  * Implementations should define a suitable value in `crypto_struct.h`.
1740  */
1741 #define PSA_CIPHER_OPERATION_INIT {0}
1742 #endif
1743 
1747 
1811 
1875 
1911  uint8_t *iv,
1912  size_t iv_size,
1913  size_t *iv_length);
1914 
1953  const uint8_t *iv,
1954  size_t iv_length);
1955 
1995  const uint8_t *input,
1996  size_t input_length,
1997  uint8_t *output,
1998  size_t output_size,
1999  size_t *output_length);
2000 
2048  uint8_t *output,
2049  size_t output_size,
2050  size_t *output_length);
2051 
2078 
2137  const uint8_t *nonce,
2138  size_t nonce_length,
2139  const uint8_t *additional_data,
2140  size_t additional_data_length,
2141  const uint8_t *plaintext,
2142  size_t plaintext_length,
2143  uint8_t *ciphertext,
2144  size_t ciphertext_size,
2145  size_t *ciphertext_length);
2146 
2199  const uint8_t *nonce,
2200  size_t nonce_length,
2201  const uint8_t *additional_data,
2202  size_t additional_data_length,
2203  const uint8_t *ciphertext,
2204  size_t ciphertext_length,
2205  uint8_t *plaintext,
2206  size_t plaintext_size,
2207  size_t *plaintext_length);
2208 
2238 
2244 #ifdef __DOXYGEN_ONLY__
2245 /* This is an example definition for documentation purposes.
2246  * Implementations should define a suitable value in `crypto_struct.h`.
2247  */
2248 #define PSA_AEAD_OPERATION_INIT {0}
2249 #endif
2250 
2254 
2324 
2391 
2429  uint8_t *nonce,
2430  size_t nonce_size,
2431  size_t *nonce_length);
2432 
2470  const uint8_t *nonce,
2471  size_t nonce_length);
2472 
2516  size_t ad_length,
2517  size_t plaintext_length);
2518 
2565  const uint8_t *input,
2566  size_t input_length);
2567 
2643  const uint8_t *input,
2644  size_t input_length,
2645  uint8_t *output,
2646  size_t output_size,
2647  size_t *output_length);
2648 
2719  uint8_t *ciphertext,
2720  size_t ciphertext_size,
2721  size_t *ciphertext_length,
2722  uint8_t *tag,
2723  size_t tag_size,
2724  size_t *tag_length);
2725 
2799  uint8_t *plaintext,
2800  size_t plaintext_size,
2801  size_t *plaintext_length,
2802  const uint8_t *tag,
2803  size_t tag_length);
2804 
2831 
2883  const uint8_t *hash,
2884  size_t hash_length,
2885  uint8_t *signature,
2886  size_t signature_size,
2887  size_t *signature_length);
2888 
2931  const uint8_t *hash,
2932  size_t hash_length,
2933  const uint8_t *signature,
2934  size_t signature_length);
2935 
2989  const uint8_t *input,
2990  size_t input_length,
2991  const uint8_t *salt,
2992  size_t salt_length,
2993  uint8_t *output,
2994  size_t output_size,
2995  size_t *output_length);
2996 
3050  const uint8_t *input,
3051  size_t input_length,
3052  const uint8_t *salt,
3053  size_t salt_length,
3054  uint8_t *output,
3055  size_t output_size,
3056  size_t *output_length);
3057 
3094 
3100 #ifdef __DOXYGEN_ONLY__
3101 /* This is an example definition for documentation purposes.
3102  * Implementations should define a suitable value in `crypto_struct.h`.
3103  */
3104 #define PSA_KEY_DERIVATION_OPERATION_INIT {0}
3105 #endif
3106 
3110 
3171  psa_key_derivation_operation_t *operation,
3173 
3195  const psa_key_derivation_operation_t *operation,
3196  size_t *capacity);
3197 
3224  psa_key_derivation_operation_t *operation,
3225  size_t capacity);
3226 
3234 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t)(-1))
3235 
3279  psa_key_derivation_operation_t *operation,
3281  const uint8_t *data,
3282  size_t data_length);
3283 
3332  psa_key_derivation_operation_t *operation,
3334  mbedtls_svc_key_id_t key);
3335 
3402  psa_key_derivation_operation_t *operation,
3404  mbedtls_svc_key_id_t private_key,
3405  const uint8_t *peer_key,
3406  size_t peer_key_length);
3407 
3447  psa_key_derivation_operation_t *operation,
3448  uint8_t *output,
3449  size_t output_length);
3450 
3590  const psa_key_attributes_t *attributes,
3591  psa_key_derivation_operation_t *operation,
3592  mbedtls_svc_key_id_t *key);
3593 
3618  psa_key_derivation_operation_t *operation);
3619 
3672  mbedtls_svc_key_id_t private_key,
3673  const uint8_t *peer_key,
3674  size_t peer_key_length,
3675  uint8_t *output,
3676  size_t output_size,
3677  size_t *output_length);
3678 
3709 psa_status_t psa_generate_random(uint8_t *output,
3710  size_t output_size);
3711 
3757  mbedtls_svc_key_id_t *key);
3758 
3761 #ifdef __cplusplus
3762 }
3763 #endif
3764 
3765 /* The file "crypto_sizes.h" contains definitions for size calculation
3766  * macros whose definitions are implementation-specific. */
3767 #include "crypto_sizes.h"
3768 
3769 /* The file "crypto_struct.h" contains definitions for
3770  * implementation-specific structs that are declared above. */
3771 #include "crypto_struct.h"
3772 
3773 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3774  * can include vendor-defined algorithms, extra functions, etc. */
3775 #include "crypto_extra.h"
3776 
3777 #endif /* PSA_CRYPTO_H */
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_aead_encrypt_setup(psa_aead_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
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_generate_random(uint8_t *output, size_t output_size)
Generate random bytes.
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_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.
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_cipher_decrypt_setup(psa_cipher_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
psa_algorithm_t alg
psa_status_t psa_key_derivation_abort(psa_key_derivation_operation_t *operation)
psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
static void psa_set_key_bits(psa_key_attributes_t *attributes, size_t bits)
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_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 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:379
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 cryptography module: Mbed TLS structured type implementations.
PSA cryptography module: Mbed TLS vendor extensions.
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_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_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_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)
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)
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 void psa_set_key_id(psa_key_attributes_t *attributes, mbedtls_svc_key_id_t key)
static size_t psa_get_key_bits(const psa_key_attributes_t *attributes)
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 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_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_mac_sign_setup(psa_mac_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
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 a hash or short message using a public 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_hash_clone(const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
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_status_t psa_purge_key(mbedtls_svc_key_id_t 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)
psa_status_t psa_get_key_attributes(mbedtls_svc_key_id_t key, psa_key_attributes_t *attributes)
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)
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:105
psa_algorithm_t alg
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_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)
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_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:250
static void psa_set_key_algorithm(psa_key_attributes_t *attributes, psa_algorithm_t alg)
uint16_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:73
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 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)
static psa_key_usage_t psa_get_key_usage_flags(const psa_key_attributes_t *attributes)
psa_key_id_t mbedtls_svc_key_id_t
Definition: crypto_types.h:227
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_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_hash_abort(psa_hash_operation_t *operation)
static psa_key_attributes_t psa_key_attributes_init(void)
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_destroy_key(mbedtls_svc_key_id_t key)
Destroy a key.
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_key_derivation_setup(psa_key_derivation_operation_t *operation, psa_algorithm_t alg)
static mbedtls_svc_key_id_t psa_get_key_id(const psa_key_attributes_t *attributes)
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_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)
uint32_t psa_key_lifetime_t
Definition: crypto_types.h:146
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)
static psa_mac_operation_t psa_mac_operation_init(void)
psa_algorithm_t alg
Definition: crypto_struct.h:92
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)
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:62
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_mac_verify_setup(psa_mac_operation_t *operation, mbedtls_svc_key_id_t key, psa_algorithm_t alg)
psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)