From 335cbf61daba7f49c22cf1e7d9556ae111e07799 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 1 Feb 2022 09:55:45 +0100 Subject: [PATCH] Remove temporary documents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../psa-migration/dependencies-tls.md | 563 ------------------ .../psa-migration/dependencies-x509.md | 206 ------- docs/architecture/psa-migration/tasks-g1.md | 114 ---- 3 files changed, 883 deletions(-) delete mode 100644 docs/architecture/psa-migration/dependencies-tls.md delete mode 100644 docs/architecture/psa-migration/dependencies-x509.md delete mode 100644 docs/architecture/psa-migration/tasks-g1.md diff --git a/docs/architecture/psa-migration/dependencies-tls.md b/docs/architecture/psa-migration/dependencies-tls.md deleted file mode 100644 index 74f78d57b0..0000000000 --- a/docs/architecture/psa-migration/dependencies-tls.md +++ /dev/null @@ -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()` diff --git a/docs/architecture/psa-migration/dependencies-x509.md b/docs/architecture/psa-migration/dependencies-x509.md deleted file mode 100644 index dfbff8304a..0000000000 --- a/docs/architecture/psa-migration/dependencies-x509.md +++ /dev/null @@ -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 diff --git a/docs/architecture/psa-migration/tasks-g1.md b/docs/architecture/psa-migration/tasks-g1.md deleted file mode 100644 index d906bf9ea5..0000000000 --- a/docs/architecture/psa-migration/tasks-g1.md +++ /dev/null @@ -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