nRF5 SDK v17.1.0
Cryptography library - nrf_crypto

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_structure.svg
Basic layout nrf_crypto frontend, backend, and source or library
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.

AES support in 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.

AEAD support in 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.

ECDH curve support in 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.

ECDSA curve support in 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 support in 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:

HMAC support in 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:

RNG support in 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

Configuring nrf_crypto frontend and backends

nrf_crypto frontend modules

nrf_crypto backend modules


Documentation feedback | Developer Zone | Subscribe | Updated