pw_crypto: Suggest Mbed TLS configurations
Since multiple modules depend on the Mbed TLS library, each requiring
different configurations in order to achieve optimal code size and
performance, it is eventually a product responsibility to configure the
Mbed TLS library per the exact set of modules selected. To facilitate
that process, we document the specific Mbed TLS options needed for each
module that depend on Mbed TLS.
Change-Id: I7e491f7b6510359f83f5a40fed870147ca9bcff7
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/53741
Reviewed-by: Darren Krahn <dkrahn@google.com>
Pigweed-Auto-Submit: Ali Zhang <alizhang@google.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed.google.com.iam.gserviceaccount.com>
diff --git a/pw_crypto/docs.rst b/pw_crypto/docs.rst
index 4fa17df..c239657 100644
--- a/pw_crypto/docs.rst
+++ b/pw_crypto/docs.rst
@@ -81,6 +81,9 @@
The crypto services offered by pw_crypto can be backed by different backend crypto libraries. For now only Mbed TLS is supported, others are under construction.
Mbed TLS
+^^^^^^^^
+
+To select the Mbed TLS backend, the MbedTLS library needs to be installed and configured.
.. code-block:: sh
@@ -90,10 +93,31 @@
ninja -C out
+For optimal code size and/or performance, the Mbed TLS library needs to be configured per product. Mbed TLS configuration is achieved by turning on and off MBEDTLS_* options in a config.h file. See //third_party/mbedtls for how this is done.
+
+``pw::crypto::sha256`` does not need any special configuration as it uses the mbedtls_sha256_* APIs directly. However you can optionally turn on ``MBEDTLS_SHA256_SMALLER`` to further reduce the code size to from 3KiB to ~1.8KiB at a ~30% slowdown cost (Cortex-M4).
+
+.. code-block:: c
+
+ #define MBEDTLS_SHA256_SMALLER
+
+``pw::crypto::ecdsa`` requires the following minimum configurations which yields a code size of ~12KiB.
+
+.. code-block:: c
+
+ #define MBEDTLS_BIGNUM_C
+ #define MBEDTLS_ECP_C
+ #define MBEDTLS_ECDSA_C
+ // The ASN1 options are needed only because mbedtls considers and verifies
+ // them (in check_config.h) as dependencies of MBEDTLS_ECDSA_C.
+ #define MBEDTLS_ASN1_WRITE_C
+ #define MBEDTLS_ASN1_PARSE_C
+ #define MBEDTLS_ECP_NO_INTERNAL_RNG
+ #define MBEDTLS_ECP_DP_SECP256R1_ENABLED
Size Reports
------------
-Below are size reports for each crypto service. These may vary from across different configurations.
+Below are size reports for each crypto service. These vary across configurations.
.. include:: size_report
