nrf_crypto provides APIs to run cryptographic operations in a portable way across all devices from the nRF family. nrf_crypto supports multiple implementations of the cryptographic operations, both from software libraries and hardware-accelerated crypto modules (like the ARM CC310 cryptographic subsystem that is available in nRF52840 devices).
nrf_crypto consists of nrf_crypto frontend and multiple nrf_crypto backends. The system is structured according to the following figure:
nrf_crypto supports multiple cryptographic implementations by providing a normalization layer that hides all API differences. This layer is called the nrf_crypto frontend. Each family of cryptographic operations available to use in the nRF5 SDK distribution will be available in the nrf_crypto namespace, meaning that all cryptographic functions in the API will begin with the term nrf_crypto.
The application always sees the same frontend API, regardless of which backend and which nRF family device is used.
See nrf_crypto frontend modules for detailed descriptions of frontend modules for each family of supported cryptographic operations.
The nrf_crypto frontend features methods to precisely control the memory usage. This provides a high level of flexibility in the APIs, and also ensures that shared or static memory is controllable by the end users.
For more details on memory management in nrf_crypto, see Memory management in nrf_crypto.
The nrf_crypto API is grouped into families of cryptographic routines through the nrf_crypto namespace.
The AES frontend provides API functions to do encryption and decryption using the Advanced Encryption Standard.
The following table shows the supported AES modes in the nrf_crypto backends.
Mode | CC310 | mbed TLS |
---|---|---|
AES CBC | | |
AES CTR | | |
AES CFB | | |
AES ECB | | |
AES CBC_MAC | | |
AES CMAC | | |
For details on the AES implementation, see AES - Advanced Encryption Standard.
For AES related API documentation, see AES related functions.
The AEAD frontend provides API functions to do Authenticated Encryption with Associated Data.
The following table shows the supported AEAD modes in the nrf_crypto backends.
Mode | CC310 | mbed TLS | Oberon | Cifra |
---|---|---|---|---|
AES CCM | | | | |
AES CCM* | | | | |
AES EAX | | | | |
AES GCM | | | | |
ChaCha-Poly | | | | |
For details on the AEAD implementation, see AEAD - Authenticated Encryption with Associated Data and ChaCha-Poly.
For AEAD related API documentation, see AEAD (Authenticated Encryption with Associated Data) related.
The ECC frontend provides API functions to generate and manage keys for Eliptic Curve Cryptography. This includes generating private and public keys and converting key material from/to raw format. This API is used in conjunction with ECDH - Elliptic Curve Diffie–Hellman, ECDSA - Elliptic Curve Digital Signature Algorithm, and EdDSA - Edwards-curve Digital Signature Algorithm.
Backends offer different types of curves and schemes. To use a specific curve, an appropriate backend and curve inside it must be enabled. The table below summaries backend support for different types of curves and schemes.
CC310 | mbed TLS | Oberon | µECC | CC310_BL | |
---|---|---|---|---|---|
NIST Group | |||||
secp160r1 | | ||||
secp160r2 | | ||||
secp192r1 | | | | ||
secp224r1 | | | | | |
secp256r1 | | | | | |
secp384r1 | | | |||
secp521r1 | | | |||
Koblitz Group | |||||
secp160k1 | | ||||
secp192k1 | | | |||
secp224k1 | | | |||
secp256k1 | | | | ||
Brainpool Group | |||||
bp256r1 | | ||||
bp384r1 | | ||||
bp512r1 | | ||||
Curve25519 Group | |||||
Curve25519 1 | | | | ||
Ed25519 2 3 | |
1 - Curve25519 allows only ECDH. ECDSA is not possible using Curve25519.
For details on the ECC implementation, see ECC - Elliptic Curve Cryptography.
For ECC related API documentation, see Elliptic Curve Cryptography Key Management.
The ECDH frontend provides APIs to do Elliptic Curve Diffie-Hellman calculations. The APIs in this frontend are used in conjunction with calls to ECC - Elliptic Curve Cryptography.
The following table shows the supported curve types in the nrf_crypto backends.
Curve Type | CC310 | mbed TLS | Oberon |
---|---|---|---|
secp160r1 | | | |
secp160r2 | | | |
secp192r1 | | | |
secp224r1 | | | |
secp256r1 | | | |
secp384r1 | | | |
secp521r1 | | | |
secp160k1 | | | |
secp192k1 | | | |
secp224k1 | | | |
secp256k1 | | | |
br256r1 | | | |
br384r1 | | | |
br512r1 | | | |
Curve25519 | | | |
For details on the ECDH implementation, see ECDH - Elliptic Curve Diffie–Hellman.
For ECDH related API documentation, see Elliptic Curve Diffie-Hellman (ECDH).
The ECDSA frontend provides APIs which use the Elliptic Curve Digital Signature Algorithm to create or verify signatures.
The following table shows the supported curve types in the nrf_crypto backends.
Curve Type | CC310 | mbed TLS | Oberon |
---|---|---|---|
secp160r1 | | | |
secp160r2 | | | |
secp192r1 | | | |
secp224r1 | | | |
secp256r1 | | | |
secp384r1 | | | |
secp521r1 | | | |
secp160k1 | | | |
secp192k1 | | | |
secp224k1 | | | |
secp256k1 | | | |
br256r1 | | | |
br384r1 | | | |
br512r1 | | | |
Curve25519 | | | |
For details on the ECDSA implementation, see ECDSA - Elliptic Curve Digital Signature Algorithm.
For ECDSA related API documentation, see Elliptic Curve Digital Signature (ECDSA).
The EdDSA frontend provides APIs to use the Edwards-curve Digital Signature Algorithm to create or verify signatures. The Edwards-Curve Digital Signature Algorithm is a specialized algorithm that uses elliptic curve Curve25519 to verify the signature in an efficient way in software implementations (Ed25519).
The following table summarizes backend support for EdDSA.
CC310 | Oberon | |
---|---|---|
Ed25519 | | |
For details on the EdDSA implementation, see EdDSA - Edwards-curve Digital Signature Algorithm.
For EdDSA-related API documentation, see Edwards-curve Digital Signature Algorithm (EdDSA).
The Hash frontend provides APIs to calculate hash digests using cyptographic hash algoritms.
The following table shows the supported cryptographic hash algorithms in the nrf_crypto backends.
Hash Algorithm | CC310 | mbed TLS | Oberon | NRF_SW |
---|---|---|---|---|
SHA-256 | | | | |
SHA-512 | | | | |
For details on the Hash implementation, see Hash - Cryptographic hash functions.
For Hash related API documentation, see Cryptographic hash related functions.
The HMAC frontend provides APIs to calculate hash-based message authentication codes.
The following table show the HMAC support in the nrf_crypto backends:
Mode | CC310 | mbedtls | Oberon |
---|---|---|---|
HMAC SHA-256 | | | |
HMAC SHA-512 | | | |
For details on the HMAC implementation, see HMAC - Hash-based message authentication code.
For HMAC related API documentation, see Hash-based message authentication code (HMAC) related functions.
The HKDF frontend provides APIs to derive keys by using Extract and Expand methods using HMAC calculations.
For details on the HKDF implementation, see HKDF - HMAC-based Extract-and-Expand Key Derivation Function.
For HKDF related API documentation, see HMAC based Key Derivation Function (HKDF) related functions.
The RNG frontend provides APIs for random number generation.
The following table shows the RNG support in the nrf_crypto backends:
CC310 | nRF HW |
---|---|
| |
For details on the RNG implementation, see RNG - Random Number Generator.
For RNG related API documentation, see RNG related functions.
See the following chapters for detailed descriptions of various aspects of nrf_crypto.
Memory management in nrf_crypto