Mbed TLS v2.28.9
crypto.h
Go to the documentation of this file.
1 
5 /*
6  * Copyright The Mbed TLS Contributors
7  * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
8  */
9 
10 #ifndef PSA_CRYPTO_H
11 #define PSA_CRYPTO_H
12 
13 #include "crypto_platform.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 
28 #endif /* __DOXYGEN_ONLY__ */
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /* The file "crypto_types.h" declares types that encode errors,
35  * algorithms, key types, policies, etc. */
36 #include "crypto_types.h"
37 
45 #define PSA_CRYPTO_API_VERSION_MAJOR 1
46 
50 #define PSA_CRYPTO_API_VERSION_MINOR 0
51 
54 /* The file "crypto_values.h" declares macros to build and analyze values
55  * of integral types defined in "crypto_types.h". */
56 #include "crypto_values.h"
57 
91 
103 #ifdef __DOXYGEN_ONLY__
104 /* This is an example definition for documentation purposes.
105  * Implementations should define a suitable value in `crypto_struct.h`.
106  */
107 #define PSA_KEY_ATTRIBUTES_INIT { 0 }
108 #endif
109 
113 
137 static void psa_set_key_id(psa_key_attributes_t *attributes,
139 
140 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
141 
155 static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes,
156  mbedtls_key_owner_id_t owner);
157 #endif
158 
184 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
185  psa_key_lifetime_t lifetime);
186 
200  const psa_key_attributes_t *attributes);
201 
213  const psa_key_attributes_t *attributes);
214 
231 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
232  psa_key_usage_t usage_flags);
233 
245  const psa_key_attributes_t *attributes);
246 
277 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
278  psa_algorithm_t alg);
279 
280 
292  const psa_key_attributes_t *attributes);
293 
308 static void psa_set_key_type(psa_key_attributes_t *attributes,
309  psa_key_type_t type);
310 
311 
326 static void psa_set_key_bits(psa_key_attributes_t *attributes,
327  size_t bits);
328 
339 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
340 
351 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
352 
382  psa_key_attributes_t *attributes);
383 
397 
426 
516  const psa_key_attributes_t *attributes,
517  mbedtls_svc_key_id_t *target_key);
518 
519 
566 
645  const uint8_t *data,
646  size_t data_length,
647  mbedtls_svc_key_id_t *key);
648 
649 
650 
740  uint8_t *data,
741  size_t data_size,
742  size_t *data_length);
743 
815  uint8_t *data,
816  size_t data_size,
817  size_t *data_length);
818 
819 
820 
859  const uint8_t *input,
860  size_t input_length,
861  uint8_t *hash,
862  size_t hash_size,
863  size_t *hash_length);
864 
894  const uint8_t *input,
895  size_t input_length,
896  const uint8_t *hash,
897  size_t hash_length);
898 
928 
934 #ifdef __DOXYGEN_ONLY__
935 /* This is an example definition for documentation purposes.
936  * Implementations should define a suitable value in `crypto_struct.h`.
937  */
938 #define PSA_HASH_OPERATION_INIT { 0 }
939 #endif
940 
944 
994  psa_algorithm_t alg);
995 
1020  const uint8_t *input,
1021  size_t input_length);
1022 
1066  uint8_t *hash,
1067  size_t hash_size,
1068  size_t *hash_length);
1069 
1107  const uint8_t *hash,
1108  size_t hash_length);
1109 
1136 
1164 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1165  psa_hash_operation_t *target_operation);
1166 
1216  psa_algorithm_t alg,
1217  const uint8_t *input,
1218  size_t input_length,
1219  uint8_t *mac,
1220  size_t mac_size,
1221  size_t *mac_length);
1222 
1257  psa_algorithm_t alg,
1258  const uint8_t *input,
1259  size_t input_length,
1260  const uint8_t *mac,
1261  size_t mac_length);
1262 
1292 
1298 #ifdef __DOXYGEN_ONLY__
1299 /* This is an example definition for documentation purposes.
1300  * Implementations should define a suitable value in `crypto_struct.h`.
1301  */
1302 #define PSA_MAC_OPERATION_INIT { 0 }
1303 #endif
1304 
1308 
1369  psa_algorithm_t alg);
1370 
1431  psa_algorithm_t alg);
1432 
1460  const uint8_t *input,
1461  size_t input_length);
1462 
1509  uint8_t *mac,
1510  size_t mac_size,
1511  size_t *mac_length);
1512 
1552  const uint8_t *mac,
1553  size_t mac_length);
1554 
1581 
1628  psa_algorithm_t alg,
1629  const uint8_t *input,
1630  size_t input_length,
1631  uint8_t *output,
1632  size_t output_size,
1633  size_t *output_length);
1634 
1675  psa_algorithm_t alg,
1676  const uint8_t *input,
1677  size_t input_length,
1678  uint8_t *output,
1679  size_t output_size,
1680  size_t *output_length);
1681 
1711 
1717 #ifdef __DOXYGEN_ONLY__
1718 /* This is an example definition for documentation purposes.
1719  * Implementations should define a suitable value in `crypto_struct.h`.
1720  */
1721 #define PSA_CIPHER_OPERATION_INIT { 0 }
1722 #endif
1723 
1727 
1789  psa_algorithm_t alg);
1790 
1852  psa_algorithm_t alg);
1853 
1889  uint8_t *iv,
1890  size_t iv_size,
1891  size_t *iv_length);
1892 
1930  const uint8_t *iv,
1931  size_t iv_length);
1932 
1971  const uint8_t *input,
1972  size_t input_length,
1973  uint8_t *output,
1974  size_t output_size,
1975  size_t *output_length);
1976 
2023  uint8_t *output,
2024  size_t output_size,
2025  size_t *output_length);
2026 
2053 
2122  psa_algorithm_t alg,
2123  const uint8_t *nonce,
2124  size_t nonce_length,
2125  const uint8_t *additional_data,
2126  size_t additional_data_length,
2127  const uint8_t *plaintext,
2128  size_t plaintext_length,
2129  uint8_t *ciphertext,
2130  size_t ciphertext_size,
2131  size_t *ciphertext_length);
2132 
2195  psa_algorithm_t alg,
2196  const uint8_t *nonce,
2197  size_t nonce_length,
2198  const uint8_t *additional_data,
2199  size_t additional_data_length,
2200  const uint8_t *ciphertext,
2201  size_t ciphertext_length,
2202  uint8_t *plaintext,
2203  size_t plaintext_size,
2204  size_t *plaintext_length);
2205 
2235 
2241 #ifdef __DOXYGEN_ONLY__
2242 /* This is an example definition for documentation purposes.
2243  * Implementations should define a suitable value in `crypto_struct.h`.
2244  */
2245 #define PSA_AEAD_OPERATION_INIT { 0 }
2246 #endif
2247 
2251 
2321 
2387 
2424  uint8_t *nonce,
2425  size_t nonce_size,
2426  size_t *nonce_length);
2427 
2464  const uint8_t *nonce,
2465  size_t nonce_length);
2466 
2509  size_t ad_length,
2510  size_t plaintext_length);
2511 
2557  const uint8_t *input,
2558  size_t input_length);
2559 
2641  const uint8_t *input,
2642  size_t input_length,
2643  uint8_t *output,
2644  size_t output_size,
2645  size_t *output_length);
2646 
2727  uint8_t *ciphertext,
2728  size_t ciphertext_size,
2729  size_t *ciphertext_length,
2730  uint8_t *tag,
2731  size_t tag_size,
2732  size_t *tag_length);
2733 
2810  uint8_t *plaintext,
2811  size_t plaintext_size,
2812  size_t *plaintext_length,
2813  const uint8_t *tag,
2814  size_t tag_length);
2815 
2842 
2909  const uint8_t *input,
2910  size_t input_length,
2911  uint8_t *signature,
2912  size_t signature_size,
2913  size_t *signature_length);
2914 
2961  const uint8_t *input,
2962  size_t input_length,
2963  const uint8_t *signature,
2964  size_t signature_length);
2965 
3014  const uint8_t *hash,
3015  size_t hash_length,
3016  uint8_t *signature,
3017  size_t signature_size,
3018  size_t *signature_length);
3019 
3065  const uint8_t *hash,
3066  size_t hash_length,
3067  const uint8_t *signature,
3068  size_t signature_length);
3069 
3123  const uint8_t *input,
3124  size_t input_length,
3125  const uint8_t *salt,
3126  size_t salt_length,
3127  uint8_t *output,
3128  size_t output_size,
3129  size_t *output_length);
3130 
3184  const uint8_t *input,
3185  size_t input_length,
3186  const uint8_t *salt,
3187  size_t salt_length,
3188  uint8_t *output,
3189  size_t output_size,
3190  size_t *output_length);
3191 
3228 
3234 #ifdef __DOXYGEN_ONLY__
3235 /* This is an example definition for documentation purposes.
3236  * Implementations should define a suitable value in `crypto_struct.h`.
3237  */
3238 #define PSA_KEY_DERIVATION_OPERATION_INIT { 0 }
3239 #endif
3240 
3244 
3304  psa_key_derivation_operation_t *operation,
3306 
3327  const psa_key_derivation_operation_t *operation,
3328  size_t *capacity);
3329 
3355  psa_key_derivation_operation_t *operation,
3356  size_t capacity);
3357 
3365 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t) (-1))
3366 
3408  psa_key_derivation_operation_t *operation,
3410  const uint8_t *data,
3411  size_t data_length);
3412 
3459  psa_key_derivation_operation_t *operation,
3461  mbedtls_svc_key_id_t key);
3462 
3527  psa_key_derivation_operation_t *operation,
3529  mbedtls_svc_key_id_t private_key,
3530  const uint8_t *peer_key,
3531  size_t peer_key_length);
3532 
3571  psa_key_derivation_operation_t *operation,
3572  uint8_t *output,
3573  size_t output_length);
3574 
3715  const psa_key_attributes_t *attributes,
3716  psa_key_derivation_operation_t *operation,
3717  mbedtls_svc_key_id_t *key);
3718 
3743  psa_key_derivation_operation_t *operation);
3744 
3796  mbedtls_svc_key_id_t private_key,
3797  const uint8_t *peer_key,
3798  size_t peer_key_length,
3799  uint8_t *output,
3800  size_t output_size,
3801  size_t *output_length);
3802 
3833 psa_status_t psa_generate_random(uint8_t *output,
3834  size_t output_size);
3835 
3881  mbedtls_svc_key_id_t *key);
3882 
3885 #ifdef __cplusplus
3886 }
3887 #endif
3888 
3889 /* The file "crypto_sizes.h" contains definitions for size calculation
3890  * macros whose definitions are implementation-specific. */
3891 #include "crypto_sizes.h"
3892 
3893 /* The file "crypto_struct.h" contains definitions for
3894  * implementation-specific structs that are declared above. */
3895 #include "crypto_struct.h"
3896 
3897 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3898  * can include vendor-defined algorithms, extra functions, etc. */
3899 #include "crypto_extra.h"
3900 
3901 #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_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_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_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_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:447
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 of 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:125
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:314
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:69
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:283
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_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_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:174
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_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:50
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)