Platform Security Architecture — cryptography and keystore interface  beta 1 — 2019-01-21
crypto.h
Go to the documentation of this file.
1 
5 /*
6  * Copyright (C) 2018, ARM Limited, All Rights Reserved
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 
60 /* The file "crypto_values.h" declares macros to build and analyze values
61  * of integral types defined in "crypto_types.h". */
62 #include "crypto_values.h"
63 
93 
128 typedef struct psa_key_policy_s psa_key_policy_t;
129 
135 #ifdef __DOXYGEN_ONLY__
136 /* This is an example definition for documentation purposes.
137  * Implementations should define a suitable value in `crypto_struct.h`.
138  */
139 #define PSA_KEY_POLICY_INIT {0}
140 #endif
141 
144 static psa_key_policy_t psa_key_policy_init(void);
145 
159  psa_key_usage_t usage,
160  psa_algorithm_t alg);
161 
169 
177 
208  const psa_key_policy_t *policy);
209 
226  psa_key_policy_t *policy);
227 
251  psa_key_lifetime_t *lifetime);
252 
253 
271 
302  psa_key_id_t id,
303  psa_key_handle_t *handle);
304 
339  psa_key_id_t id,
340  psa_key_handle_t *handle);
341 
361 
421  psa_key_type_t type,
422  const uint8_t *data,
423  size_t data_length);
424 
465 
490  psa_key_type_t *type,
491  size_t *bits);
492 
557  psa_key_type_t type,
558  const uint8_t *data,
559  size_t data_length);
560 
589  uint8_t *data,
590  size_t data_size,
591  size_t *data_length);
592 
676  uint8_t *data,
677  size_t data_size,
678  size_t *data_length);
679 
745  uint8_t *data,
746  size_t data_size,
747  size_t *data_length);
748 
811  psa_key_handle_t target_handle,
812  const psa_key_policy_t *constraint);
813 
846  const uint8_t *input,
847  size_t input_length,
848  uint8_t *hash,
849  size_t hash_size,
850  size_t *hash_length);
851 
875  const uint8_t *input,
876  size_t input_length,
877  const uint8_t *hash,
878  const size_t hash_length);
879 
908 typedef struct psa_hash_operation_s psa_hash_operation_t;
909 
915 #ifdef __DOXYGEN_ONLY__
916 /* This is an example definition for documentation purposes.
917  * Implementations should define a suitable value in `crypto_struct.h`.
918  */
919 #define PSA_HASH_OPERATION_INIT {0}
920 #endif
921 
924 static psa_hash_operation_t psa_hash_operation_init(void);
925 
966  psa_algorithm_t alg);
967 
988  const uint8_t *input,
989  size_t input_length);
990 
1029  uint8_t *hash,
1030  size_t hash_size,
1031  size_t *hash_length);
1032 
1065  const uint8_t *hash,
1066  size_t hash_length);
1067 
1096 
1121 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1122  psa_hash_operation_t *target_operation);
1123 
1171  psa_algorithm_t alg,
1172  const uint8_t *input,
1173  size_t input_length,
1174  uint8_t *mac,
1175  size_t mac_size,
1176  size_t *mac_length);
1177 
1206  psa_algorithm_t alg,
1207  const uint8_t *input,
1208  size_t input_length,
1209  const uint8_t *mac,
1210  const size_t mac_length);
1211 
1240 typedef struct psa_mac_operation_s psa_mac_operation_t;
1241 
1247 #ifdef __DOXYGEN_ONLY__
1248 /* This is an example definition for documentation purposes.
1249  * Implementations should define a suitable value in `crypto_struct.h`.
1250  */
1251 #define PSA_MAC_OPERATION_INIT {0}
1252 #endif
1253 
1256 static psa_mac_operation_t psa_mac_operation_init(void);
1257 
1313  psa_key_handle_t handle,
1314  psa_algorithm_t alg);
1315 
1370  psa_key_handle_t handle,
1371  psa_algorithm_t alg);
1372 
1395  const uint8_t *input,
1396  size_t input_length);
1397 
1437  uint8_t *mac,
1438  size_t mac_size,
1439  size_t *mac_length);
1440 
1473  const uint8_t *mac,
1474  size_t mac_length);
1475 
1505 
1548  psa_algorithm_t alg,
1549  const uint8_t *input,
1550  size_t input_length,
1551  uint8_t *output,
1552  size_t output_size,
1553  size_t *output_length);
1554 
1590  psa_algorithm_t alg,
1591  const uint8_t *input,
1592  size_t input_length,
1593  uint8_t *output,
1594  size_t output_size,
1595  size_t *output_length);
1596 
1625 typedef struct psa_cipher_operation_s psa_cipher_operation_t;
1626 
1632 #ifdef __DOXYGEN_ONLY__
1633 /* This is an example definition for documentation purposes.
1634  * Implementations should define a suitable value in `crypto_struct.h`.
1635  */
1636 #define PSA_CIPHER_OPERATION_INIT {0}
1637 #endif
1638 
1641 static psa_cipher_operation_t psa_cipher_operation_init(void);
1642 
1699  psa_key_handle_t handle,
1700  psa_algorithm_t alg);
1701 
1758  psa_key_handle_t handle,
1759  psa_algorithm_t alg);
1760 
1790  unsigned char *iv,
1791  size_t iv_size,
1792  size_t *iv_length);
1793 
1825  const unsigned char *iv,
1826  size_t iv_length);
1827 
1861  const uint8_t *input,
1862  size_t input_length,
1863  unsigned char *output,
1864  size_t output_size,
1865  size_t *output_length);
1866 
1899  uint8_t *output,
1900  size_t output_size,
1901  size_t *output_length);
1902 
1932 
1986  psa_algorithm_t alg,
1987  const uint8_t *nonce,
1988  size_t nonce_length,
1989  const uint8_t *additional_data,
1990  size_t additional_data_length,
1991  const uint8_t *plaintext,
1992  size_t plaintext_length,
1993  uint8_t *ciphertext,
1994  size_t ciphertext_size,
1995  size_t *ciphertext_length);
1996 
2044  psa_algorithm_t alg,
2045  const uint8_t *nonce,
2046  size_t nonce_length,
2047  const uint8_t *additional_data,
2048  size_t additional_data_length,
2049  const uint8_t *ciphertext,
2050  size_t ciphertext_length,
2051  uint8_t *plaintext,
2052  size_t plaintext_size,
2053  size_t *plaintext_length);
2054 
2083 typedef struct psa_aead_operation_s psa_aead_operation_t;
2084 
2090 #ifdef __DOXYGEN_ONLY__
2091 /* This is an example definition for documentation purposes.
2092  * Implementations should define a suitable value in `crypto_struct.h`.
2093  */
2094 #define PSA_AEAD_OPERATION_INIT {0}
2095 #endif
2096 
2099 static psa_aead_operation_t psa_aead_operation_init(void);
2100 
2163  psa_key_handle_t handle,
2164  psa_algorithm_t alg);
2165 
2225  psa_key_handle_t handle,
2226  psa_algorithm_t alg);
2227 
2258  unsigned char *nonce,
2259  size_t nonce_size,
2260  size_t *nonce_length);
2261 
2292  const unsigned char *nonce,
2293  size_t nonce_length);
2294 
2330  size_t ad_length,
2331  size_t plaintext_length);
2332 
2372  const uint8_t *input,
2373  size_t input_length);
2374 
2429  const uint8_t *input,
2430  size_t input_length,
2431  unsigned char *output,
2432  size_t output_size,
2433  size_t *output_length);
2434 
2488  uint8_t *ciphertext,
2489  size_t ciphertext_size,
2490  size_t *ciphertext_length,
2491  uint8_t *tag,
2492  size_t tag_size,
2493  size_t *tag_length);
2494 
2531  const uint8_t *tag,
2532  size_t tag_length);
2533 
2563 
2610  psa_algorithm_t alg,
2611  const uint8_t *hash,
2612  size_t hash_length,
2613  uint8_t *signature,
2614  size_t signature_size,
2615  size_t *signature_length);
2616 
2653  psa_algorithm_t alg,
2654  const uint8_t *hash,
2655  size_t hash_length,
2656  const uint8_t *signature,
2657  size_t signature_length);
2658 
2707  psa_algorithm_t alg,
2708  const uint8_t *input,
2709  size_t input_length,
2710  const uint8_t *salt,
2711  size_t salt_length,
2712  uint8_t *output,
2713  size_t output_size,
2714  size_t *output_length);
2715 
2764  psa_algorithm_t alg,
2765  const uint8_t *input,
2766  size_t input_length,
2767  const uint8_t *salt,
2768  size_t salt_length,
2769  uint8_t *output,
2770  size_t output_size,
2771  size_t *output_length);
2772 
2808 typedef struct psa_crypto_generator_s psa_crypto_generator_t;
2809 
2815 #ifdef __DOXYGEN_ONLY__
2816 /* This is an example definition for documentation purposes.
2817  * Implementations should define a suitable value in `crypto_struct.h`.
2818  */
2819 #define PSA_CRYPTO_GENERATOR_INIT {0}
2820 #endif
2821 
2824 static psa_crypto_generator_t psa_crypto_generator_init(void);
2825 
2839  size_t *capacity);
2840 
2855  size_t capacity);
2856 
2883  uint8_t *output,
2884  size_t output_length);
2885 
2936  psa_key_type_t type,
2937  size_t bits,
2938  psa_crypto_generator_t *generator);
2939 
2963 
2971 #define PSA_GENERATOR_UNBRIDLED_CAPACITY ((size_t)(-1))
2972 
3020  psa_algorithm_t alg);
3021 
3059  const uint8_t *data,
3060  size_t data_length);
3061 
3104  psa_key_handle_t handle);
3105 
3161  psa_key_handle_t private_key,
3162  const uint8_t *peer_key,
3163  size_t peer_key_length);
3164 
3210  psa_key_handle_t private_key,
3211  const uint8_t *peer_key,
3212  size_t peer_key_length,
3213  uint8_t *output,
3214  size_t output_size,
3215  size_t *output_length);
3216 
3246 psa_status_t psa_generate_random(uint8_t *output,
3247  size_t output_size);
3248 
3254 typedef struct {
3255  uint32_t e;
3257 
3324  psa_key_type_t type,
3325  size_t bits,
3326  const void *extra,
3327  size_t extra_size);
3328 
3331 #ifdef __cplusplus
3332 }
3333 #endif
3334 
3335 /* The file "crypto_sizes.h" contains definitions for size calculation
3336  * macros whose definitions are implementation-specific. */
3337 #include "crypto_sizes.h"
3338 
3339 /* The file "crypto_struct.h" contains definitions for
3340  * implementation-specific structs that are declared above. */
3341 #include "crypto_struct.h"
3342 
3343 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3344  * can include vendor-defined algorithms, extra functions, etc. */
3345 #include "crypto_extra.h"
3346 
3347 #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)
psa_status_t psa_mac_verify_finish(psa_mac_operation_t *operation, const uint8_t *mac, size_t mac_length)
psa_status_t psa_generate_random(uint8_t *output, size_t output_size)
Generate random bytes.
psa_status_t psa_aead_generate_nonce(psa_aead_operation_t *operation, unsigned char *nonce, size_t nonce_size, size_t *nonce_length)
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_allocate_key(psa_key_handle_t *handle)
psa_status_t psa_asymmetric_verify(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_cipher_decrypt_setup(psa_cipher_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
psa_key_usage_t psa_key_policy_get_usage(const psa_key_policy_t *policy)
Retrieve the usage field of a policy structure.
psa_status_t psa_key_agreement_raw_shared_secret(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_aead_encrypt_setup(psa_aead_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
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, const size_t mac_length)
psa_status_t psa_generate_key(psa_key_handle_t handle, psa_key_type_t type, size_t bits, const void *extra, size_t extra_size)
Generate a key or key pair.
psa_status_t psa_close_key(psa_key_handle_t handle)
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_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.
struct psa_aead_operation_s psa_aead_operation_t
Definition: crypto.h:2083
psa_status_t psa_key_derivation_input_bytes(psa_crypto_generator_t *generator, psa_key_derivation_step_t step, const uint8_t *data, size_t data_length)
psa_status_t psa_get_key_domain_parameters(psa_key_handle_t handle, uint8_t *data, size_t data_size, size_t *data_length)
Get domain parameters for a key.
PSA cryptography module: type aliases.
psa_status_t psa_copy_key(psa_key_handle_t source_handle, psa_key_handle_t target_handle, const psa_key_policy_t *constraint)
psa_status_t psa_generator_abort(psa_crypto_generator_t *generator)
uint16_t psa_key_derivation_step_t
Encoding of the step of a key derivation.
Definition: crypto_types.h:106
uint32_t psa_key_id_t
Definition: crypto_types.h:88
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_cipher_update(psa_cipher_operation_t *operation, const uint8_t *input, size_t input_length, unsigned char *output, size_t output_size, size_t *output_length)
psa_status_t psa_cipher_set_iv(psa_cipher_operation_t *operation, const unsigned char *iv, size_t iv_length)
psa_status_t psa_generator_read(psa_crypto_generator_t *generator, uint8_t *output, size_t output_length)
psa_status_t psa_hash_update(psa_hash_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_hash_compare(psa_algorithm_t alg, const uint8_t *input, size_t input_length, const uint8_t *hash, const size_t hash_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_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_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_set_key_domain_parameters(psa_key_handle_t handle, psa_key_type_t type, const uint8_t *data, size_t data_length)
Set domain parameters for a key.
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_cipher_finish(psa_cipher_operation_t *operation, uint8_t *output, size_t output_size, size_t *output_length)
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_cipher_generate_iv(psa_cipher_operation_t *operation, unsigned char *iv, size_t iv_size, size_t *iv_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_key_derivation_input_key(psa_crypto_generator_t *generator, psa_key_derivation_step_t step, psa_key_handle_t handle)
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_generator_import_key(psa_key_handle_t handle, psa_key_type_t type, size_t bits, psa_crypto_generator_t *generator)
psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation, psa_hash_operation_t *target_operation)
psa_status_t psa_get_key_policy(psa_key_handle_t handle, psa_key_policy_t *policy)
Get the usage policy for a key slot.
uint32_t e
Definition: crypto.h:3255
uint32_t psa_algorithm_t
Encoding of a cryptographic algorithm.
Definition: crypto_types.h:74
struct psa_hash_operation_s psa_hash_operation_t
Definition: crypto.h:908
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_mac_abort(psa_mac_operation_t *operation)
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)
uint32_t psa_key_usage_t
Encoding of permitted usage on a key.
Definition: crypto_types.h:97
struct psa_key_policy_s psa_key_policy_t
Definition: crypto.h:128
psa_status_t psa_destroy_key(psa_key_handle_t handle)
Destroy a key.
void psa_key_policy_set_usage(psa_key_policy_t *policy, psa_key_usage_t usage, psa_algorithm_t alg)
Set the standard fields of a policy structure.
psa_status_t psa_crypto_init(void)
Library initialization.
_unsigned_integral_type_ psa_key_handle_t
Key handle.
Definition: crypto.h:47
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 cryptography module: Mbed TLS buffer size macros.
psa_status_t psa_key_agreement(psa_crypto_generator_t *generator, psa_key_derivation_step_t step, psa_key_handle_t private_key, const uint8_t *peer_key, size_t peer_key_length)
psa_status_t psa_open_key(psa_key_lifetime_t lifetime, psa_key_id_t id, psa_key_handle_t *handle)
psa_status_t psa_mac_update(psa_mac_operation_t *operation, const uint8_t *input, size_t input_length)
psa_status_t psa_aead_set_nonce(psa_aead_operation_t *operation, const unsigned char *nonce, size_t nonce_length)
psa_status_t psa_hash_abort(psa_hash_operation_t *operation)
psa_status_t psa_get_key_lifetime(psa_key_handle_t handle, psa_key_lifetime_t *lifetime)
Retrieve the lifetime of an open key.
psa_status_t psa_aead_update(psa_aead_operation_t *operation, const uint8_t *input, size_t input_length, unsigned char *output, size_t output_size, size_t *output_length)
struct psa_cipher_operation_s psa_cipher_operation_t
Definition: crypto.h:1625
uint32_t psa_key_type_t
Encoding of a key type.
Definition: crypto_types.h:61
psa_status_t psa_aead_verify(psa_aead_operation_t *operation, const uint8_t *tag, size_t tag_length)
struct psa_mac_operation_s psa_mac_operation_t
Definition: crypto.h:1240
psa_status_t psa_aead_abort(psa_aead_operation_t *operation)
psa_algorithm_t psa_key_policy_get_algorithm(const psa_key_policy_t *policy)
Retrieve the algorithm field of a policy structure.
uint32_t psa_key_lifetime_t
Definition: crypto_types.h:84
psa_status_t psa_get_generator_capacity(const psa_crypto_generator_t *generator, size_t *capacity)
psa_status_t psa_set_key_policy(psa_key_handle_t handle, const psa_key_policy_t *policy)
Set the usage policy on a key slot.
psa_status_t psa_create_key(psa_key_lifetime_t lifetime, psa_key_id_t id, psa_key_handle_t *handle)
psa_status_t psa_import_key(psa_key_handle_t handle, psa_key_type_t type, const uint8_t *data, size_t data_length)
Import a key in binary format.
int32_t psa_status_t
Function return status.
Definition: crypto_types.h:51
psa_status_t psa_cipher_abort(psa_cipher_operation_t *operation)
psa_status_t psa_set_generator_capacity(psa_crypto_generator_t *generator, size_t capacity)
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_mac_sign_setup(psa_mac_operation_t *operation, psa_key_handle_t handle, psa_algorithm_t alg)
psa_status_t psa_key_derivation_setup(psa_crypto_generator_t *generator, psa_algorithm_t alg)
psa_status_t psa_get_key_information(psa_key_handle_t handle, psa_key_type_t *type, size_t *bits)
Get basic metadata about a key.
psa_status_t psa_asymmetric_sign(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.
struct psa_crypto_generator_s psa_crypto_generator_t
Definition: crypto.h:2808
psa_status_t psa_hash_finish(psa_hash_operation_t *operation, uint8_t *hash, size_t hash_size, size_t *hash_length)
Definition: crypto.h:3254