The cryptography library provides functions that implement several variants of public key cryptography. These cryptography functions are required for the BLE Secure DFU Bootloader. You can also include the library in your application (independently of the bootloader). The implementation can use different backends.
The cryptographic functionality that is supported depends on the backend that is used. All backends support the following cryptographic schemes:
In addition, the library can be used to calculate a hash (or digest) of the input data, based on a SHA-1 or SHA-2 family cryptographic hash algorithm.
If you plan to use the cryptography library, you should familiarize yourself with the general concepts of asymmetric cryptography. The following concepts are important to know:
A digital signature attests the authenticity of a set of data. Usually, it contains a signed hash or digest of the same data. The recipient of the data can then verify the signature by hashing the data and comparing the hash to the one obtained from the signature.
The signature is generated using a private key and a hashing algorithm. It can be verified using a public key.
A private key (also called signing key in the context of ECDSA) is a key that identifies its owner. You should never share your private key with anybody. When you use it to sign data, you affirm that the data is yours, because no one else knows the private key that is required for signing.
To be understood by the cryptography library, private keys must be based on one of the curves defined in NRF_CRYPTO_CURVES. See Backends for an overview of which of these curves are supported by the different backends.
A public key (also called verification key in the context of ECDSA) is openly available and can be used to verify the input data based on the signature and the hash of the input data.
The public key is calculated based on the private key. This means that if you plan to send signed data, you must create a public key and share it with the recipient so that the recipient can verify the signature.
A shared secret, or a shared key, is a key that is known only to the involved parties. The shared secret can be negotiated over an insecure channel between parties that each have a public-private key pair. After the shared secret is calculated on both sides, it can be used to encrypt communication between the parties.
Shared secrets are currently not used in secure DFU, but they can be used in different contexts (for example, they are required for Bluetooth LE Secure Connections).
The cryptography library requires private and public keys. A public key can be computed from a private key, but the private key must always be provided.
If your keys should be valid for only one device or even only one connection, you can generate them at run time. Simply generate a random number as private key and compute the corresponding public key by calling nrf_crypto_ecc_public_key_calculate.
If you need static keys for use on multiple devices, you should generate the keys externally. The following example commands use Nordic Semiconductor's nrfutil tool (see the nrfutil documentation) to generate keys based on the secp256r1 curve:
You can also generate keys using OpenSSL. See the OpenSSL documentation for instructions on how to generate a private key. Issue the following command to display the contents of the .pem key file:
This command will display both the private and the public key in big-endian format. To use these keys with the cryptography library, you must reverse the byte order. Also, the public key will be prefixed by a byte with the value "0x04", which you should ignore.
Make sure to store the private key securely and with limited access. If the private key is lost, you cannot reproduce it and therefore cannot provide signed data anymore.
The cryptography library provides one common API that can be used with different backends. Currently, two backends are available: a pure software backend that uses a well-known open source library (micro-ecc) and a hardware-accelerated backend (CryptoCell).
The software backend is compatible with all supported SoCs. Before you can use it, you must install the micro-ecc library. See Software backend (micro-ecc) for more information about this backend.
The hardware-accelerated backend is faster, consumes less power, and offers more functionality. Using the hardware-accelerated backend also decreases the size of the application. However, this backend requires hardware support and is therefore available only on the nRF52840 SoC. See Hardware-accelerated backend (CryptoCell) for more information about this backend.
The following table shows which cryptographic curves are supported by which backend:
| Cryptographic curve | Software backend | Hardware-accelerated backend |
|---|---|---|
| NRF_CRYPTO_CURVE_SECP160R1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP192R1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP224R1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP256R1 | ✓ | ✓ |
| NRF_CRYPTO_CURVE_SECP384R1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP521R1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP192K1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP224K1 | - | ✓ |
| NRF_CRYPTO_CURVE_SECP256K1 | - | ✓ |
See Recommended elliptic curves for federal government use, SEC 2: Recommended Elliptic Curve Domain Parameters, and other sources for detailed information about this curves.
The following table shows which hashing algorithms are supported by which backend:
| Hashing algorithm | Software backend | Hardware-accelerated backend |
|---|---|---|
| NRF_CRYPTO_HASH_TYPE_MD5 | - | ✓ |
| NRF_CRYPTO_HASH_TYPE_SHA1 | - | ✓ |
| NRF_CRYPTO_HASH_TYPE_SHA224 | - | ✓ |
| NRF_CRYPTO_HASH_TYPE_SHA256 | ✓ | ✓ |
| NRF_CRYPTO_HASH_TYPE_SHA384 | - | ✓ |
| NRF_CRYPTO_HASH_TYPE_SHA512 | - | ✓ |
micro-ecc is an open source library that performs cryptographic operations. It is optimized for small program size while maintaining high processing speed. The micro-ecc backend supports all current nRF5 Series devices.
When using micro-ecc, you must ensure compliance with the license of the library as stated in the LICENSE.txt file that is included in micro-ecc.
The cryptography library expects to find the compiled micro-ecc library in InstallFolder\external\micro-ecc\micro-ecc.
To install micro-ecc, complete the following steps:
make is installed (see, for example, MinGW, GNU Make, or Xcode).InstallFolder\external\micro-ecc\micro-ecc.InstallFolder\external\micro-ecc\nrf52_keil\armgccInstallFolder\external\micro-ecc\nrf52_iar\armgccInstallFolder\external\micro-ecc\nrf52_armgcc\armgccmake to compile the micro-ecc library.uECC_VLI_NATIVE_LITTLE_ENDIAN=1), the library might not work properly.The micro-ecc library does not support hashing or random number generation. However, when you use the micro-ecc backend, you can enable software implementations for this functionality separately.
The hardware-accelerated backend uses cryptography hardware to perform cryptographic operations. The required CryptoCell hardware is available on the nRF52840 SoC, but not on the nRF52832 SoC. See the nRF52840 Product Specification for detailed information about CryptoCell.
Applications that use the hardware-accelerated backend usually consume less power and are faster and smaller in size than applications that use the software backend. Therefore, you should use the CryptoCell backend on devices that support it.
CryptoCell provides more functionality than what is currently supported by the cryptography library. If you require advanced cryptographic operations, use the CryptoCell API directly. See the CryptoCell API documentation for an overview of all available objects and functions. To get started, see the Experimental: CryptoCell examples.
You select the backend that you want to use in the SDK configuration header file of your project.
To use the cryptography library with the software backend, ensure that you have installed the micro-ecc library. Then enable the following modules:
To use the cryptography library with the hardware-accelerated backend, enable the following modules:
See the BLE Secure DFU Bootloader as an example for an application that uses the software backend. The Experimental: LE Secure Connections Multirole Example uses the hardware-accelerated backend.
Before you use the cryptography library, run nrf_crypto_init to initialize it.
To create a public key from a private key, call nrf_crypto_ecc_public_key_calculate and specify which curve to use. This public key should be shared with other applications to enable them to verify signed data. Remember though that you should not share your private key, so calculating public keys in an application can be a risk.
To sign data, first call nrf_crypto_hash_compute and specify which hashing algorithm to use. This function creates a hash (or digest) of the data. Next, create a signature for the hash by calling nrf_crypto_ecdsa_sign_hash with your private key and the curve that you want to use as input. To verify the signature, the other application must first calculate the hash of the data (using nrf_crypto_hash_compute) and then call nrf_crypto_ecdsa_verify_hash with the computed hash and your public key as input.
To calculate a shared secret between two applications, each application must call nrf_crypto_ecdh_shared_secret_compute with their own private key and the other application's public key as input.