diff options
Diffstat (limited to 'pw_crypto/docs.rst')
| -rw-r--r-- | pw_crypto/docs.rst | 81 |
1 files changed, 47 insertions, 34 deletions
diff --git a/pw_crypto/docs.rst b/pw_crypto/docs.rst index 1230cd35d..db3b0c2e3 100644 --- a/pw_crypto/docs.rst +++ b/pw_crypto/docs.rst @@ -1,5 +1,6 @@ .. _module-pw_crypto: +========= pw_crypto ========= A set of safe (read: easy to use, hard to misuse) crypto APIs. @@ -10,6 +11,7 @@ The following crypto services are provided by this module. 2. Verifying a digital signature signed with `ECDSA`_ over the NIST P256 curve. 3. Many more to come ... +------ SHA256 ------ @@ -43,6 +45,7 @@ SHA256 // Handle errors. } +----- ECDSA ----- @@ -82,6 +85,7 @@ ECDSA // Handle errors. } +------------- Configuration ------------- @@ -89,25 +93,47 @@ The crypto services offered by pw_crypto can be backed by different backend crypto libraries. Mbed TLS -^^^^^^^^ +======== + +The `Mbed TLS project <https://www.trustedfirmware.org/projects/mbed-tls/>`_ +is a mature and full-featured crypto library that implements cryptographic +primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. + +The project also has good support for interfacing to cryptographic accelerators. + +The small code footprint makes the project suitable and popular for embedded +systems. To select the Mbed TLS backend, the MbedTLS library needs to be installed and -configured. +configured. If using GN, do, .. code-block:: sh # Install and configure MbedTLS pw package install mbedtls gn gen out --args=' - import("//build_overrides/pigweed_environment.gni") - - dir_pw_third_party_mbedtls=pw_env_setup_PACKAGE_ROOT+"/mbedtls" - pw_crypto_SHA256_BACKEND="//pw_crypto:sha256_mbedtls" - pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_mbedtls" + dir_pw_third_party_mbedtls=getenv("PW_PACKAGE_ROOT")+"/mbedtls" + pw_crypto_SHA256_BACKEND="//pw_crypto:sha256_mbedtls_v3" + pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_mbedtls_v3" ' ninja -C out +If using Bazel, add the Mbed TLS repository to your WORKSPACE and select +appropriate backends by adding them to your project's `platform +<https://bazel.build/extending/platforms>`_: + +.. code-block:: python + + platform( + name = "my_platform", + constraint_values = [ + "@pigweed//pw_crypto:sha256_mbedtls_backend", + "@pigweed//pw_crypto:ecdsa_mbedtls_backend", + # ... other constraint_values + ], + ) + For optimal code size and/or performance, the Mbed TLS library can 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. @@ -136,31 +162,8 @@ a code size of ~12KiB. #define MBEDTLS_ECP_NO_INTERNAL_RNG #define MBEDTLS_ECP_DP_SECP256R1_ENABLED -BoringSSL -^^^^^^^^^ - -To select the BoringSSL backend, the BoringSSL library needs to be installed and -configured. - -.. code-block:: sh - - # Install and configure BoringSSL - pw package install boringssl - gn gen out --args=' - import("//build_overrides/pigweed_environment.gni") - - dir_pw_third_party_boringssl=pw_env_setup_PACKAGE_ROOT+"/boringssl" - pw_crypto_SHA256_BACKEND="//pw_crypto:sha256_boringssl" - pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_boringssl" - ' - - ninja -C out - -BoringSSL does not provide a public configuration interface to reduce the code -size. - Micro ECC -^^^^^^^^^ +========= To select Micro ECC, the library needs to be installed and configured. @@ -169,9 +172,7 @@ To select Micro ECC, the library needs to be installed and configured. # Install and configure Micro ECC pw package install micro-ecc gn gen out --args=' - import("//build_overrides/pigweed_environment.gni") - - dir_pw_third_party_micro_ecc=pw_env_setup_PACKAGE_ROOT+"/micro-ecc" + dir_pw_third_party_micro_ecc=getenv("PW_PACKAGE_ROOT")+"/micro-ecc" pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_uecc" ' @@ -183,6 +184,7 @@ can be selected with ``pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_uecc_little_en Note Micro-ECC does not implement any hashing functions, so you will need to use other backends for SHA256 functionality if needed. +------------ Size Reports ------------ @@ -190,3 +192,14 @@ Below are size reports for each crypto service. These vary across configurations. .. include:: size_report + +------------- +API reference +------------- +.. doxygenfunction:: pw::crypto::ecdsa::VerifyP256Signature(ConstByteSpan public_key, ConstByteSpan digest, ConstByteSpan signature) +.. doxygenfunction:: pw::crypto::sha256::Hash(ConstByteSpan message, ByteSpan out_digest) +.. doxygenfunction:: pw::crypto::sha256::Hash(stream::Reader& reader, ByteSpan out_digest) +.. doxygenvariable:: pw::crypto::sha256::kDigestSizeBytes +.. doxygenfunction:: pw::crypto::sha256::Sha256::Final(ByteSpan out_digest) +.. doxygenfunction:: pw::crypto::sha256::Sha256::Update(ConstByteSpan data) +.. doxygenenum:: pw::crypto::sha256::Sha256State |