mbedtls/docs/architecture/psa-migration/dependencies-x509.md

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