mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-01-31 18:32:57 +00:00
Remove temporary documents
The dependencies-xxx.md documents where merely a support for study, now distilled to strategy.md, psa-limitation.md, and tasks-xx.md and/or github issues. The tasks-g1.md document has now been fully converted to a list of github issues. These documents would quickly become out-of-date and there's little point in updating them, so it's better to remove them. They're still in the github history if anyone wants to have a look. Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
This commit is contained in:
Manuel Pégourié-Gonnard
parent
ec3fd75cbc
commit
335cbf61da
@ -1,563 +0,0 @@
|
||||
Dependencies of the TLS library on the Crypto library
|
||||
=====================================================
|
||||
|
||||
This document is part of the technical study on how to port Mbed TLS to PSA
|
||||
Crypto. It describes the dependencies of libmbedtls.a on libmbedcrypto.a.
|
||||
|
||||
More precisely, it describes what functions from libmbedcrypto.a are called
|
||||
from libmbedtls.a - other forms of dependencies such as using static inline
|
||||
functions or types, accessing private struct members, etc., are not listed.
|
||||
|
||||
It is based on Mbed TLS 3.0, excluding experimental support for TLS 1.3, and
|
||||
also excluding support for restartble ECP operations.
|
||||
|
||||
Non-Crypto dependencies
|
||||
-----------------------
|
||||
|
||||
The TLS library has a number of dependencies on libmbedcrypto.a that are not
|
||||
cryptographic, hence are unlikely to be covered by the PSA Crypto API.
|
||||
|
||||
These involve the following modules:
|
||||
|
||||
- threading
|
||||
- platform
|
||||
|
||||
It also depends on the X.509 library, which is excluded from further analysis
|
||||
as the focus here is on dependencies on libmbedcrypto.a.
|
||||
|
||||
Crypto dependencies (high-level)
|
||||
--------------------------------
|
||||
|
||||
The TLS library depends on the following cryptographic modules:
|
||||
|
||||
- cipher
|
||||
- dhm
|
||||
- ecdh
|
||||
- ecjpake
|
||||
- ecp
|
||||
- md
|
||||
- mpi
|
||||
- pk
|
||||
- sha256
|
||||
- sha512
|
||||
|
||||
More specifically, calls are made to the following API functions:
|
||||
|
||||
```
|
||||
mbedtls_cipher_auth_decrypt_ext
|
||||
mbedtls_cipher_auth_encrypt_ext
|
||||
mbedtls_cipher_crypt
|
||||
mbedtls_cipher_free
|
||||
mbedtls_cipher_info_from_type
|
||||
mbedtls_cipher_init
|
||||
mbedtls_cipher_set_padding_mode
|
||||
mbedtls_cipher_setkey
|
||||
mbedtls_cipher_setup
|
||||
|
||||
mbedtls_dhm_calc_secret
|
||||
mbedtls_dhm_free
|
||||
mbedtls_dhm_get_bitlen
|
||||
mbedtls_dhm_get_len
|
||||
mbedtls_dhm_get_value
|
||||
mbedtls_dhm_init
|
||||
mbedtls_dhm_make_params
|
||||
mbedtls_dhm_make_public
|
||||
mbedtls_dhm_read_params
|
||||
mbedtls_dhm_read_public
|
||||
mbedtls_dhm_set_group
|
||||
|
||||
mbedtls_ecdh_calc_secret
|
||||
mbedtls_ecdh_free
|
||||
mbedtls_ecdh_get_params
|
||||
mbedtls_ecdh_init
|
||||
mbedtls_ecdh_make_params
|
||||
mbedtls_ecdh_make_public
|
||||
mbedtls_ecdh_read_params
|
||||
mbedtls_ecdh_read_public
|
||||
mbedtls_ecdh_setup
|
||||
|
||||
mbedtls_ecjpake_check
|
||||
mbedtls_ecjpake_derive_secret
|
||||
mbedtls_ecjpake_free
|
||||
mbedtls_ecjpake_init
|
||||
mbedtls_ecjpake_read_round_one
|
||||
mbedtls_ecjpake_read_round_two
|
||||
mbedtls_ecjpake_set_point_format
|
||||
mbedtls_ecjpake_setup
|
||||
mbedtls_ecjpake_write_round_one
|
||||
mbedtls_ecjpake_write_round_two
|
||||
|
||||
mbedtls_ecp_curve_info_from_grp_id
|
||||
mbedtls_ecp_curve_info_from_tls_id
|
||||
|
||||
mbedtls_md_clone
|
||||
mbedtls_md_finish
|
||||
mbedtls_md_free
|
||||
mbedtls_md_get_size
|
||||
mbedtls_md_get_type
|
||||
mbedtls_md_hmac_finish
|
||||
mbedtls_md_hmac_reset
|
||||
mbedtls_md_hmac_starts
|
||||
mbedtls_md_hmac_update
|
||||
mbedtls_md_info_from_type
|
||||
mbedtls_md_init
|
||||
mbedtls_md_setup
|
||||
mbedtls_md_starts
|
||||
mbedtls_md_update
|
||||
|
||||
mbedtls_mpi_bitlen
|
||||
mbedtls_mpi_free
|
||||
mbedtls_mpi_read_binary
|
||||
|
||||
mbedtls_pk_can_do
|
||||
mbedtls_pk_debug
|
||||
mbedtls_pk_decrypt
|
||||
mbedtls_pk_encrypt
|
||||
mbedtls_pk_get_bitlen
|
||||
mbedtls_pk_sign
|
||||
mbedtls_pk_sign_restartable
|
||||
mbedtls_pk_verify
|
||||
mbedtls_pk_verify_restartable
|
||||
|
||||
mbedtls_sha256_clone
|
||||
mbedtls_sha256_finish
|
||||
mbedtls_sha256_free
|
||||
mbedtls_sha256_init
|
||||
mbedtls_sha256_starts
|
||||
mbedtls_sha256_update
|
||||
|
||||
mbedtls_sha512_clone
|
||||
mbedtls_sha512_finish
|
||||
mbedtls_sha512_free
|
||||
mbedtls_sha512_init
|
||||
mbedtls_sha512_starts
|
||||
mbedtls_sha512_update
|
||||
```
|
||||
|
||||
Note: the direct dependency on MPI functions is in order to manage DHM
|
||||
parameters, that are currently stored as a pair of MPIs in the
|
||||
`mbedtls_ssl_config` structure. (The public API uses byte arrays or a
|
||||
`mbedtls_dhm_context` structure.)
|
||||
|
||||
Note: the direct dependency on ECP APIs is in order to access information;
|
||||
no crypto operation is done directly via this API, only via the PK and ECDH
|
||||
APIs.
|
||||
|
||||
Note: the direct dependencies on the SHA-2 modules instead of using the
|
||||
MD layer is for convenience (and perhaps to save some memory as well) and can
|
||||
easily be replace by use of a more generic API.
|
||||
|
||||
Key exchanges and other configuration options
|
||||
---------------------------------------------
|
||||
|
||||
In the file-level analysis below, many things are only used if certain key
|
||||
exchanges or other configuration options are enabled. This section sums up
|
||||
those key exchanges and options.
|
||||
|
||||
Key exchanges:
|
||||
|
||||
- DHE-PSK
|
||||
- DHE-RSA
|
||||
- ECDH-ECDSA
|
||||
- ECDH-RSA
|
||||
- ECDHE-ECDSA
|
||||
- ECDHE-PSK
|
||||
- ECDHE-RSA
|
||||
- ECJPAKE
|
||||
- PSK
|
||||
- RSA
|
||||
- RSA-PSK
|
||||
|
||||
Protocol:
|
||||
|
||||
- `MBEDTLS_SSL_PROTO_TLS1_2`
|
||||
- `MBEDTLS_SSL_PROTO_DTLS`
|
||||
- `MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL` (excluded from this analysis)
|
||||
|
||||
TLS sides:
|
||||
|
||||
- `MBEDTLS_SSL_CLI_C`
|
||||
- `MBEDTLS_SSL_SRV_C`
|
||||
|
||||
TLS support modules:
|
||||
|
||||
- `MBEDTLS_SSL_CACHE_C`
|
||||
- `MBEDTLS_SSL_COOKIE_C`
|
||||
- `MBEDTLS_SSL_TICKET_C`
|
||||
|
||||
Cipher modes:
|
||||
|
||||
- `MBEDTLS_CIPHER_MODE_CBC`
|
||||
- `MBEDTLS_CIPHER_NULL_CIPHER`
|
||||
- `MBEDTLS_GCM_C`
|
||||
- `MBEDTLS_CCM_C`
|
||||
- `MBEDTLS_CHACHAPOLY_C`
|
||||
|
||||
Hashes:
|
||||
|
||||
- `MBEDTLS_MD5_C` (ciphersuites using HMAC-MD5)
|
||||
- `MBEDTLS_SHA1_C` (ciphersuites using HMAC-SHA1)
|
||||
- `MBEDTLS_SHA256_C`
|
||||
- `MBEDTLS_SHA512_C`
|
||||
|
||||
Other options:
|
||||
|
||||
- `MBEDTLS_X509_CRT_PARSE_C`
|
||||
- `MBEDTLS_SSL_SESSION_TICKETS`
|
||||
- `MBEDTLS_SSL_ENCRYPT_THEN_MAC`
|
||||
|
||||
|
||||
File-level analysis
|
||||
-------------------
|
||||
|
||||
The TLS library consists of the following files (excluding TLS 1.3 which is
|
||||
currently experimental and changing rapidly):
|
||||
|
||||
```
|
||||
library/debug.c
|
||||
library/net_sockets.c
|
||||
library/ssl_cache.c
|
||||
library/ssl_ciphersuites.c
|
||||
library/ssl_cli.c
|
||||
library/ssl_cookie.c
|
||||
library/ssl_msg.c
|
||||
library/ssl_srv.c
|
||||
library/ssl_ticket.c
|
||||
library/ssl_tls.c
|
||||
```
|
||||
|
||||
The file `net_sockets.c` is excluded from further analysis as it's unrelated.
|
||||
|
||||
**Note:** Calls to `f_rng` in the files below could also be replaced with
|
||||
direct calls to the global PSA RNG; however these calls are not included in
|
||||
the current analysis, since the PSA RNG can already be used by setting it
|
||||
explicitly.
|
||||
|
||||
### `debug.c`
|
||||
|
||||
- In `debug_print_pk()`
|
||||
call `mbedtls_pk_debug()`
|
||||
to print info (or "invalid PK context" on failure)
|
||||
if `MBEDTLS_X509_CRT_PARSE_C` is enabled.
|
||||
|
||||
- In `mbedtls_debug_print_mpi()`
|
||||
call `mbedtls_mpi_print_mpi()`
|
||||
|
||||
### `ssl_cache.c`
|
||||
|
||||
**Note:** This module is only used server side.
|
||||
|
||||
No call to any crypto API function from this file.
|
||||
|
||||
_Note :_ in the future, work may be required in order to securely store
|
||||
session secrets in the cache, but it's outside the scope of this analysis.
|
||||
|
||||
### `ssl_ciphersuites.c`
|
||||
|
||||
No call to any crypto API function from this file.
|
||||
|
||||
### `ssl_cookie.c`
|
||||
|
||||
**Note:** this module is only used server-side, only for DTLS.
|
||||
|
||||
- In `mbedtls_ssl_cookie_init()` / `mbedtls_ssl_cookie_free()`
|
||||
call `mbedtls_md_init()` / `mbedtls_md_free()`
|
||||
|
||||
- In `mbedtls_ssl_cookie_setup()`
|
||||
call `mbedtls_md_setup()`, `mbedtls_md_info_from_type()` and `mbedtls_md_hmac_starts()`
|
||||
to set up an HMAC key.
|
||||
|
||||
- In `ssl_cookie_hmac()`
|
||||
call `mbedtls_md_hmac_reset()`, `mbedtls_md_hmac_update()` and `mbedtls_md_hmac_finish()`
|
||||
|
||||
### `ssl_ticket.c`
|
||||
|
||||
**Note:** This module is only used server-side.
|
||||
|
||||
- In `ssl_ticket_gen_key()`
|
||||
call `mbedtls_cipher_setkey()` and `mbedtls_cipher_get_key_bitlen()`
|
||||
|
||||
- In `mbedtls_ssl_ticket_setup()`
|
||||
call `mbedtls_cipher_info_from_type()` and `mbedtls_cipher_setup()`
|
||||
|
||||
- In `mbedtls_ssl_ticket_write()`
|
||||
call `mbedtls_cipher_auth_encrypt_ext()`
|
||||
|
||||
- In `mbedtls_ssl_ticket_parse()`
|
||||
call `mbedtls_cipher_auth_decrypt_ext()`
|
||||
|
||||
### `ssl_cli.c`
|
||||
|
||||
**Note:** This module is only used client-side.
|
||||
|
||||
- In `ssl_write_supported_elliptic_curves_ext()`
|
||||
call `mbedtls_ecp_curve_list()` and `mbedtls_ecp_curve_info_from_grp_id()`
|
||||
if ECDH, ECDSA or ECJPAKE is enabled
|
||||
|
||||
- In `ssl_write_ecjpake_kkpp_ext()`
|
||||
call `mbedtls_ecjpake_check()` and `mbedtls_ecjpake_write_round_one()`
|
||||
if ECJPAKE is enabled
|
||||
|
||||
- In `ssl_parse_supported_point_formats_ext()`
|
||||
call `mbedtls_ecjpake_set_point_format()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_validate_ciphersuite()`
|
||||
call `mbedtls_ecjpake_check()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_parse_ecjpake_kkpp()`
|
||||
call `mbedtls_ecjpake_read_round_one()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_parse_server_dh_params()`
|
||||
call `mbedtls_dhm_read_params()` and `mbedtls_dhm_get_bitlen()`
|
||||
if DHE-RSA or DHE-PSK key echange is enabled.
|
||||
|
||||
- In `ssl_check_server_ecdh_params()`
|
||||
call `mbedtls_ecp_curve_info_from_grp_id()`
|
||||
if ECDHE-RSA, ECDHE-ECDSA, ECDHE-PSK, ECDH-RSA or ECDH-ECDSA key exchange is enabled.
|
||||
|
||||
- In `ssl_parse_server_ecdh_params()`
|
||||
call `mbedtls_ecdh_read_params()`
|
||||
if ECDHE-RSA, ECDHE-ECDSA or ECDHE-PSK is enabled.
|
||||
|
||||
- In `ssl_write_encrypted_pms()`
|
||||
call `mbedtls_pk_can_do()` and `mbedtls_pk_encrypt()` on peer's public key
|
||||
if RSA or RSA-PSK key exchange enabled.
|
||||
|
||||
- In `ssl_get_ecdh_params_from_cert()`
|
||||
call `mbedtls_pk_can_do()` and `mbedtls_pk_ec()` and `mbedtls_ecdh_get_params()`
|
||||
if ECDH-RSA or ECDH-ECDSA key exchange is enabled
|
||||
to import public key of peer's cert to ECDH context.
|
||||
|
||||
- In `ssl_parse_server_key_exchange()`
|
||||
call `mbedtls_ecjpake_read_round_two()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_parse_server_key_exchange()`
|
||||
call `mbedtls_pk_can_do()` and `mbedtls_pk_verify_restartable()`
|
||||
if DHE-RSA, ECDHE-RSA or ECDHE-ECDSA is enabled.
|
||||
(Note: the hash is computed by `mbedtls_ssl_get_key_exchange_md_tls1_2()`.)
|
||||
|
||||
- In `ssl_write_client_key_exchange()`
|
||||
call `mbedtls_dhm_make_public()`, `mbedtls_dhm_get_len()` and `mbedtls_dhm_calc_secret()`
|
||||
if DHE-RSA key exchange is enabled.
|
||||
|
||||
- In `ssl_write_client_key_exchange()`
|
||||
call `mbedtls_ecdh_make_public()` and `mbedtls_ecdh_calc_secret()`
|
||||
if ECDHE-RSA, ECDHE-ECDSA, ECDH-RSA or ECDH-ECDSA is enabled.
|
||||
|
||||
- In `ssl_write_client_key_exchange()`
|
||||
call `mbedtls_dhm_make_public()` and `mbedtls_dhm_get_len()`
|
||||
if DHE-PSK is enabled.
|
||||
|
||||
- In `ssl_write_client_key_exchange()`
|
||||
call `mbedtls_ecdh_make_public()`
|
||||
if ECDHE-PSK is enabled.
|
||||
|
||||
- In `ssl_write_client_key_exchange()`
|
||||
call `mbedtls_ecjpake_write_round_two()` and `mbedtls_ecjpake_derive_secret()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_write_certificate_verify()`
|
||||
call `mbedtls_pk_can_do()` and `mbedtls_pk_sign_restartable()`
|
||||
if RSA, DHE-RSA, ECDH-RSA, ECDHE-RSA, ECDH-ECDSA or ECDHE-ECDSA is enabled.
|
||||
(Note: the hash is computed by `calc_verify()`.)
|
||||
|
||||
### `ssl_srv.c`
|
||||
|
||||
**Note:** This module is only used server-side.
|
||||
|
||||
- In `ssl_parse_supported_elliptic_curves()`
|
||||
call `mbedtls_ecp_curve_info_from_tls_id()`
|
||||
if ECDH, ECDSA or ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_parse_supported_point_formats()`
|
||||
call `mbedtls_ecjpake_set_point_format()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_parse_ecjpake_kkpp()`
|
||||
call `mbedtls_ecjpake_check()` and `mbedtls_ecjpake_read_round_one()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_check_key_curve()` to get group ID
|
||||
call `mbedtls_pk_ec()`
|
||||
if certificates and ECDSA are enabled.
|
||||
|
||||
- In `ssl_pick_cert()`
|
||||
call `mbedtls_pk_can_do()`
|
||||
if certificates are enabled.
|
||||
|
||||
- In `ssl_write_encrypt_then_mac_ext()`
|
||||
call `mbedtls_cipher_info_from_type()` on ciphersuite info
|
||||
if EtM is enabled
|
||||
|
||||
- In `ssl_write_ecjpake_kkpp_ext()`
|
||||
call `mbedtls_ecjpake_write_round_one()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_get_ecdh_params_from_cert()`
|
||||
call `mbedtls_pk_can_do()`, `mbedtls_pk_ec()` and `mbedtls_ecdh_get_params()`
|
||||
if ECDH-RSA or ECDH-ECDSA is enabled,
|
||||
in order to import own private key to ecdh context.
|
||||
|
||||
- In `ssl_prepare_server_key_exchange()`
|
||||
call `mbedtls_ecjpake_write_round_two()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `ssl_prepare_server_key_exchange()`
|
||||
call `mbedtls_dhm_set_group()`, `mbedtls_dhm_make_params()` and `mbedtls_dhm_get_len()`
|
||||
if DHE-RSA or DHE-PSK key exchange is enabled.
|
||||
|
||||
- In `ssl_prepare_server_key_exchange()`
|
||||
call `mbedtls_ecdh_setup()` and `mbedtls_ecdh_make_params()`
|
||||
if ECDHE-RSA, ECDHE-ECDSA or ECDHE-PSK is enabled.
|
||||
|
||||
- In `ssl_prepare_server_key_exchange()`
|
||||
call `mbedtls_pk_sign()` from `ssl_prepare_server_key_exchange()`
|
||||
if DHE-RSA, ECDHE-RSA or ECDHE-ECDSA is enabled.
|
||||
|
||||
- In `ssl_parse_client_dh_public()`
|
||||
call `mbedtls_dhm_read_public()`
|
||||
if DHE-RSA or DHE-PSK is enabled.
|
||||
|
||||
- In `ssl_decrypt_encrypted_pms()`
|
||||
call `mbedtls_pk_get_len()`, `mbedtls_pk_can_do()` and `mbedtls_pk_decrypt()`
|
||||
if RSA or RSA-PSK key exchange is enabled.
|
||||
|
||||
- In `ssl_parse_client_key_exchange()`
|
||||
call `mbedtls_dhm_calc_secret()`
|
||||
if DHE-RSA enabled.
|
||||
(Note: `ssl_parse_client_dh_public()` called first.)
|
||||
|
||||
- In `ssl_parse_client_key_exchange()`
|
||||
call `mbedtls_ecdh_read_public()` and `mbedtls_ecdh_calc_secret()`
|
||||
if ECDHE-RSA, ECDHE-ECDSA, ECDH-RSA or ECDH-ECDSA enabled.
|
||||
|
||||
- In `ssl_parse_client_key_exchange()`
|
||||
call `mbedtls_ecdh_read_public()`
|
||||
if ECDHE-PSK enabled.
|
||||
(Note: calling `mbedtls_ssl_psk_derive_premaster()` afterwards.)
|
||||
|
||||
- In `ssl_parse_client_key_exchange()`
|
||||
call `mbedtls_ecjpake_read_round_two()` and `mbedtls_ecjpake_derive_secret()`
|
||||
if ECJPAKE enabled.
|
||||
|
||||
- In `ssl_parse_certificate_verify()`
|
||||
call `mbedtls_pk_can_do()` and `mbedtls_pk_verify()`
|
||||
if RSA, DHE-RSA, ECDH-RSA, ECDHE-RSA, ECDH-ECDSA or ECDHE-ECDSA enabled.
|
||||
|
||||
### `ssl_tls.c`
|
||||
|
||||
**Note:** This module is used both server-side and client-side.
|
||||
|
||||
- In `tls_prf_generic()`
|
||||
call `mbedtls_md_init()`, `mbedtls_md_info_from_type()`, `mbedtls_md_get_size()`, `mbedtls_md_setup()`, `mbedtls_md_hmac_starts()`, `mbedtls_md_hmac_update()`, `mbedtls_md_hmac_finish()`, `mbedtls_md_hmac_reset()` and `mbedtls_md_free()`
|
||||
|
||||
- In `mbedtls_ssl_derive_keys()`
|
||||
call `mbedtls_cipher_info_from_type()`, `mbedtls_cipher_setup_psa()` or `mbedtls_cipher_setup()`, `mbedtls_cipher_setkey()`, and `mbedtls_cipher_set_padding_mode()`
|
||||
|
||||
- In `mbedtls_ssl_derive_keys()`.
|
||||
call `mbedtls_md_info_from_type()`, `mbedtls_md_setup()`, `mbedtls_md_get_size()` and `mbedtls_md_hmac_starts()`
|
||||
Note: should be only if CBC/NULL ciphersuites enabled, but is currently unconditional.
|
||||
|
||||
- In `ssl_calc_verify_tls_sha256()`
|
||||
call `mbedtls_sha256_init()` `mbedtls_sha256_clone()` `mbedtls_sha256_finish()` `mbedtls_sha256_free()`
|
||||
if SHA256 is enabled.
|
||||
|
||||
- In `ssl_calc_verify_tls_sha384()`
|
||||
call `mbedtls_sha512_init()` `mbedtls_sha512_clone()` `mbedtls_sha512_finish()` `mbedtls_sha512_free()`
|
||||
if SHA512 is enabled.
|
||||
|
||||
- In `mbedtls_ssl_psk_derive_premaster()`
|
||||
call `mbedtls_dhm_calc_secret()`
|
||||
if DHE-PSK is enabled.
|
||||
|
||||
- In `mbedtls_ssl_psk_derive_premaster()`
|
||||
call `mbedtls_ecdh_calc_secret()`
|
||||
if ECDHE-PSK is enabled.
|
||||
|
||||
- In `ssl_encrypt_buf()`
|
||||
call `mbedtls_cipher_get_cipher_mode()` `mbedtls_md_hmac_update()` `mbedtls_md_hmac_finish()` `mbedtls_md_hmac_reset()` `mbedtls_cipher_crypt()`
|
||||
if CBC or NULL is enabled.
|
||||
|
||||
- In `ssl_encrypt_buf()`
|
||||
call `mbedtls_cipher_get_cipher_mode()`, `mbedtls_cipher_auth_encrypt()`
|
||||
if GCM, CCM or CHACHAPOLY is enabled.
|
||||
|
||||
- In `ssl_decrypt_buf()`
|
||||
call `mbedtls_cipher_get_cipher_mode()` `mbedtls_md_hmac_update()` `mbedtls_md_hmac_finish()` `mbedtls_md_hmac_reset()` `mbedtls_cipher_crypt()`
|
||||
if CBC and Encrypt-then-Mac
|
||||
are enabled.
|
||||
|
||||
- In `mbedtls_ssl_cf_hmac()`
|
||||
call `mbedtls_md_clone()`
|
||||
if CBC or NULL is enabled.
|
||||
|
||||
- In `ssl_decrypt_buf()`
|
||||
call `mbedtls_cipher_get_cipher_mode()`, `mbedtls_cipher_auth_decrypt()`
|
||||
if GCM, CCM or CHACHAPOLY is enabled.
|
||||
|
||||
- In `mbedtls_ssl_parse_certificate()`
|
||||
call `mbedtls_pk_can_do()` and `mbedtls_pk_ec()`
|
||||
to get and check group ID.
|
||||
|
||||
- In `mbedtls_ssl_reset_checksum()`.
|
||||
call `mbedtls_sha256_starts()` `mbedtls_sha512_starts()`
|
||||
|
||||
- In `ssl_update_checksum_start()`.
|
||||
call `mbedtls_sha256_update()` `mbedtls_sha512_update()`
|
||||
|
||||
- In `ssl_update_checksum_sha256()`
|
||||
call `mbedtls_sha256_update()`
|
||||
if SHA256 is enabled.
|
||||
|
||||
- In `ssl_update_checksum_sha512()`
|
||||
call `mbedtls_sha512_update()`
|
||||
if SHA512 is enabled.
|
||||
|
||||
- In `ssl_calc_finished_tls_sha256()`
|
||||
call `mbedtls_sha256_init()` `mbedtls_sha256_clone()` `mbedtls_sha256_finish()` `mbedtls_sha256_free()`
|
||||
if SHA256 is enabled.
|
||||
|
||||
- In `ssl_calc_finished_tls_sha512()`
|
||||
call `mbedtls_sha512_init()` `mbedtls_sha512_clone()` `mbedtls_sha512_finish()` `mbedtls_sha512_free()`
|
||||
if SHA512 is enabled.
|
||||
|
||||
- In `ssl_handshake_params_init()`.
|
||||
call `mbedtls_sha256_init()` `mbedtls_sha256_starts()` `mbedtls_sha512_init()` `mbedtls_sha512_starts()` `mbedtls_dhm_init()` `mbedtls_ecdh_init()` `mbedtls_ecjpake_init()`
|
||||
|
||||
- In `ssl_transform_init()`.
|
||||
call `mbedtls_cipher_init()` `mbedtls_md_init()`
|
||||
|
||||
- In `mbedtls_ssl_set_hs_ecjpake_password()`
|
||||
call `mbedtls_ecjpake_setup()`
|
||||
if ECJPAKE is enabled.
|
||||
|
||||
- In `mbedtls_ssl_conf_dh_param_bin()`
|
||||
call `mbedtls_mpi_read_binary()` and `mbedtls_mpi_free()`
|
||||
if DHM and SRV are enabled.
|
||||
|
||||
- In `mbedtls_ssl_conf_dh_param_ctx()`
|
||||
call `mbedtls_dhm_get_value()` and `mbedtls_mpi_free()`
|
||||
if DHM and SRV are enabled.
|
||||
|
||||
- In `mbedtls_ssl_get_record_expansion()`.
|
||||
call `mbedtls_cipher_get_cipher_mode()` and `mbedtls_cipher_get_block_size()`
|
||||
|
||||
- In `mbedtls_ssl_transform_free()`.
|
||||
call `mbedtls_cipher_free()` and `mbedtls_md_free()`
|
||||
|
||||
- In `mbedtls_ssl_handshake_free()`.
|
||||
call `mbedtls_sha256_free()` `mbedtls_sha512_free()` `mbedtls_dhm_free()` `mbedtls_ecdh_free()` `mbedtls_ecjpake_free()`
|
||||
|
||||
- In `mbedtls_ssl_config_free()`
|
||||
call `mbedtls_mpi_free()`
|
||||
if DHM is enabled.
|
||||
|
||||
- In `mbedtls_ssl_sig_from_pk()`.
|
||||
call `mbedtls_pk_can_do()`
|
||||
|
||||
- In `mbedtls_ssl_get_key_exchange_md_tls1_2()`
|
||||
call `mbedtls_md_info_from_type()` `mbedtls_md_get_size()` `mbedtls_md_init()` `mbedtls_md_setup()` `mbedtls_md_starts()` `mbedtls_md_update()` `mbedtls_md_update()` `mbedtls_md_finish()` `mbedtls_md_free()`
|
||||
@ -1,206 +0,0 @@
|
||||
Dependencies of the X.509 library on the Crypto library
|
||||
=======================================================
|
||||
|
||||
This document is part of the technical study on how to port Mbed TLS to PSA
|
||||
Crypto. It describes the dependencies of libmbedx509.a on libmbedcrypto.a.
|
||||
|
||||
More precisely, it describes what functions from libmbedcrypto.a are called
|
||||
from libmbedx509.a - other forms of dependencies such as using static inline
|
||||
functions or types, accessing private struct members, etc., are not listed.
|
||||
|
||||
It is based on Mbed TLS 3.0, excluding support for restartble ECP operations.
|
||||
|
||||
Non-Crypto dependencies
|
||||
-----------------------
|
||||
|
||||
The X.509 library has a number of dependencies on libmbedcrypto.a that are not
|
||||
cryptographic, hence are unlikely to be covered by the PSA Crypto API.
|
||||
|
||||
These involve the following modules:
|
||||
|
||||
- asn1
|
||||
- oid
|
||||
- pem
|
||||
- platform
|
||||
- threading
|
||||
|
||||
Crypto dependencies (high-level)
|
||||
--------------------------------
|
||||
|
||||
The X.509 library depends on the following cryptographic modules:
|
||||
|
||||
- pk
|
||||
- md
|
||||
- mpi
|
||||
- sha1
|
||||
|
||||
More specifically, calls are made to the following API functions:
|
||||
|
||||
```
|
||||
mbedtls_pk_can_do
|
||||
mbedtls_pk_free
|
||||
mbedtls_pk_get_bitlen
|
||||
mbedtls_pk_get_name
|
||||
mbedtls_pk_get_type
|
||||
mbedtls_pk_load_file
|
||||
mbedtls_pk_parse_subpubkey
|
||||
mbedtls_pk_sign
|
||||
mbedtls_pk_verify_ext
|
||||
mbedtls_pk_write_pubkey
|
||||
mbedtls_pk_write_pubkey_der
|
||||
|
||||
mbedtls_md
|
||||
mbedtls_md_get_name
|
||||
mbedtls_md_get_size
|
||||
mbedtls_md_info_from_type
|
||||
|
||||
mbedtls_mpi_copy
|
||||
mbedtls_mpi_free
|
||||
mbedtls_mpi_init
|
||||
|
||||
mbedtls_sha1
|
||||
```
|
||||
|
||||
Note: the dependency on MPI is because the certificate's serial number is
|
||||
stored as an MPI in `struct mbedtls_x509write_cert` - the MPI is used purely
|
||||
as a container for bytes. The depencency is embedded in the public API as
|
||||
`mbedtls_x509write_crt_set_serial` take an argument of type `mbedtls_mpi *`.
|
||||
|
||||
Note: the direct dependency on SHA1 is in `x509write_crt.c` and makes sense
|
||||
because it's the only hash that can be used to compute key identifiers for the
|
||||
Subject Key Identifier and Authority Key Identifier extensions. Replacing that
|
||||
with an algorithm-agnistic API would or course be easy.
|
||||
|
||||
File by file analysis
|
||||
---------------------
|
||||
|
||||
The X.509 library consists of the following C files and associated headers:
|
||||
```
|
||||
x509.c
|
||||
x509_create.c
|
||||
x509_crl.c
|
||||
x509_crt.c
|
||||
x509_csr.c
|
||||
x509write_crt.c
|
||||
x509write_csr.c
|
||||
```
|
||||
|
||||
### `x509.c`
|
||||
|
||||
- In `mbedtls_x509_sig_alg_gets()`
|
||||
call `mbedtls_md_info_from_type()` and `mbedtls_md_get_name()`
|
||||
to print out information
|
||||
|
||||
### `x509_crl.c`
|
||||
|
||||
- In `mbedtls_x509_crl_parse_file()`
|
||||
call `mbedtls_pk_load_file()`
|
||||
to load files if `MBEDTLS_FS_IO` defined
|
||||
|
||||
### `x509_crt.c`
|
||||
|
||||
**Note:** All calls to PK APIs in this file use public (not private) keys.
|
||||
|
||||
- In `x509_profile_check_key()`
|
||||
call `mbedtls_pk_get_type()` and `mbedtls_pk_get_bitlen()`
|
||||
|
||||
- In `x509_profile_check_key()`
|
||||
call `mbedtls_pk_ec()`
|
||||
to get the group id
|
||||
|
||||
- In `x509_crt_parse_der_core()`
|
||||
call `mbedtls_pk_parse_subpubkey()`
|
||||
|
||||
- In `mbedtls_x509_crt_parse_file()`
|
||||
call `mbedtls_pk_load_file()`
|
||||
to load files if `MBEDTLS_FS_IO` defined
|
||||
|
||||
- In `mbedtls_x509_crt_info()`
|
||||
call `mbedtls_pk_get_name()` and `mbedtls_pk_get_bitlen()`
|
||||
to print out information
|
||||
|
||||
- In `x509_crt_verifycrl()`
|
||||
call `mbedtls_md_info_from_type()`, `mbedtls_md()`, `mbedtls_pk_verify_ext()` and `mbedtls_md_get_size()`
|
||||
to verify CRL signature
|
||||
|
||||
- In `x509_crt_check_signature()`
|
||||
call `mbedtls_md_info_from_type()`, `mbedtls_md_get_size()`, `mbedtls_md()`, then `mbedtls_pk_can_do()` and `mbedtls_pk_verify_ext()`
|
||||
to verify certificate signature
|
||||
|
||||
- In `x509_crt_verify_restartable_ca_cb()`
|
||||
call `mbedtls_pk_get_type()`
|
||||
to check against profile
|
||||
|
||||
- In `mbedtls_x509_crt_free()`
|
||||
call `mbedtls_pk_free()`
|
||||
|
||||
### `x509_csr.c`
|
||||
|
||||
**Note:** All calls to PK APIs in this file use public (not private) keys.
|
||||
|
||||
- In `mbedtls_x509_csr_parse_der()`
|
||||
call `mbedtls_pk_parse_subpubkey()`
|
||||
|
||||
- In `mbedtls_x509_csr_parse_file()`
|
||||
call `mbedtls_pk_load_file()`
|
||||
to load files if `MBEDTLS_FS_IO` defined
|
||||
|
||||
- In `mbedtls_x509_csr_info()`
|
||||
call `mbedtls_pk_get_name()` and `mbedtls_pk_get_bitlen()`
|
||||
to print out information
|
||||
|
||||
- In `mbedtls_x509_csr_free()`
|
||||
call `mbedtls_pk_free()`
|
||||
|
||||
### `x509_create.c`
|
||||
|
||||
No call to crypto functions - mostly ASN.1 writing and data conversion.
|
||||
|
||||
### `x509write_crt.c`
|
||||
|
||||
**Note:** Calls to PK APIs in this file are both on public and private keys.
|
||||
|
||||
- In `mbedtls_x509write_crt_init()`, resp. `mbedtls_x509write_crt_free()`
|
||||
call `mbedtls_mpi_init()`, resp. `mbedtls_mpi_free()`
|
||||
to manage the serial number
|
||||
|
||||
- In `mbedtls_x509write_crt_set_serial()`
|
||||
call `mbedtls_mpi_copy()`
|
||||
|
||||
- In `mbedtls_x509write_crt_set_subject_key_identifier()` and `mbedtls_x509write_crt_set_authority_key_identifier()`
|
||||
call `mbedtls_pk_write_pubkey()` and `mbedtls_sha1_ret()`
|
||||
|
||||
- In `mbedtls_x509write_crt_der()`
|
||||
call `mbedtls_pk_can_do()`
|
||||
on a private key (issuer)
|
||||
to write out correct signature algorithm
|
||||
|
||||
- In `mbedtls_x509write_crt_der()`
|
||||
call `mbedtls_pk_write_pubkey_der()`
|
||||
on a public key (subject)
|
||||
|
||||
- In `mbedtls_x509write_crt_der()`
|
||||
call `mbedtls_md_info_from_type()` and `mbedtls_md()`
|
||||
to prepare for signing
|
||||
|
||||
- In `mbedtls_x509write_crt_der()`
|
||||
call `mbedtls_pk_sign()`
|
||||
on a private key (issuer)
|
||||
to sign certificate being issued
|
||||
|
||||
### `x509write_csr.c`
|
||||
|
||||
**Note:** All calls for PK APIs in this file are on private (not public) keys
|
||||
|
||||
- In `mbedtls_x509write_csr_der()`
|
||||
call `mbedtls_pk_write_pubkey_der()`
|
||||
|
||||
- In `mbedtls_x509write_csr_der()`
|
||||
call `mbedtls_md_info_from_type()` and `mbedtls_md()`
|
||||
|
||||
- In `mbedtls_x509write_csr_der()`
|
||||
call `mbedtls_pk_sign()`
|
||||
|
||||
- Call `mbedtls_pk_can_do()`
|
||||
on a private key (writer's)
|
||||
to write out correct signature algorithm
|
||||
@ -1,114 +0,0 @@
|
||||
This document is temporary; it lists tasks to achieve G1 as described in
|
||||
`strategy.md` while the strategy is being reviewed - once that's done,
|
||||
corresponding github issues will be created and this document removed.
|
||||
|
||||
For all of the tasks here, no specific testing is expected to be required,
|
||||
beyond passing the existing tests in a build with `MBEDTLS_USE_PSA_ENABLED`,
|
||||
see `testing.md`.
|
||||
|
||||
Symmetric crypto
|
||||
================
|
||||
|
||||
Hashes
|
||||
------
|
||||
|
||||
### Use `psa_hash` in all of X.509
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5157
|
||||
|
||||
HMAC
|
||||
----
|
||||
|
||||
### Variable-time HMAC in TLS record protection
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5177
|
||||
|
||||
### Constant-time HMAC in TLS record protection
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5178
|
||||
|
||||
|
||||
Ciphers
|
||||
-------
|
||||
|
||||
### Use PSA for all cipher operations in TLS
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5181
|
||||
https://github.com/ARMmbed/mbedtls/issues/5182
|
||||
https://github.com/ARMmbed/mbedtls/issues/5203
|
||||
https://github.com/ARMmbed/mbedtls/issues/5204
|
||||
https://github.com/ARMmbed/mbedtls/issues/5205
|
||||
https://github.com/ARMmbed/mbedtls/issues/5206
|
||||
|
||||
Asymmetric crypto
|
||||
=================
|
||||
|
||||
ECDSA
|
||||
-----
|
||||
|
||||
### Make `mbedtls_pk_sign()` use PSA for ECDSA operations
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5274
|
||||
|
||||
RSA signature (and verification)
|
||||
--------------------------------
|
||||
|
||||
### Make `mbedtls_pk_sign()` use PSA for RSA operations
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5162
|
||||
|
||||
### Make `mbedtls_pk_verify()` use PSA for RSA operations
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5159
|
||||
|
||||
### Make `mbedtls_pk_verify_ext()` use PSA for RSA operations
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5333 (partial)
|
||||
https://github.com/ARMmbed/mbedtls/issues/5277 (futher)
|
||||
|
||||
RSA en/decryption
|
||||
-----------------
|
||||
|
||||
### Make `mbedtls_pk_encrypt()` use PSA for RSA operations
|
||||
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5161
|
||||
|
||||
### Make `mbedtls_pk_decrypt()` use PSA for RSA operations
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5160
|
||||
|
||||
ECDH
|
||||
----
|
||||
|
||||
Additional:
|
||||
https://github.com/ARMmbed/mbedtls/issues/5291 (pre clean-up)
|
||||
https://github.com/ARMmbed/mbedtls/issues/5321 (TLS 1.3)
|
||||
https://github.com/ARMmbed/mbedtls/issues/5322 (post clean-up)
|
||||
|
||||
### Write remaining utilities for ECDH parsing/writing
|
||||
|
||||
(not a task on its own, part of other tasks)
|
||||
|
||||
### Use PSA for ECDHE in ECDHE-ECDSA and ECDHE-RSA server-side
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5317
|
||||
|
||||
### Use PSA for ECDH in ECDHE-PSK (all sides and versions)
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5318
|
||||
|
||||
### Use PSA for ECDH in static-ECDH key exchanges
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5319
|
||||
https://github.com/ARMmbed/mbedtls/issues/5320
|
||||
|
||||
FFDH
|
||||
----
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5287
|
||||
|
||||
EC J-PAKE
|
||||
---------
|
||||
|
||||
https://github.com/ARMmbed/mbedtls/issues/5275
|
||||
Loading…
x
Reference in New Issue
Block a user