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:
- Note
- This figure does not list all available backends.
nrf_crypto frontends overview
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.
Memory management
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 .
Families of cryptographic functionality
The nrf_crypto API is grouped into families of cryptographic routines through the nrf_crypto namespace.
AES - Advanced Encryption Standard
The AES frontend provides API functions to do encryption and decryption using the Advanced Encryption Standard.
Supported AES modes in nrf_crypto backends
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 |
|
|
AES Implementation and API
For details on the AES implementation, see AES - Advanced Encryption Standard .
For AES related API documentation, see AES related functions .
AEAD - Authenticated Encryption with Associated Data
The AEAD frontend provides API functions to do Authenticated Encryption with Associated Data.
Supported AEAD modes in nrf_crypto backends
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 |
|
|
|
|
AEAD implementation and API
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 .
ECC - Elliptic Curve Cryptography
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 .
Supported backends
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.
ECC implementation and API
For details on the ECC implementation, see ECC - Elliptic Curve Cryptography .
For ECC related API documentation, see Elliptic Curve Cryptography Key Management .
ECDH - Elliptic Curve Diffie–Hellman
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 .
Supported curve types
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 |
|
|
|
ECDH implementation and API
For details on the ECDH implementation, see ECDH - Elliptic Curve Diffie–Hellman .
For ECDH related API documentation, see Elliptic Curve Diffie-Hellman (ECDH) .
ECDSA - Elliptic Curve Digital Signature Algorithm
The ECDSA frontend provides APIs which use the Elliptic Curve Digital Signature Algorithm to create or verify signatures.
Supported curve types
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 |
|
|
|
ECDSA implementation and API
For details on the ECDSA implementation, see ECDSA - Elliptic Curve Digital Signature Algorithm .
For ECDSA related API documentation, see Elliptic Curve Digital Signature (ECDSA) .
EdDSA - Edwards-curve Digital Signature Algorithm
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 |
|
|
EdDSA implementation and API
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) .
Hash - cryptographic hash algorithms
The Hash frontend provides APIs to calculate hash digests using cyptographic hash algoritms.
Supported cryptograhic hash algorithms
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 |
|
|
|
|
Hash implementation and API
For details on the Hash implementation, see Hash - Cryptographic hash functions .
For Hash related API documentation, see Cryptographic hash related functions .
HMAC - Hash-based Message Authentication Code
The HMAC frontend provides APIs to calculate hash-based message authentication codes.
Supported HMAC modes
The following table show the HMAC support in the nrf_crypto backends:
| Mode | CC310 | mbedtls | Oberon |
|---|---|---|---|
| HMAC SHA-256 |
|
|
|
| HMAC SHA-512 |
|
|
|
HMAC implementation and API
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 .
HKDF - HMAC based Key Derivation Function
The HKDF frontend provides APIs to derive keys by using Extract and Expand methods using HMAC calculations.
- Note
- For supported backends, see HMAC - Hash-based Message Authentication Code .
HKDF implementation and API
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 .
RNG - Random Number Generation
The RNG frontend provides APIs for random number generation.
RNG support in nrf_crypto backends
The following table shows the RNG support in the nrf_crypto backends:
| CC310 | nRF HW |
|---|---|
|
|
|
RNG implementation and API
For details on the RNG implementation, see RNG - Random Number Generator .
For RNG related API documentation, see RNG related functions .
Details
See the following chapters for detailed descriptions of various aspects of nrf_crypto.
Memory management in nrf_crypto