Mbed TLS v2.28.8
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 
134 static void psa_set_key_id(psa_key_attributes_t *attributes,
136 
137 #ifdef MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
138 
152 static void mbedtls_set_key_owner_id(psa_key_attributes_t *attributes,
153  mbedtls_key_owner_id_t owner);
154 #endif
155 
181 static void psa_set_key_lifetime(psa_key_attributes_t *attributes,
182  psa_key_lifetime_t lifetime);
183 
197  const psa_key_attributes_t *attributes);
198 
210  const psa_key_attributes_t *attributes);
211 
228 static void psa_set_key_usage_flags(psa_key_attributes_t *attributes,
229  psa_key_usage_t usage_flags);
230 
242  const psa_key_attributes_t *attributes);
243 
274 static void psa_set_key_algorithm(psa_key_attributes_t *attributes,
275  psa_algorithm_t alg);
276 
277 
289  const psa_key_attributes_t *attributes);
290 
305 static void psa_set_key_type(psa_key_attributes_t *attributes,
306  psa_key_type_t type);
307 
308 
323 static void psa_set_key_bits(psa_key_attributes_t *attributes,
324  size_t bits);
325 
336 static psa_key_type_t psa_get_key_type(const psa_key_attributes_t *attributes);
337 
348 static size_t psa_get_key_bits(const psa_key_attributes_t *attributes);
349 
379  psa_key_attributes_t *attributes);
380 
394 
423 
513  const psa_key_attributes_t *attributes,
514  mbedtls_svc_key_id_t *target_key);
515 
516 
563 
642  const uint8_t *data,
643  size_t data_length,
644  mbedtls_svc_key_id_t *key);
645 
646 
647 
737  uint8_t *data,
738  size_t data_size,
739  size_t *data_length);
740 
812  uint8_t *data,
813  size_t data_size,
814  size_t *data_length);
815 
816 
817 
856  const uint8_t *input,
857  size_t input_length,
858  uint8_t *hash,
859  size_t hash_size,
860  size_t *hash_length);
861 
891  const uint8_t *input,
892  size_t input_length,
893  const uint8_t *hash,
894  size_t hash_length);
895 
925 
931 #ifdef __DOXYGEN_ONLY__
932 /* This is an example definition for documentation purposes.
933  * Implementations should define a suitable value in `crypto_struct.h`.
934  */
935 #define PSA_HASH_OPERATION_INIT { 0 }
936 #endif
937 
941 
991  psa_algorithm_t alg);
992 
1017  const uint8_t *input,
1018  size_t input_length);
1019 
1063  uint8_t *hash,
1064  size_t hash_size,
1065  size_t *hash_length);
1066 
1104  const uint8_t *hash,
1105  size_t hash_length);
1106 
1133 
1161 psa_status_t psa_hash_clone(const psa_hash_operation_t *source_operation,
1162  psa_hash_operation_t *target_operation);
1163 
1213  psa_algorithm_t alg,
1214  const uint8_t *input,
1215  size_t input_length,
1216  uint8_t *mac,
1217  size_t mac_size,
1218  size_t *mac_length);
1219 
1254  psa_algorithm_t alg,
1255  const uint8_t *input,
1256  size_t input_length,
1257  const uint8_t *mac,
1258  size_t mac_length);
1259 
1289 
1295 #ifdef __DOXYGEN_ONLY__
1296 /* This is an example definition for documentation purposes.
1297  * Implementations should define a suitable value in `crypto_struct.h`.
1298  */
1299 #define PSA_MAC_OPERATION_INIT { 0 }
1300 #endif
1301 
1305 
1366  psa_algorithm_t alg);
1367 
1428  psa_algorithm_t alg);
1429 
1457  const uint8_t *input,
1458  size_t input_length);
1459 
1506  uint8_t *mac,
1507  size_t mac_size,
1508  size_t *mac_length);
1509 
1549  const uint8_t *mac,
1550  size_t mac_length);
1551 
1578 
1625  psa_algorithm_t alg,
1626  const uint8_t *input,
1627  size_t input_length,
1628  uint8_t *output,
1629  size_t output_size,
1630  size_t *output_length);
1631 
1672  psa_algorithm_t alg,
1673  const uint8_t *input,
1674  size_t input_length,
1675  uint8_t *output,
1676  size_t output_size,
1677  size_t *output_length);
1678 
1708 
1714 #ifdef __DOXYGEN_ONLY__
1715 /* This is an example definition for documentation purposes.
1716  * Implementations should define a suitable value in `crypto_struct.h`.
1717  */
1718 #define PSA_CIPHER_OPERATION_INIT { 0 }
1719 #endif
1720 
1724 
1786  psa_algorithm_t alg);
1787 
1849  psa_algorithm_t alg);
1850 
1886  uint8_t *iv,
1887  size_t iv_size,
1888  size_t *iv_length);
1889 
1927  const uint8_t *iv,
1928  size_t iv_length);
1929 
1968  const uint8_t *input,
1969  size_t input_length,
1970  uint8_t *output,
1971  size_t output_size,
1972  size_t *output_length);
1973 
2020  uint8_t *output,
2021  size_t output_size,
2022  size_t *output_length);
2023 
2050 
2119  psa_algorithm_t alg,
2120  const uint8_t *nonce,
2121  size_t nonce_length,
2122  const uint8_t *additional_data,
2123  size_t additional_data_length,
2124  const uint8_t *plaintext,
2125  size_t plaintext_length,
2126  uint8_t *ciphertext,
2127  size_t ciphertext_size,
2128  size_t *ciphertext_length);
2129 
2192  psa_algorithm_t alg,
2193  const uint8_t *nonce,
2194  size_t nonce_length,
2195  const uint8_t *additional_data,
2196  size_t additional_data_length,
2197  const uint8_t *ciphertext,
2198  size_t ciphertext_length,
2199  uint8_t *plaintext,
2200  size_t plaintext_size,
2201  size_t *plaintext_length);
2202 
2232 
2238 #ifdef __DOXYGEN_ONLY__
2239 /* This is an example definition for documentation purposes.
2240  * Implementations should define a suitable value in `crypto_struct.h`.
2241  */
2242 #define PSA_AEAD_OPERATION_INIT { 0 }
2243 #endif
2244 
2248 
2318 
2384 
2421  uint8_t *nonce,
2422  size_t nonce_size,
2423  size_t *nonce_length);
2424 
2461  const uint8_t *nonce,
2462  size_t nonce_length);
2463 
2506  size_t ad_length,
2507  size_t plaintext_length);
2508 
2554  const uint8_t *input,
2555  size_t input_length);
2556 
2638  const uint8_t *input,
2639  size_t input_length,
2640  uint8_t *output,
2641  size_t output_size,
2642  size_t *output_length);
2643 
2724  uint8_t *ciphertext,
2725  size_t ciphertext_size,
2726  size_t *ciphertext_length,
2727  uint8_t *tag,
2728  size_t tag_size,
2729  size_t *tag_length);
2730 
2807  uint8_t *plaintext,
2808  size_t plaintext_size,
2809  size_t *plaintext_length,
2810  const uint8_t *tag,
2811  size_t tag_length);
2812 
2839 
2906  const uint8_t *input,
2907  size_t input_length,
2908  uint8_t *signature,
2909  size_t signature_size,
2910  size_t *signature_length);
2911 
2958  const uint8_t *input,
2959  size_t input_length,
2960  const uint8_t *signature,
2961  size_t signature_length);
2962 
3011  const uint8_t *hash,
3012  size_t hash_length,
3013  uint8_t *signature,
3014  size_t signature_size,
3015  size_t *signature_length);
3016 
3062  const uint8_t *hash,
3063  size_t hash_length,
3064  const uint8_t *signature,
3065  size_t signature_length);
3066 
3120  const uint8_t *input,
3121  size_t input_length,
3122  const uint8_t *salt,
3123  size_t salt_length,
3124  uint8_t *output,
3125  size_t output_size,
3126  size_t *output_length);
3127 
3181  const uint8_t *input,
3182  size_t input_length,
3183  const uint8_t *salt,
3184  size_t salt_length,
3185  uint8_t *output,
3186  size_t output_size,
3187  size_t *output_length);
3188 
3225 
3231 #ifdef __DOXYGEN_ONLY__
3232 /* This is an example definition for documentation purposes.
3233  * Implementations should define a suitable value in `crypto_struct.h`.
3234  */
3235 #define PSA_KEY_DERIVATION_OPERATION_INIT { 0 }
3236 #endif
3237 
3241 
3301  psa_key_derivation_operation_t *operation,
3303 
3324  const psa_key_derivation_operation_t *operation,
3325  size_t *capacity);
3326 
3352  psa_key_derivation_operation_t *operation,
3353  size_t capacity);
3354 
3362 #define PSA_KEY_DERIVATION_UNLIMITED_CAPACITY ((size_t) (-1))
3363 
3405  psa_key_derivation_operation_t *operation,
3407  const uint8_t *data,
3408  size_t data_length);
3409 
3456  psa_key_derivation_operation_t *operation,
3458  mbedtls_svc_key_id_t key);
3459 
3524  psa_key_derivation_operation_t *operation,
3526  mbedtls_svc_key_id_t private_key,
3527  const uint8_t *peer_key,
3528  size_t peer_key_length);
3529 
3568  psa_key_derivation_operation_t *operation,
3569  uint8_t *output,
3570  size_t output_length);
3571 
3712  const psa_key_attributes_t *attributes,
3713  psa_key_derivation_operation_t *operation,
3714  mbedtls_svc_key_id_t *key);
3715 
3740  psa_key_derivation_operation_t *operation);
3741 
3793  mbedtls_svc_key_id_t private_key,
3794  const uint8_t *peer_key,
3795  size_t peer_key_length,
3796  uint8_t *output,
3797  size_t output_size,
3798  size_t *output_length);
3799 
3830 psa_status_t psa_generate_random(uint8_t *output,
3831  size_t output_size);
3832 
3878  mbedtls_svc_key_id_t *key);
3879 
3882 #ifdef __cplusplus
3883 }
3884 #endif
3885 
3886 /* The file "crypto_sizes.h" contains definitions for size calculation
3887  * macros whose definitions are implementation-specific. */
3888 #include "crypto_sizes.h"
3889 
3890 /* The file "crypto_struct.h" contains definitions for
3891  * implementation-specific structs that are declared above. */
3892 #include "crypto_struct.h"
3893 
3894 /* The file "crypto_extra.h" contains vendor-specific definitions. This
3895  * can include vendor-defined algorithms, extra functions, etc. */
3896 #include "crypto_extra.h"
3897 
3898 #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)