From 948137be5923961acd6726f275d4e9bb3ddfbbfe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 10 Aug 2023 16:58:04 +0200 Subject: [PATCH 01/13] Add details on use of ciphers from other modules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 50 +++++++++++++------ 1 file changed, 36 insertions(+), 14 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 355f5618d..ba76f494b 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -110,23 +110,45 @@ For the purposes of this work, three domains emerge: #### Non-use-PSA modules -The following modules in Mbed TLS call another module to perform cryptographic operations which, in the long term, will be provided through a PSA interface, but cannot make any PSA-related assumption: +The following modules in Mbed TLS call another module to perform cryptographic operations which, in the long term, will be provided through a PSA interface, but cannot make any PSA-related assumption. -* CCM (block cipher in ECB mode; interdependent with cipher) -* cipher (cipher and AEAD algorithms) -* CMAC (AES-ECB and DES-ECB, but could be extended to the other block ciphers; interdependent with cipher) -* CTR\_DRBG (AES-ECB, but could be extended to the other block ciphers) -* entropy (hashes via low-level) +Hashes and HMAC (after the work on MD-light): + +* entropy (hashes via MD-light) * ECDSA (HMAC\_DRBG; `md.h` exposed through API) -* ECJPAKE (hashes via md; `md.h` exposed through API) -* GCM (block cipher in ECB mode; interdependent with cipher) -* md (hashes and HMAC) -* NIST\_KW (AES-ECB; interdependent with cipher) +* ECJPAKE (hashes via MD-light; `md.h` exposed through API) +* MD (hashes and HMAC) * HMAC\_DRBG (hashes and HMAC via `md.h`; `md.h` exposed through API) -* PEM (AES and DES in CBC mode without padding; MD5 hash via low-level) -* PKCS12 (cipher, generically, selected from ASN.1 or function parameters; hashes via md; `cipher.h` exposed through API) -* PKCS5 (cipher, generically, selected from ASN.1; HMAC via `md.h`; `md.h` exposed through API) -* RSA (hash via md for PSS and OAEP; `md.h` exposed through API) +* PKCS12 (hashes via MD-light) +* PKCS5 (HMAC via `md.h`; `md.h` exposed through API) +* RSA (hash via MD-light for PSS and OAEP; `md.h` exposed through API) +* PEM (MD5 hash via MD-light) + +Symmetric ciphers and AEADs (before Cipher-light work): + +* PEM (AES and DES in CBC mode without padding) + AES and DES: setkey_dec + crypt_cbc + (look at test data for DES) +* PKCS12 (cipher, generically, selected from ASN.1 or function parameters; `cipher.h` exposed through API) + setup, setkey, set_iv, reset, update, finish (in sequence, once) + no documented restriction, block cipher in CBC mode in practice + (padding?) + (look at test cases) +* PKCS5 (cipher, generically, selected from ASN.1) + only DES-CBC or 3DES-CBC + (padding?) + setup, setkey, crypt +* CTR\_DRBG (AES-ECB, but could be extended to the other block ciphers) + setkey_enc + crypt_ecb +* CCM (block cipher in ECB mode; interdependent with cipher) + info, setup, setkey, update (several times), (never finish) +* CMAC (AES-ECB and DES-ECB, but could be extended to the other block ciphers; interdependent with cipher) + info, setup, setkey, update (several times), (never finish) +* GCM (block cipher in ECB mode; interdependent with cipher) + info, setup, setkey, update (several times), (never finish) +* NIST\_KW (AES-ECB; interdependent with cipher) + info, setup, setkey, update (several times), (never finish) +* cipher (cipher and AEAD algorithms) ### Difficulties From 36cd3f9f8ef6edbf9c7ba16a442117ddfa506748 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 11 Aug 2023 10:06:42 +0200 Subject: [PATCH 02/13] Add tentative definition of Cipher light MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index ba76f494b..488cf20db 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -499,3 +499,54 @@ The architecture can be extended to support `MBEDTLS_PSA_CRYPTO_CLIENT` with a l * Compile-time dependencies: instead of checking `defined(MBEDTLS_PSA_CRYPTO_C)`, check `defined(MBEDTLS_PSA_CRYPTO_C) || defined(MBEDTLS_PSA_CRYPTO_CLIENT)`. * Implementers of `MBEDTLS_PSA_CRYPTO_CLIENT` will need to provide `psa_can_do_hash()` (or a more general function `psa_can_do`) alongside `psa_crypto_init()`. Note that at this point, it will become a public interface, hence we won't be able to change it at a whim. + +### Cipher light + +#### Definition + +**Note:** this definition is tentative an may be refined when implementing and +testing, based and what's needed by internal users of Cipher light. + +Cipher light will be automatically enabled in `build_info.h` by modules that +need it. (Tentative list: PEM, PCKS12, PKCS5, CTR\_DRBG, CCM, CMAC, GCM, +NIS\_KW, PSA Crypto.) Note: some of these modules currently depend on the +full `CIPHER_C` (enforced by `check_config.h`); this hard dependency would be +replace by the above auto-enablement. + +Cipher light includes: +- info functions; +- support for block ciphers in ECB mode (to be confirmed: supporting one block + at a time could be enough); +- support for block ciphers in CBC mode with no padding (to be confirmed: do + we need a padding mode?); +- support for both the "one-shot" and "streaming" APIs for block ciphers. + +This excludes: +- the AEAD/KW API (both one-shot and streaming); +- support for stream ciphers; +- support for other modes of block ciphers (CTR, CFB, etc.); +- support for (other) padding modes of CBC. + +The following API functions, and supporting types, are candidates for +inclusion in the Cipher light API, with limited features as above: +``` +mbedtls_cipher_info_from_psa +mbedtls_cipher_info_from_type +mbedtls_cipher_info_from_values + +mbedtls_cipher_info_get_block_size +mbedtls_cipher_info_get_iv_size +mbedtls_cipher_info_get_key_bitlen + +mbedtls_cipher_init +mbedtls_cipher_setup +mbedtls_cipher_setkey +mbedtls_cipher_set_padding_mode +mbedtls_cipher_crypt +mbedtls_cipher_free + +mbedtls_cipher_set_iv +mbedtls_cipher_reset +mbedtls_cipher_update +mbedtls_cipher_finish +``` From 839d3580bd9eb1bba89887c515837a871c0078aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 15 Sep 2023 21:27:19 +0200 Subject: [PATCH 03/13] Update details of modules using cipher operations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 82 +++++++++++++------ 1 file changed, 57 insertions(+), 25 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 488cf20db..6bd0694c4 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -112,7 +112,7 @@ For the purposes of this work, three domains emerge: The following modules in Mbed TLS call another module to perform cryptographic operations which, in the long term, will be provided through a PSA interface, but cannot make any PSA-related assumption. -Hashes and HMAC (after the work on MD-light): +Hashes and HMAC (after the work on driver-only hashes): * entropy (hashes via MD-light) * ECDSA (HMAC\_DRBG; `md.h` exposed through API) @@ -124,31 +124,63 @@ Hashes and HMAC (after the work on MD-light): * RSA (hash via MD-light for PSS and OAEP; `md.h` exposed through API) * PEM (MD5 hash via MD-light) -Symmetric ciphers and AEADs (before Cipher-light work): +Symmetric ciphers and AEADs (before work on driver-only cipher): -* PEM (AES and DES in CBC mode without padding) - AES and DES: setkey_dec + crypt_cbc - (look at test data for DES) -* PKCS12 (cipher, generically, selected from ASN.1 or function parameters; `cipher.h` exposed through API) - setup, setkey, set_iv, reset, update, finish (in sequence, once) - no documented restriction, block cipher in CBC mode in practice - (padding?) - (look at test cases) -* PKCS5 (cipher, generically, selected from ASN.1) - only DES-CBC or 3DES-CBC - (padding?) - setup, setkey, crypt -* CTR\_DRBG (AES-ECB, but could be extended to the other block ciphers) - setkey_enc + crypt_ecb -* CCM (block cipher in ECB mode; interdependent with cipher) - info, setup, setkey, update (several times), (never finish) -* CMAC (AES-ECB and DES-ECB, but could be extended to the other block ciphers; interdependent with cipher) - info, setup, setkey, update (several times), (never finish) -* GCM (block cipher in ECB mode; interdependent with cipher) - info, setup, setkey, update (several times), (never finish) -* NIST\_KW (AES-ECB; interdependent with cipher) - info, setup, setkey, update (several times), (never finish) -* cipher (cipher and AEAD algorithms) +* PEM: + * AES, DES or 3DES in CBC mode without padding, decrypt only (!). + * Currently using low-level non-generic APIs. + * No hard dependency, features guarded by `AES_C` resp. `DES_C`. + * Functions called: `setkey_dec()` + `crypt_cbc()`. +* PKCS12: + * In practice: 2DES or 3DES in CBC mode with PKCS7 padding, decrypt only + (when called from pkparse). + * In principle: any cipher-mode (default padding), passed an + `mbedtls_cipher_type_t` as an argument, no documented restriction. + * Cipher, generically, selected from ASN.1 or function parameters; + no documented restriction but in practice TODO (inc. padding and + en/decrypt, look at standards and tests) + * Unconditional dependency on `CIPHER_C` in `check_config.h`. + * Note: `cipher.h` exposed through API. + * Functions called: `setup`, `setkey`, `set_iv`, `reset`, `update`, `finish` (in sequence, once). +* PKCS5 (PBES2, `mbedtls_pkcs5_pbes2()`): + * 3DES or DES in CBC mode with PKCS7 padding, both encrypt and decrypt. + * Note: could also be AES in the future, see #7038. + * Unconditional dependency on `CIPHER_C` in `check_config.h`. + * Functions called: `setup`, `setkey`, `crypt`. +* CTR\_DRBG: + * AES in ECB mode, encrypt only. + * Currently using low-level non-generic API (`aes.h`). + * Unconditional dependency on `AES_C` in `check_config.h`. + * Functions called: `setkey_enc`, `crypt_ecb`. +* CCM: + * AES, Camellia or Aria in ECB mode, encrypt only. + * Unconditional dependency on `AES_C || CAMELLIA_C || ARIA_C` in `check_config.h`. + * Unconditional dependency on `CIPHER_C` in `check_config.h`. + * Note: also called by `cipher.c` if enabled. + * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish) +* CMAC: + * AES or DES in ECB mode, encrypt only. + * Unconditional dependency on `AES_C || DES_C` in `check_config.h`. + * Unconditional dependency on `CIPHER_C` in `check_config.h`. + * Note: also called by `cipher.c` if enabled. + * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish) +* GCM: + * AES, Camellia or Aria in ECB mode, encrypt only. + * Unconditional dependency on `AES_C || CAMELLIA_C || ARIA_C` in `check_config.h`. + * Unconditional dependency on `CIPHER_C` in `check_config.h`. + * Note: also called by `cipher.c` if enabled. + * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish) +* NIST\_KW: + * AES in ECB mode, both encryt and decrypt. + * Unconditional dependency on `AES_C || DES_C` in `check_config.h`. + * Unconditional dependency on `CIPHER_C` in `check_config.h`. + * Note: also called by `cipher.c` if enabled. + * Note: `cipher.h` exposed through API. + * Functions called: `info`, `setup`, `setkey`, `update` (several times) - (never finish) +* Cipher: + * potentially any cipher/AEAD in any mode and any direction + +Note: PSA cipher is built on Cipher, but PSA AEAD directly calls the underlying AEAD modules (GCM, CCM, ChachaPoly). ### Difficulties From ca18b7747e7738788df26c06c581e9c0f7c6a92a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 10 Oct 2023 09:45:28 +0200 Subject: [PATCH 04/13] Update definition of Cipher light MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 45 ++++++++++--------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 6bd0694c4..3feda1115 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -537,48 +537,51 @@ The architecture can be extended to support `MBEDTLS_PSA_CRYPTO_CLIENT` with a l #### Definition **Note:** this definition is tentative an may be refined when implementing and -testing, based and what's needed by internal users of Cipher light. +testing, based and what's needed by internal users of Cipher light. The new +config symbol will not be considered public so its definition may change. Cipher light will be automatically enabled in `build_info.h` by modules that -need it. (Tentative list: PEM, PCKS12, PKCS5, CTR\_DRBG, CCM, CMAC, GCM, -NIS\_KW, PSA Crypto.) Note: some of these modules currently depend on the -full `CIPHER_C` (enforced by `check_config.h`); this hard dependency would be -replace by the above auto-enablement. +need it, namely: CTR\_DRBG, CCM, GCM. Note: CCM and GCM currently depend on +the full `CIPHER_C` (enforced by `check_config.h`); this hard dependency would +be replaced by the above auto-enablement. Cipher light includes: - info functions; -- support for block ciphers in ECB mode (to be confirmed: supporting one block - at a time could be enough); -- support for block ciphers in CBC mode with no padding (to be confirmed: do - we need a padding mode?); -- support for both the "one-shot" and "streaming" APIs for block ciphers. +- support for block ciphers in ECB mode, encrypt only (note: in Cipher, "ECB" + means just one block, contrary to PSA); +- the one-shot API as well as (part of) the streaming API; +- only AES, Aria and Camellia. This excludes: - the AEAD/KW API (both one-shot and streaming); - support for stream ciphers; -- support for other modes of block ciphers (CTR, CFB, etc.); -- support for (other) padding modes of CBC. +- support for other modes of block ciphers (CBC, CTR, CFB, etc.); +- DES and variants (3DES). The following API functions, and supporting types, are candidates for inclusion in the Cipher light API, with limited features as above: ``` -mbedtls_cipher_info_from_psa mbedtls_cipher_info_from_type -mbedtls_cipher_info_from_values - mbedtls_cipher_info_get_block_size -mbedtls_cipher_info_get_iv_size -mbedtls_cipher_info_get_key_bitlen mbedtls_cipher_init mbedtls_cipher_setup mbedtls_cipher_setkey -mbedtls_cipher_set_padding_mode mbedtls_cipher_crypt mbedtls_cipher_free -mbedtls_cipher_set_iv -mbedtls_cipher_reset mbedtls_cipher_update -mbedtls_cipher_finish +(mbedtls_cipher_finish) ``` + +Note: `mbedtls_cipher_info_get_block_size()` can be hard-coded to return 16, +as all three supported block ciphers have the same block size (DES was +excluded). + +Note: `mbedtls_cipher_finish()` is not required by any of the modules using +Cipher light, but it might be convenient to include it anyway as it's used in +the implementation of `mbedtls_cipher_crypt()`. + +#### Cipher light dual dispatch + +This is likely to come in the future, but has not been defined yet. From 2daee0410e725ef5ef5beb34d80ac35bbd88ac79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 10 Oct 2023 09:55:03 +0200 Subject: [PATCH 05/13] Update list of modules using hashes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/architecture/psa-migration/md-cipher-dispatch.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 3feda1115..76081deef 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -118,9 +118,11 @@ Hashes and HMAC (after the work on driver-only hashes): * ECDSA (HMAC\_DRBG; `md.h` exposed through API) * ECJPAKE (hashes via MD-light; `md.h` exposed through API) * MD (hashes and HMAC) +* HKDF (HMAC via `md.h`; `md.h` exposed through API) * HMAC\_DRBG (hashes and HMAC via `md.h`; `md.h` exposed through API) * PKCS12 (hashes via MD-light) * PKCS5 (HMAC via `md.h`; `md.h` exposed through API) +* PKCS7 (hashes via MD) * RSA (hash via MD-light for PSS and OAEP; `md.h` exposed through API) * PEM (MD5 hash via MD-light) From 301d2a29a72292d4654be1929007e33fe69334ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 10 Oct 2023 10:02:03 +0200 Subject: [PATCH 06/13] Update to MD light section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mostly to reflect this has been implemented, and remove references to temporary remains from the previous strategy (hash_info, legacy_or_psa) which would probably be more confusing than helpful at this point. Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 32 +------------------ 1 file changed, 1 insertion(+), 31 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 76081deef..12b486a46 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -323,8 +323,6 @@ These problems are easily solvable. ### MD light -https://github.com/Mbed-TLS/mbedtls/pull/6474 implements part of this specification, but it's based on Mbed TLS 3.2, so it needs to be rewritten for 3.3. - #### Definition of MD light MD light is a subset of `md.h` that implements the hash calculation interface described in ”[Designing an interface for hashes](#designing-an-interface-for-hashes)”. It is activated by `MBEDTLS_MD_LIGHT` in `mbedtls_config.h`. @@ -454,31 +452,7 @@ Note that this assumes that an operation that has been started via PSA can be co #### Error code conversion -After calling a PSA function, call `mbedtls_md_error_from_psa` to convert its status code. This function is currently defined in `hash_info.c`. - -### Migration to MD light - -#### Migration of modules that used to call MD and now do the legacy-or-PSA dance - -Get rid of the case where `MBEDTLS_MD_C` is undefined. Enable `MBEDTLS_MD_LIGHT` in `build_info.h`. - -#### Migration of modules that used to call a low-level hash module and now do the legacy-or-PSA dance - -Switch to calling MD (light) unconditionally. Enable `MBEDTLS_MD_LIGHT` in `build_info.h`. - -#### Migration of modules that call a low-level hash module - -Switch to calling MD (light). Enable `MBEDTLS_MD_LIGHT` in `build_info.h`. - -#### Migration of use-PSA mixed code - -Instead of calling `hash_info.h` functions to obtain metadata, get it from `md.h`. - -Optionally, code that currently tests on `MBEDTLS_USE_PSA_CRYPTO` just to determine whether to call MD or PSA to calculate hashes can switch to just having the MD variant. - -#### Remove `legacy_or_psa.h` - -It's no longer used. +After calling a PSA function, call `mbedtls_md_error_from_psa` to convert its status code. ### Support all legacy algorithms in PSA @@ -517,10 +491,6 @@ static inline psa_algorithm_t psa_alg_of_md_info( Work in progress on this conversion is at https://github.com/gilles-peskine-arm/mbedtls/tree/hash-unify-ids-wip-1 -#### Get rid of the hash_info module - -The hash_info module is redundant with MD light. Move `mbedtls_md_error_from_psa` to `md.c`, defined only when `MBEDTLS_MD_SOME_PSA` is defined. The rest is no longer used. - #### Unify HMAC with PSA PSA has its own HMAC implementation. In builds with both `MBEDTLS_MD_C` and `PSA_WANT_ALG_HMAC` not fully provided by drivers, we should have a single implementation. Replace the one in `md.h` by calls to the PSA driver interface. This will also give mixed-domain modules access to HMAC accelerated directly by a PSA driver (eliminating the need to a HMAC interface in software if all supported hashes have an accelerator that includes HMAC support). From f1878d89741ed968b55c2a10ce5d996073bd74bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 12 Oct 2023 11:19:00 +0200 Subject: [PATCH 07/13] Update to only serve GCM and CCM MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 12b486a46..11c5f21fb 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -513,9 +513,9 @@ testing, based and what's needed by internal users of Cipher light. The new config symbol will not be considered public so its definition may change. Cipher light will be automatically enabled in `build_info.h` by modules that -need it, namely: CTR\_DRBG, CCM, GCM. Note: CCM and GCM currently depend on -the full `CIPHER_C` (enforced by `check_config.h`); this hard dependency would -be replaced by the above auto-enablement. +need it, namely: CCM, GCM. Note: CCM and GCM currently depend on the full +`CIPHER_C` (enforced by `check_config.h`); this hard dependency would be +replaced by the above auto-enablement. Cipher light includes: - info functions; @@ -533,27 +533,21 @@ This excludes: The following API functions, and supporting types, are candidates for inclusion in the Cipher light API, with limited features as above: ``` -mbedtls_cipher_info_from_type +mbedtls_cipher_info_from_values mbedtls_cipher_info_get_block_size mbedtls_cipher_init mbedtls_cipher_setup mbedtls_cipher_setkey -mbedtls_cipher_crypt mbedtls_cipher_free mbedtls_cipher_update -(mbedtls_cipher_finish) ``` Note: `mbedtls_cipher_info_get_block_size()` can be hard-coded to return 16, as all three supported block ciphers have the same block size (DES was excluded). -Note: `mbedtls_cipher_finish()` is not required by any of the modules using -Cipher light, but it might be convenient to include it anyway as it's used in -the implementation of `mbedtls_cipher_crypt()`. - #### Cipher light dual dispatch This is likely to come in the future, but has not been defined yet. From 3bcda449c08aea258029b2542e0e86dc745172c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 26 Oct 2023 10:03:49 +0200 Subject: [PATCH 08/13] Things forgotten in the previous commit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/architecture/psa-migration/md-cipher-dispatch.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index 11c5f21fb..ca98a5107 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -518,13 +518,14 @@ need it, namely: CCM, GCM. Note: CCM and GCM currently depend on the full replaced by the above auto-enablement. Cipher light includes: -- info functions; +- some info functions; - support for block ciphers in ECB mode, encrypt only (note: in Cipher, "ECB" means just one block, contrary to PSA); -- the one-shot API as well as (part of) the streaming API; +- part of the streaming API for unauthenticated ciphers; - only AES, Aria and Camellia. This excludes: +- the one-shot API for unauthenticated ciphers; - the AEAD/KW API (both one-shot and streaming); - support for stream ciphers; - support for other modes of block ciphers (CBC, CTR, CFB, etc.); From 6b3643117b404767c246f019bc0d977c2bff220a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 26 Oct 2023 11:02:17 +0200 Subject: [PATCH 09/13] Document chosen goals and priorities for 3.x MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 33 +++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index ca98a5107..d75a4dcd4 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -99,8 +99,8 @@ We can classify code that implements or uses cryptographic mechanisms into sever * Software implementations of primitive cryptographic mechanisms. These are not expected to change. * Software implementations of constructed cryptographic mechanisms (e.g. HMAC, CTR_DRBG, RSA (calling a hash for PSS/OAEP, and needing to know the hash length in PKCS1v1.5 sign/verify), …). These need to keep working whenever a legacy implementation of the auxiliary mechanism is available, regardless of whether a PSA implementation is also available. * Code implementing the PSA crypto interface. This is not expected to change, except perhaps to expose some internal functionality to overhauled glue code. -* Code that's subject to `MBEDTLS_USE_PSA_CRYPTO`: `pk.h`, X.509, TLS (excluding TLS 1.3). -* Code that always uses PSA for crypto: TLS 1.3, LMS. +* Code that's subject to `MBEDTLS_USE_PSA_CRYPTO`: `pk.h`, X.509, TLS (excluding parts specific TLS 1.3). +* Code that always uses PSA for crypto: TLS 1.3 (except things common with 1.2), LMS. For the purposes of this work, three domains emerge: @@ -319,6 +319,35 @@ These problems are easily solvable. * We can make names and HMAC optional. The mixed-domain hash interface won't be the full `MBEDTLS_MD_C` but a subset. * We can optimize `md.c` without making API changes to `md.h`. +### Scope reductions and priorities for 3.x + +This section documents things that we chose to temporarily exclude from the scope in the 3.x branch (which will eventually be in scope again after 4.0) as well as things we chose to prioritize if we don't have time to support everything. + +#### Don't support PK, X.509 and TLS without `MBEDTLS_USE_PSA_CRYPTO` + +We do not need to support driver-only hashes and ciphers in PK. X.509 and TLS without `MBEDTLS_USE_PSA_CRYPTO`. Users who want to take full advantage of drivers will need to enabled this macro. + +Note that this applies to TLS 1.3 as well, as some uses of hashes and all uses of ciphers there are common with TLS 1.2, hence governed by `MBEDTLS_USE_PSA_CRYPTO`, see [this macro's extended documentation](../../docs/use-psa-crypto.html). + +This will go away naturally in 4.0 when this macros is not longer an option (because it's always on). + +#### Don't support for `MBEDTLS_PSA_CRYPTO_CLIENT` without `MBEDTLS_PSA_CRYPTO_C` + +We generally don't really support builds with `MBEDTLS_PSA_CRYPTO_CLIENT` without `MBEDTLS_PSA_CRYPTO_C`. For example, both `MBEDTLS_USE_PSA_CRYPTO` and `MBEDTLS_SSL_PROTO_TLS1_3` require `MBEDTLS_PSA_CRYPTO_C`, while in principle they should only require `MBEDTLS_PSA_CRYPTO_CLIENT`. + +Considering this existing restriction which we do not plan to lift before 4.0, it is acceptable driver-only hashes and cipher support to have the same restriction in 3.x. + +It is however desirable for the design to keep support for `MBEDTLS_PSA_CRYPTO_CLIENT` in mind, in order to avoid making it more difficult to add in the future. + +#### For cipher: prioritize constrained devices and modern TLS + +The primary target is a configuration like TF-M's medium profile, plus TLS with only AEAD ciphersuites. + +This excludes things like: +- Support for encrypted PEM, PKCS5 and PKCS12 encryption, and PKCS8 encrypted keys in PK parse. (Not widely used on highly constrained devices.) +- Support for NIST-KW. (Same justification.) +- Support for CBC ciphersuites in TLS. (They've been recommended against for a while now.) + ## Specification ### MD light From 4823d2c94e021994671fcb0f9208c1338253f782 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 26 Oct 2023 12:56:39 +0200 Subject: [PATCH 10/13] Extend design discussion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index d75a4dcd4..a4c8fccf0 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -346,8 +346,39 @@ The primary target is a configuration like TF-M's medium profile, plus TLS with This excludes things like: - Support for encrypted PEM, PKCS5 and PKCS12 encryption, and PKCS8 encrypted keys in PK parse. (Not widely used on highly constrained devices.) - Support for NIST-KW. (Same justification.) +- Support for CMAC. (Same justification, plus can be directly accelerated.) - Support for CBC ciphersuites in TLS. (They've been recommended against for a while now.) +### Dual-dispatch for block cipher primitives + +Considering the priorities stated above, initially we want to support GCM, CCM and CTR-DRBG. All trhee of them use the block cipher primitive only in the encrypt direction. Currently, GCM and CCM use the Cipher layer in order to work with AES, Aria and Camellia (DES is excluded by the standards due to its smaller block size) and CTR-DRBG directly uses the low-level API from `aes.h`. In all cases, access to the "block cipher primitive" is done by using "ECB mode" (which for both Cipher and `aes.h` only allows a single block, contrary to PSA which implements actual ECB mode). + +The two AEAD modes, GCM and CCM, have very similar needs and positions in the stack, strongly suggesting using the same design for both. On the other hand, there are a number of differences between CTR-DRBG and them. +- CTR-DRBG only uses AES (and there is no plan to extend it to other block ciphers at the moment), while GCM and CCM need to work with 3 block ciphers already. +- CTR-DRBG holds a special position in the stack: most users don't care about it per se, they only care about getting random numbers - in fact PSA users don't even need to know what DRBG is used. In particular, no part of the stack is asking questions like "is CTR-DRBG-AES available?" - an RNG needs to be available and that's it - contrary to similar questions about AES-GCM etc. which are asked for example by TLS. + +So, it makes sense to use different designs for CTR-DRBG on one hand, and GCM/CCM on the other hand: +- CTR-DRBG can just check if `AES_C` is present and "fall back" to PSA is not. +- GCM and CCM need an common abstraction layer that allows: + - Using AES, Aria or Camellia in a uniform way. + - Dispatching to built-in or driver. + +The abstraction layer used by GCM and CCM may either be a new internal module, or a subset of the existing Cipher API, extended with the ability to dispatch to a PSA driver. + +Reasons for making this layer's API a subset of the existing Cipher API: +- No need to design, implement and test a new module. (Will need to test the new subset though, as well as the extended behaviour.) +- No code change in GCM and CCM - only need to update dependencies. +- No risk for code duplication between a potential new module and Cipher: source-level, and in in particular in builds that still have `CIPHER_C` enabled. (Compiled-code duplication could be avoided by excluding the new module in such builds, though.) +- If want to support other users of Cipher later (such as NIST-KW, CMAC, PKCS5 and PKCS12), we can just extend dual-dispatch support to other modes/operations in Cipher and keep those extra modules unchanged as well. + +Possible costs of re-using (a subset of) the existing Cipher API instead of defining a new one: +- We carry over costs associated with `cipher_info_t` structures. (Currently the info structure is used for 3 things: (1) to check if the cipher is supported, (2) to check its block size, (3) because `setup()` requires it). +- We carry over questionable implementation decisions, like dynamic allocation of context. + +Those costs could be avoided by refactoring (parts of) Cipher, but that would probably mean either: +- significant differences in how the `cipher.h` API is implemented between builds with the full Cipher or only a subset; +- or more work to apply the simplifications to all of Cipher. + ## Specification ### MD light From 303121eb1682f3e4e18f2a7d9578c21a53f17f2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 7 Dec 2023 12:05:07 +0100 Subject: [PATCH 11/13] Fix a typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/architecture/psa-migration/md-cipher-dispatch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index a4c8fccf0..f165b21e0 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -351,7 +351,7 @@ This excludes things like: ### Dual-dispatch for block cipher primitives -Considering the priorities stated above, initially we want to support GCM, CCM and CTR-DRBG. All trhee of them use the block cipher primitive only in the encrypt direction. Currently, GCM and CCM use the Cipher layer in order to work with AES, Aria and Camellia (DES is excluded by the standards due to its smaller block size) and CTR-DRBG directly uses the low-level API from `aes.h`. In all cases, access to the "block cipher primitive" is done by using "ECB mode" (which for both Cipher and `aes.h` only allows a single block, contrary to PSA which implements actual ECB mode). +Considering the priorities stated above, initially we want to support GCM, CCM and CTR-DRBG. All three of them use the block cipher primitive only in the encrypt direction. Currently, GCM and CCM use the Cipher layer in order to work with AES, Aria and Camellia (DES is excluded by the standards due to its smaller block size) and CTR-DRBG directly uses the low-level API from `aes.h`. In all cases, access to the "block cipher primitive" is done by using "ECB mode" (which for both Cipher and `aes.h` only allows a single block, contrary to PSA which implements actual ECB mode). The two AEAD modes, GCM and CCM, have very similar needs and positions in the stack, strongly suggesting using the same design for both. On the other hand, there are a number of differences between CTR-DRBG and them. - CTR-DRBG only uses AES (and there is no plan to extend it to other block ciphers at the moment), while GCM and CCM need to work with 3 block ciphers already. From b8c4254f449e263cac03c282f9a9b0124c54151c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 7 Dec 2023 12:12:39 +0100 Subject: [PATCH 12/13] Update cipher light -> block cipher definition MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- .../psa-migration/md-cipher-dispatch.md | 58 +++++++------------ 1 file changed, 21 insertions(+), 37 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index f165b21e0..bc92d00b3 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -379,6 +379,8 @@ Those costs could be avoided by refactoring (parts of) Cipher, but that would pr - significant differences in how the `cipher.h` API is implemented between builds with the full Cipher or only a subset; - or more work to apply the simplifications to all of Cipher. +Prototyping both approaches showed better code size savings and cleaner code with a new internal module. + ## Specification ### MD light @@ -564,50 +566,32 @@ The architecture can be extended to support `MBEDTLS_PSA_CRYPTO_CLIENT` with a l * Compile-time dependencies: instead of checking `defined(MBEDTLS_PSA_CRYPTO_C)`, check `defined(MBEDTLS_PSA_CRYPTO_C) || defined(MBEDTLS_PSA_CRYPTO_CLIENT)`. * Implementers of `MBEDTLS_PSA_CRYPTO_CLIENT` will need to provide `psa_can_do_hash()` (or a more general function `psa_can_do`) alongside `psa_crypto_init()`. Note that at this point, it will become a public interface, hence we won't be able to change it at a whim. -### Cipher light +### Internal "block cipher" abstraction (Cipher light) #### Definition -**Note:** this definition is tentative an may be refined when implementing and -testing, based and what's needed by internal users of Cipher light. The new -config symbol will not be considered public so its definition may change. +The new module is automatically enabled in `build_info.h` by modules that need +it, namely: CCM, GCM, only when `CIPHER_C` is not available. Note: CCM and GCM +currently depend on the full `CIPHER_C` (enforced by `check_config.h`); this +hard dependency would be replaced by the above auto-enablement. -Cipher light will be automatically enabled in `build_info.h` by modules that -need it, namely: CCM, GCM. Note: CCM and GCM currently depend on the full -`CIPHER_C` (enforced by `check_config.h`); this hard dependency would be -replaced by the above auto-enablement. - -Cipher light includes: -- some info functions; -- support for block ciphers in ECB mode, encrypt only (note: in Cipher, "ECB" - means just one block, contrary to PSA); -- part of the streaming API for unauthenticated ciphers; -- only AES, Aria and Camellia. - -This excludes: -- the one-shot API for unauthenticated ciphers; -- the AEAD/KW API (both one-shot and streaming); -- support for stream ciphers; -- support for other modes of block ciphers (CBC, CTR, CFB, etc.); -- DES and variants (3DES). - -The following API functions, and supporting types, are candidates for -inclusion in the Cipher light API, with limited features as above: +The following API functions are offered: ``` -mbedtls_cipher_info_from_values -mbedtls_cipher_info_get_block_size - -mbedtls_cipher_init -mbedtls_cipher_setup -mbedtls_cipher_setkey -mbedtls_cipher_free - -mbedtls_cipher_update +void mbedtls_block_cipher_init(mbedtls_block_cipher_context_t *ctx); +void mbedtls_block_cipher_free(mbedtls_block_cipher_context_t *ctx); +int mbedtls_block_cipher_setup(mbedtls_block_cipher_context_t *ctx, + mbedtls_cipher_id_t cipher_id); +int mbedtls_block_cipher_setkey(mbedtls_block_cipher_context_t *ctx, + const unsigned char *key, + unsigned key_bitlen); +int mbedtls_block_cipher_encrypt(mbedtls_block_cipher_context_t *ctx, + const unsigned char input[16], + unsigned char output[16]); ``` -Note: `mbedtls_cipher_info_get_block_size()` can be hard-coded to return 16, -as all three supported block ciphers have the same block size (DES was -excluded). +The only supported ciphers are AES, ARIA and Camellia. They are identified by +an `mbedtls_cipher_id_t` in the `setup()` function, because that's how they're +identifed by callers (GCM/CCM). #### Cipher light dual dispatch From 4dde0b293cd84dd0eff77a1d6d5f9387a55f8a46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 14 Dec 2023 12:09:38 +0100 Subject: [PATCH 13/13] md-cipher-dispatch: editorial improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix a typo, add a reference. Signed-off-by: Manuel Pégourié-Gonnard --- docs/architecture/psa-migration/md-cipher-dispatch.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/psa-migration/md-cipher-dispatch.md b/docs/architecture/psa-migration/md-cipher-dispatch.md index bc92d00b3..430b0caec 100644 --- a/docs/architecture/psa-migration/md-cipher-dispatch.md +++ b/docs/architecture/psa-migration/md-cipher-dispatch.md @@ -358,7 +358,7 @@ The two AEAD modes, GCM and CCM, have very similar needs and positions in the st - CTR-DRBG holds a special position in the stack: most users don't care about it per se, they only care about getting random numbers - in fact PSA users don't even need to know what DRBG is used. In particular, no part of the stack is asking questions like "is CTR-DRBG-AES available?" - an RNG needs to be available and that's it - contrary to similar questions about AES-GCM etc. which are asked for example by TLS. So, it makes sense to use different designs for CTR-DRBG on one hand, and GCM/CCM on the other hand: -- CTR-DRBG can just check if `AES_C` is present and "fall back" to PSA is not. +- CTR-DRBG can just check if `AES_C` is present and "fall back" to PSA if not. - GCM and CCM need an common abstraction layer that allows: - Using AES, Aria or Camellia in a uniform way. - Dispatching to built-in or driver. @@ -379,7 +379,7 @@ Those costs could be avoided by refactoring (parts of) Cipher, but that would pr - significant differences in how the `cipher.h` API is implemented between builds with the full Cipher or only a subset; - or more work to apply the simplifications to all of Cipher. -Prototyping both approaches showed better code size savings and cleaner code with a new internal module. +Prototyping both approaches showed better code size savings and cleaner code with a new internal module (see section "Internal "block cipher" abstraction (Cipher light)" below). ## Specification