1.. _module-pw_crypto: 2 3pw_crypto 4========= 5A set of safe (read: easy to use, hard to misuse) crypto APIs. 6 7The following crypto services are provided by this module. 8 91. Hashing a message with `SHA256`_. 102. Verifying a digital signature signed with `ECDSA`_ over the NIST P256 curve. 113. Many more to come ... 12 13SHA256 14------ 15 161. Obtaining a oneshot digest. 17 18.. code-block:: cpp 19 20 #include "pw_crypto/sha256.h" 21 22 std::byte digest[32]; 23 if (!pw::crypto::sha256::Hash(message, digest).ok()) { 24 // Handle errors. 25 } 26 27 // The content can also come from a pw::stream::Reader. 28 if (!pw::crypto::sha256::Hash(reader, digest).ok()) { 29 // Handle errors. 30 } 31 322. Hashing a long, potentially non-contiguous message. 33 34.. code-block:: cpp 35 36 #include "pw_crypto/sha256.h" 37 38 std::byte digest[32]; 39 40 if (!pw::crypto::sha256::Sha256() 41 .Update(chunk1).Update(chunk2).Update(chunk...) 42 .Final().ok()) { 43 // Handle errors. 44 } 45 46ECDSA 47----- 48 491. Verifying a digital signature signed with ECDSA over the NIST P256 curve. 50 51.. code-block:: cpp 52 53 #include "pw_crypto/sha256.h" 54 55 std::byte digest[32]; 56 if (!pw::crypto::sha256::Hash(message, digest).ok()) { 57 // handle errors. 58 } 59 60 if (!pw::crypto::ecdsa::VerifyP256Signature(public_key, digest, 61 signature).ok()) { 62 // handle errors. 63 } 64 652. Verifying a digital signature signed with ECDSA over the NIST P256 curve, 66 with a long and/or non-contiguous message. 67 68.. code-block:: cpp 69 70 #include "pw_crypto/sha256.h" 71 72 std::byte digest[32]; 73 74 if (!pw::crypto::sha256::Sha256() 75 .Update(chunk1).Update(chunk2).Update(chunkN) 76 .Final(digest).ok()) { 77 // Handle errors. 78 } 79 80 if (!pw::crypto::ecdsa::VerifyP256Signature(public_key, digest, 81 signature).ok()) { 82 // Handle errors. 83 } 84 85Configuration 86------------- 87 88The crypto services offered by pw_crypto can be backed by different backend 89crypto libraries. 90 91Mbed TLS 92^^^^^^^^ 93 94To select the Mbed TLS backend, the MbedTLS library needs to be installed and 95configured. 96 97.. code-block:: sh 98 99 # Install and configure MbedTLS 100 pw package install mbedtls 101 gn gen out \ 102 --args='dir_pw_third_party_mbedtls="//.environment/packages/mbedtls" \ 103 pw_crypto_SHA256_BACKEND="//pw_crypto:sha256_mbedtls" \ 104 pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_mbedtls"' 105 106 ninja -C out 107 108For optimal code size and/or performance, the Mbed TLS library can be configured 109per product. Mbed TLS configuration is achieved by turning on and off MBEDTLS_* 110options in a config.h file. See //third_party/mbedtls for how this is done. 111 112``pw::crypto::sha256`` does not need any special configuration as it uses the 113mbedtls_sha256_* APIs directly. However you can optionally turn on 114``MBEDTLS_SHA256_SMALLER`` to further reduce the code size to from 3KiB to 115~1.8KiB at a ~30% slowdown cost (Cortex-M4). 116 117.. code-block:: c 118 119 #define MBEDTLS_SHA256_SMALLER 120 121``pw::crypto::ecdsa`` requires the following minimum configurations which yields 122a code size of ~12KiB. 123 124.. code-block:: c 125 126 #define MBEDTLS_BIGNUM_C 127 #define MBEDTLS_ECP_C 128 #define MBEDTLS_ECDSA_C 129 // The ASN1 options are needed only because mbedtls considers and verifies 130 // them (in check_config.h) as dependencies of MBEDTLS_ECDSA_C. 131 #define MBEDTLS_ASN1_WRITE_C 132 #define MBEDTLS_ASN1_PARSE_C 133 #define MBEDTLS_ECP_NO_INTERNAL_RNG 134 #define MBEDTLS_ECP_DP_SECP256R1_ENABLED 135 136BoringSSL 137^^^^^^^^^ 138 139To select the BoringSSL backend, the BoringSSL library needs to be installed and 140configured. 141 142.. code-block:: sh 143 144 # Install and configure BoringSSL 145 pw package install boringssl 146 gn gen out \ 147 --args='dir_pw_third_party_boringssl="//.environment/packages/boringssl" \ 148 pw_crypto_SHA256_BACKEND="//pw_crypto:sha256_boringssl" \ 149 pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_boringssl"' 150 151 ninja -C out 152 153BoringSSL does not provide a public configuration interface to reduce the code 154size. 155 156Micro ECC 157^^^^^^^^^ 158 159To select Micro ECC, the library needs to be installed and configured. 160 161.. code-block:: sh 162 163 # Install and configure Micro ECC 164 pw package install micro-ecc 165 gn gen out --args='dir_pw_third_party_micro_ecc="//.environment/packages/micro-ecc" pw_crypto_ECDSA_BACKEND="//pw_crypto:ecdsa_uecc"' 166 167Note Micro-ECC does not implement any hashing functions, so you will need to use other backends for SHA256 functionality if needed. 168 169Size Reports 170------------ 171 172Below are size reports for each crypto service. These vary across 173configurations. 174 175.. include:: size_report 176