API documentation

nRF CC310 bootloader crypto library

group nrf_cc310_bl

Common declarations for nrf_cc310_bl ECDSA verify APIs.

Function for initializing the CC310 hardware and runtime library.

Type definitions and public APIs for nrf_cc310_bl HASH using SHA-256.

Shared declarations used by nrf_cc310_bl for hash APIs.

Type definitions and APIs for nrf_cc310_bl ECDSA verify using curve secp256r1.

Note

Running this initialization is intended for cases where there is no direct requirement for the RNG subsystem (all operations are deterministic).

Return Value
  • CRYS_OK: Initialization was successful.

Defines

NRF_CC310_BL_ECDSA_CONTEXT_INITIALIZED
NRF_CC310_BL_ECDSA_VERIFY_CONTEXT_SIZE_SECP224R1

Macro for the size of the ECDSA Verify context.

NRF_CC310_BL_ECDSA_VERIFY_CONTEXT_SIZE_SECP256R1

Macro for the size of the ECDSA Verify context.

NRF_CC310_BL_HASH_CONTEXT_INITIALIZED

Value indicating that the hash context is initialized.

NRF_CC310_BL_HASH_CONTEXT_BUFFER_SIZE_SHA256

Size of internal representation of SHA-256 hash context.

NRF_CC310_BL_SHA256_DIGEST_SIZE_IN_WORDS

Size of SHA-256 hash digest in words.

NRF_CC310_BL_SHA256_DIGEST_SIZE_IN_BYTES

Size of SHA-256 hash digest in bytes.

Typedefs

typedef uint8_t nrf_cc310_bl_hash_digest_sha256_t[(32)]

Array to hold SHA-256 hash digest.

Functions

CRYSError_t nrf_cc310_bl_ecdsa_verify_init_secp256r1(nrf_cc310_bl_ecdsa_verify_context_secp256r1_t *const p_context, nrf_cc310_bl_ecc_public_key_secp256r1_t const *const p_public_key)

Function for initializing the context information for an ECDSA verify operation.

Note

The memory that holds the context object must be allocated prior to this call.

Parameters
  • [inout] p_context: Pointer to the structure holding context information for the ECDSA verify operation.

  • [in] p_public_key: Pointer to the structure holding the public key for the ECDSA verify operation.

Return Value
  • CRYS_ECDSA_VERIFY_INVALID_USER_CONTEXT_PTR_ERROR: p_context was NULL.

  • CRYS_ECDSA_VERIFY_SIGNER_PUBL_KEY_VALIDATION_TAG_ERROR: p_public_key was NULL.

CRYSError_t nrf_cc310_bl_ecdsa_verify_hash_secp256r1(nrf_cc310_bl_ecdsa_verify_context_secp256r1_t *const p_context, nrf_cc310_bl_ecc_signature_secp256r1_t const *const p_signature, uint8_t const *const p_hash, uint32_t hash_len)

Function for executing an ECDSA verify operation using secp256r1 with hash input.

Note

The ECDSA verify context structure must be initialized prior to this call using nrf_cc310_bl_ecdsa_verify_init_secp256r1.

Parameters
  • [inout] p_context: Pointer to the structure holding context information for the ECDSA verify operation.

  • [in] p_signature: Pointer to the structure holding the signature to use for the ECDSA verify operation.

  • [in] p_hash: Pointer to the hash to use in the ECDSA verify operation.

  • [in] hash_len: Length of the hash to verify.

Return Value
  • CRYS_OK: Signature was successfully verified.

  • CRYS_ECDSA_VERIFY_INVALID_USER_CONTEXT_PTR_ERROR: p_context was NULL.

  • CRYS_ECDSA_VERIFY_USER_CONTEXT_VALIDATION_TAG_ERROR: p_context was not initialized.

  • CRYS_ECDSA_VERIFY_INVALID_SIGNATURE_IN_PTR_ERROR: p_signature was NULL.

  • CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_PTR_ERROR: p_hash was NULL.

  • CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_SIZE_ERROR: hash_len was invalid.

  • CRYS_ECDSA_VERIFY_INCONSISTENT_VERIFY_ERROR: Signature verification failed.

CRYSError_t nrf_cc310_bl_ecdsa_verify_secp256r1(nrf_cc310_bl_ecdsa_verify_context_secp256r1_t *const p_context, nrf_cc310_bl_ecc_public_key_secp256r1_t const *const p_public_key, nrf_cc310_bl_ecc_signature_secp256r1_t const *const p_signature, uint8_t const *const p_hash, uint32_t hash_len)

Function for executing an ECDSA verify operation using secp256r1 with hash input in integrated form.

Note

This will run initialization of ECDSA context and run ECDSA verify in a single step.

Parameters
  • [inout] p_context: Pointer to the structure holding context information for the ECDSA verify operation.

  • [in] p_public_key: Pointer to the structure holding the public key for the ECDSA verify operation.

  • [in] p_signature: Pointer to the structure holding the signature to use for the ECDSA verify operation.

  • [in] p_hash: Pointer to the hash to use in the ECDSA verify operation.

  • [in] hash_len: Length of the hash to verify.

Return Value
  • CRYS_OK: Signature was successfully verified.

  • CRYS_ECDSA_VERIFY_INVALID_USER_CONTEXT_PTR_ERROR: p_context was NULL.

  • CRYS_ECDSA_VERIFY_USER_CONTEXT_VALIDATION_TAG_ERROR: p_context was not initialized.

  • CRYS_ECDSA_VERIFY_SIGNER_PUBL_KEY_VALIDATION_TAG_ERROR: p_public_key was NULL.

  • CRYS_ECDSA_VERIFY_INVALID_SIGNATURE_IN_PTR_ERROR: p_signature was NULL.

  • CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_PTR_ERROR: p_hash was NULL.

  • CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_SIZE_ERROR: hash_len was invalid.

  • CRYS_ECDSA_VERIFY_INCONSISTENT_VERIFY_ERROR: Signature verification failed.

CRYSError_t nrf_cc310_bl_hash_sha256_init(nrf_cc310_bl_hash_context_sha256_t *const p_hash_context)

Function for initializing the SHA-256 context.

Note

Memory pointed to in hash context must be allocated prior to this call.

Parameters
  • [inout] p_hash_context: Structure holding context information for the SHA-256 operation.

Return Value
  • CRYS_OK: If call was successful.

  • CRYS_HASH_INVALID_USER_CONTEXT_POINTER_ERROR: p_hash_context was NULL.

CRYSError_t nrf_cc310_bl_hash_sha256_update(nrf_cc310_bl_hash_context_sha256_t *const p_hash_context, uint8_t const *p_src, uint32_t len)

Function for running an update to the SHA-256 hash calculation.

Parameters
  • [inout] p_hash_context: Structure holding context information for the SHA-256 operation.

  • [in] p_src: Input data to be added to the digest.

  • [in] len: Amount of data passed in p_src.

Return Value
  • CRYS_OK: If call was successful.

  • CRYS_HASH_INVALID_USER_CONTEXT_POINTER_ERROR: p_hash_context was NULL.

  • CRYS_HASH_USER_CONTEXT_CORRUPTED_ERROR: p_hash_context not initialized.

  • CRYS_HASH_LAST_BLOCK_ALREADY_PROCESSED_ERROR: p_hash_context already finalized.

CRYSError_t nrf_cc310_bl_hash_sha256_finalize(nrf_cc310_bl_hash_context_sha256_t *const p_hash_context, nrf_cc310_bl_hash_digest_sha256_t *const p_digest)

Function for finalizing the hash calculation.

Note

Memory pointed to in hash digest must be allocated prior to this call.

Parameters
  • [inout] p_hash_context: Structure holding context information for the SHA-256 operation.

  • [inout] p_digest: Pointer to the structure holding SHA-256 hash digest. Data pointed to must be 32 bytes long.

Return Value
  • CRYS_HASH_INVALID_USER_CONTEXT_POINTER_ERROR: p_hash_context was NULL.

  • CRYS_HASH_USER_CONTEXT_CORRUPTED_ERROR: p_hash_context was corrupted.

  • CRYS_HASH_INVALID_RESULT_BUFFER_POINTER_ERROR: p_digest was NULL.

CRYSError_t nrf_cc310_bl_init(void)
struct nrf_cc310_bl_ecc_public_key_secp256r1_t
#include <nrf_cc310_bl_ecdsa_verify_secp256r1.h>

Structure holding the secp256r1 public key represented by X,Y coordinates.

Public Members

uint8_t x[32]

Public key X coordinate in big-endian format.

uint8_t y[32]

Public key Y coordinate in big-endian format.

struct nrf_cc310_bl_ecc_signature_secp256r1_t
#include <nrf_cc310_bl_ecdsa_verify_secp256r1.h>

Structure holding the secp256r1 signature represented by R,S values.

Public Members

uint8_t r[32]

Signature R part in big-endian format.

uint8_t s[32]

Signature S part in big-endian format.

struct nrf_cc310_bl_ecdsa_verify_context_secp256r1_t
#include <nrf_cc310_bl_ecdsa_verify_secp256r1.h>

Structure holding memory required for allocation of CC310 ECDSA verify context using curve secp256r1.

struct nrf_cc310_bl_hash_context_sha256_t
#include <nrf_cc310_bl_hash_sha256.h>

Structure to hold SHA-256 context information.

nRF CC310 platform library

group nrf_cc310_platform

nrf_cc310_platform library containing CC310 hardware initialization and entropy gathering APIs. The library also contains APIs and companion source-files to setus RTOS dependent mutex and abort functionality for the nrf_cc310_mbedcrypto library in Zephyr RTOS and FreeRTOS.

CC310 Platform - Defines

group nrf_cc310_platform_defines

nrf_cc310_platform shared defines and return codes.

Defines

NRF_CC310_PLATFORM_ENTROPY_MAX_GATHER

Definition of max number of entropy bits to gather for CTR_DRBG.

NRF_CC310_PLATFORM_USE_COUNT_MAX

Definition of max count of concurrent usage.

Note

The max value will never be reached.

NRF_CC310_PLATFORM_SUCCESS
NRF_CC310_PLATFORM_ERROR_PARAM_NULL
NRF_CC310_PLATFORM_ERROR_INTERNAL
NRF_CC310_PLATFORM_ERROR_RNG_TEST_FAILED
NRF_CC310_PLATFORM_ERROR_HW_VERSION_FAILED
NRF_CC310_PLATFORM_ERROR_PARAM_WRITE_FAILED
NRF_CC310_PLATFORM_ERROR_MUTEX_NOT_INITIALIZED
NRF_CC310_PLATFORM_ERROR_MUTEX_FAILED
NRF_CC310_PLATFORM_ERROR_ENTROPY_NOT_INITIALIZED
NRF_CC310_PLATFORM_ERROR_ENTROPY_TRNG_TOO_LONG

CC310 Platform - Initialization APIs

group nrf_cc310_platform_init

The nrf_cc310_platform APIs provides functions related to initialization of the Arm CC310 hardware accelerator for usage in nrf_cc310_platform and dependent libraries.

Functions

int nrf_cc310_platform_init(void)

Function to initialize the nrf_cc310_platform with rng support.

Return

Zero on success, otherwise a non-zero error code.

int nrf_cc310_platform_init_no_rng(void)

Function to initialize the nrf_cc310_platform without rng support.

Return

Zero on success, otherwise a non-zero error code.

int nrf_cc310_platform_deinit(void)

Function to deintialize the nrf_cc310_platform.

Return

Zero on success, otherwise a non-zero error code.

bool nrf_cc310_platform_is_initialized(void)

Function to check if the nrf_cc310_platform is initialized.

Return Value
  • True: if initialized, otherwise false.

bool nrf_cc310_platform_rng_is_initialized(void)

Function to check if the nrf_cc310_platform is initialized with RNG support.

Return Value
  • True: if RNG is initialized, otherwise false.

void CRYPTOCELL_IRQHandler(void)

ISR Function for processing of CC310 Interrupts. This CC310 interrupt service routine function should be called for interrupt processing. Either by placing this functions directly in the vector table or by calling it from the ISR in the OS.

CC310 Platform - Entropy APIs

group nrf_cc310_platform_entropy

The nrf_cc310_platform_entropy APIs provides TRNG using Arm CC310 hardware acceleration.

Functions

int nrf_cc310_platform_entropy_get(uint8_t *buffer, size_t length, size_t *olen)

Function to generate entropy using Arm CryptoCell CC310.

This API corresponds to mbedtls_hardware_poll. It provides TRNG using the Arm CC310 hardware accelerator.

Note

This API is only usable if nrf_cc310_platform initialization APIs was run prior to calling it.

Return

Any other error code returned from mbedtls_hardware_poll

Parameters
  • [out] buffer: Pointer to buffer to hold the entropy data.

  • [in] length: Length of the buffer to fill with entropy data.

  • [out] olen: Pointer to variable that will hold the length of generated entropy.

Return Value
  • 0: on success

CC310 Platform - Mutex APIs

group nrf_cc310_platform_mutex

The nrf_cc310_platform_mutex APIs provides RTOS integration for mutex usage in nrf_cc310_platform and dependent libraries.

Defines

NRF_CC310_PLATFORM_MUTEX_MASK_INVALID

Mask indicating that the mutex is invalid (not initialized or allocated).

NRF_CC310_PLATFORM_MUTEX_MASK_IS_VALID

Mask value indicating that the mutex is valid for use.

NRF_CC310_PLATFORM_MUTEX_MASK_IS_ALLOCATED

Mask value indicating that the mutex is allocated and requires deallocation once freed.

Typedefs

typedef void (*nrf_cc310_platform_mutex_init_fn_t)(nrf_cc310_platform_mutex_t *mutex)

Type definition of function pointer to initialize a mutex.

Calling this function pointer should initialize a previously uninitialized mutex or do nothing if the mutex is already initialized.

Note

Initialization may not imply memory allocation, as this can be done using static allocation through other APIs in the RTOS.

Parameters
  • [in] mutex: Pointer to a mutex to initialize.

typedef void (*nrf_cc310_platform_mutex_free_fn_t)(nrf_cc310_platform_mutex_t *mutex)

Type definition of function pointer to free a mutex.

Calling this function pointer should free a mutex.

Note

If the RTOS does not provide an API to free the mutex it is advised to reset the mutex to an initialized state with no owner.

Parameters
  • [in] mutex: Pointer to a mutex to free.

typedef int (*nrf_cc310_platform_mutex_lock_fn_t)(nrf_cc310_platform_mutex_t *mutex)

Type definition of function pointer to lock a mutex.

Calling this function pointer should lock a mutex.

Parameters
  • [in] mutex: Pointer to a mutex to lock.

typedef int (*nrf_cc310_platform_mutex_unlock_fn_t)(nrf_cc310_platform_mutex_t *mutex)

Type definition of function pointer to unlock a mutex.

Calling this function pointer should unlock a mutex.

Parameters
  • [in] mutex: Pointer to a mutex to unlock.

Functions

void nrf_cc310_platform_set_mutexes(nrf_cc310_platform_mutex_apis_t const *const apis, nrf_cc310_platform_mutexes_t const *const mutexes)

Function to set platform mutex APIs and mutexes.

Parameters
  • [in] apis: Structure holding the mutex APIs.

  • [in] mutexes: Structure holding the mutexes.

void nrf_cc310_platform_mutex_init(void)

Function to initialize RTOS thread-safe mutexes.

This function must be implemented to set the platform mutex APIS, and platform mutexes.

Note

This function must be called once before calling nrf_cc310_platform_init() or nrf_cc310_platform_init_no_rng().

Note

This function is not expected to be thread-safe.

Variables

nrf_cc310_platform_mutex_apis_t platform_mutex_apis

External reference to structure holding the currently set platform mutexe APIs.

nrf_cc310_platform_mutexes_t platform_mutexes

External reference to currently set platform hw mutexes.

struct nrf_cc310_platform_mutex_t
#include <nrf_cc310_platform_mutex.h>

Type definition of architecture neutral mutex type.

struct nrf_cc310_platform_mutex_apis_t
#include <nrf_cc310_platform_mutex.h>

Type definition of structure holding platform mutex APIs.

struct nrf_cc310_platform_mutexes_t
#include <nrf_cc310_platform_mutex.h>

Type definition of structure to platform hw mutexes.

CC310 Platform - Abort APIs

group nrf_cc310_platform_abort

The nrf_cc310_platform_entropy APIs provides callbacks to abort from nrf_cc310_platform and/or dependent libraries.

Typedefs

typedef void *nrf_cc310_platform_abort_handle_t

Type definition of handle used for abort.

This handle could point to the thread or task to abort or any other static memory required for aborting the on-going cryptographic routine(s).

typedef void (*nrf_cc310_platform_abort_fn_t)(char const *const reason)

Type definition of platform abort function.

Note

This function pointer will be used when the nrf_cc310_platform and/or dependent libraries raises an error that can’t be recovered.

Functions

void nrf_cc310_platform_set_abort(nrf_cc310_platform_abort_apis_t const *const apis)

Function to set platform abort APIs.

Parameters
  • [in] apis: Pointer to platform APIs.

void nrf_cc310_platform_abort_init(void)

Function to initialize platform abort APIs.

Note

This function must be called once before calling nrf_cc310_platform initialization APIs or nrf_cc310_platform_init_no_rng.

Note

This function is not expected to be thread-safe.

Variables

nrf_cc310_platform_abort_apis_t platform_abort_apis

External reference to the platform abort APIs.

struct nrf_cc310_platform_abort_apis_t
#include <nrf_cc310_platform_abort.h>

Type definition of structure holding platform abort APIs.

Public Members

nrf_cc310_platform_abort_handle_t abort_handle

Handle to use when crypto operations are aborted.

nrf_cc310_platform_abort_fn_t abort_fn

Function to use when crypto operations are aborted.

nrf_oberon crypto library

group nrf_oberon

Highly optimized cryptographic algorithm implementation for Cortex-M0, Cortex-M4, and Cortex-M33. Created by Oberon, under distribution license with Nordic Semiconductor ASA.

AES - Advanced Encryption Standard APIs

group nrf_oberon_aes

AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.

AES-CTR - AES Counter Mode

group nrf_oberon_aes_ctr

Type definitions and APIs for AES-CTR (AES Counter mode).

AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.

AES-CTR (AES counter mode) is an AES mode which effectively turns the block cipher into a stream cipher. The AES block encryption is used on a value which is incremented for each new block. The resulting cypher stream is then xor combined with the plaintext to get the ciphertext. In contrast to AES itself, encryption and decryption operations are identical for AES-CTR.

Incremental AES-CTR encryption/decryption.

This group of functions can be used to incrementally compute the AES-CTR encryption/decryption for a given message.

void ocrypto_aes_ctr_init(ocrypto_aes_ctr_ctx *ctx, const uint8_t *key, size_t size, const uint8_t iv[16])

AES-CTR initialization.

The context ctx is initialized using the given key key and initial vector iv.

Parameters
  • [out] ctx: Context.

  • key: AES key.

  • size: Key size (16, 24, or 32 bytes).

  • iv: Initial vector.

void ocrypto_aes_ctr_encrypt(ocrypto_aes_ctr_ctx *ctx, uint8_t *ct, const uint8_t *pt, size_t pt_len)

AES-CTR incremental encryption.

The plaintext pt is encrypted to the ciphertext ct using the context ctx.

This function can be called repeatedly until the whole message is processed.

Remark

ct and pt can point to the same address.

Remark

Initialization of the context ctx through ocrypto_aes_ctr_init is required before this function can be called.

Parameters
  • ctx: Context.

  • [out] ct: Ciphertext.

  • pt: Plaintext.

  • pt_len: Length of pt and ct.

void ocrypto_aes_ctr_decrypt(ocrypto_aes_ctr_ctx *ctx, uint8_t *pt, const uint8_t *ct, size_t ct_len)

AES-CTR incremental decryption.

The ciphertext ct is decrypted to the plaintext pt using the context ctx.

This function can be called repeatedly until the whole message is processed.

Remark

ct and pt can point to the same address.

Remark

Initialization of the context ctx through ocrypto_aes_ctr_init is required before this function can be called.

Parameters
  • ctx: Context.

  • [out] pt: Plaintext.

  • ct: Ciphertext.

  • ct_len: Length of ct and pt.

AES EAX APIs

group nrf_oberon_aes_eax

Type definitions and APIS for AES EAX (Encrypt-then-authenticate-then-translate)

AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.

AES-EAX (encrypt-then-authenticate-then-translate) is an AES mode which effectively turns the block cipher into a stream cipher. The AES block cipher primitive is used in CTR mode for encryption and as OMAC for authentication over each block.

Functions

void ocrypto_aes_eax_encrypt(uint8_t *ct, uint8_t tag[16], const uint8_t *pt, size_t pt_len, const uint8_t *key, size_t size, const uint8_t *iv, size_t iv_len, const uint8_t *aa, size_t aa_len)

AES-EAX encryption.

Remark

ct and pt can point to the same address.

Parameters
  • [out] ct: Cyphertext.

  • [out] tag: Authentication tag.

  • pt: Plaintext.

  • pt_len: Plaintext length.

  • key: AES key.

  • size: Key size (16, 24, or 32 bytes).

  • iv: Initial vector.

  • iv_len: Initial vector length.

  • aa: Additional authentication data.

  • aa_len: Additional authentication data length.

int ocrypto_aes_eax_decrypt(uint8_t *pt, const uint8_t tag[16], const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size, const uint8_t *iv, size_t iv_len, const uint8_t *aa, size_t aa_len)

AES-EAX decryption.

Remark

ct and pt can point to the same address.

Parameters
  • [out] pt: Plaintext.

  • tag: Authentication tag.

  • ct: Cyphertext.

  • ct_len: Cyphertext length.

  • key: AES key.

  • size: Key size (16, 24, or 32 bytes).

  • iv: Initial vector.

  • iv_len: Initial vector length.

  • aa: Additional authentication data.

  • aa_len: Additional authentication data length.

Return Value
  • 0: If tag is valid.

  • -1: Otherwise.

AES GCM - AES Galois/Counter Mode APIs

group nrf_oberon_aes_gcm

Type definitions and APIs for AES-GCM (AES Galois/Counter Mode).

AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.

AES-GCM (AES Galois/Counter Mode) is an AES mode which effectively turns the block cipher into a stream cipher. The AES block cipher primitive is used in CTR mode for encryption and decryption. In addition, 128-bit Galois Field multiplication is used for authentication.

Functions

void ocrypto_aes_gcm_encrypt(uint8_t *ct, uint8_t tag[16], const uint8_t *pt, size_t pt_len, const uint8_t *key, size_t size, const uint8_t iv[12], const uint8_t *aa, size_t aa_len)

AES-GCM encryption.

Remark

ct and pt can point to the same address.

Parameters
  • [out] ct: Cyphertext.

  • [out] tag: Authentication tag.

  • pt: Plaintext.

  • pt_len: Plaintext length.

  • key: AES key.

  • size: Key size (16, 24, or 32 bytes).

  • iv: Initial vector.

  • aa: Additional authentication data.

  • aa_len: Additional authentication data length.

int ocrypto_aes_gcm_decrypt(uint8_t *pt, const uint8_t tag[16], const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size, const uint8_t iv[12], const uint8_t *aa, size_t aa_len)

AES-GCM decryption.

Remark

ct and pt can point to the same address.

Parameters
  • [out] pt: Plaintext.

  • tag: Authentication tag.

  • ct: Cyphertext.

  • ct_len: Cyphertext length.

  • key: AES key.

  • size: Key size (16, 24, or 32 bytes).

  • iv: Initial vector.

  • aa: Additional authentication data.

  • aa_len: Additional authentication data length.

Return Value
  • 0: If tag is valid.

  • -1: Otherwise.

AES key sizes

group nrf_oberon_aes_key

Type definition of AES key sizes.

AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.

Defines

ocrypto_aes128_KEY_BYTES

AES-128 key size in bytes.

ocrypto_aes192_KEY_BYTES

AES-192 key size in bytes.

ocrypto_aes256_KEY_BYTES

AES-256 key size in bytes.

ChaCha20-Poly1305

group nrf_oberon_chacha_poly

ChaCha20-Poly1305 is an authenticated encryption algorithm with optional additional authenticated data developed by Daniel J.Bernstein.

ChaCha20-Poly1305 APIs

group nrf_oberon_chacha_poly_apis

Type declaration and APIs for authenticated encryption and additional data using the ChaCha20-Poly1305 algorithm.

ChaCha20-Poly1305 is an authenticated encryption algorithm with optional additional authenticated data developed by Daniel J.Bernstein.

The ChaCha20 stream cipher is combined with the Poly1305 authenticator.

See

RFC 7539 - ChaCha20 and Poly1305 for IETF Protocols

Unnamed Group

int ocrypto_chacha20_poly1305_decrypt(const uint8_t tag[(16)], uint8_t *m, const uint8_t *c, size_t c_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

AEAD ChaCha20-Poly1305 decrypt.

If the authentication tag tag is valid for the ciphertext c, the encryption key k and the nonce n, the ciphertext is decrypted and put into m. The decrypted message m has the same length c_len as the original ciphertext.

Remark

m and c can point to the same address.

Parameters
  • tag: Received authentication tag.

  • [out] m: Decoded message. Same length as received ciphertext.

  • c: Received ciphertext.

  • c_len: Length of c and m.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

Return Value
  • 0: If tag is valid.

  • -1: Otherwise.

int ocrypto_chacha20_poly1305_decrypt_aad(const uint8_t tag[(16)], uint8_t *m, const uint8_t *c, size_t c_len, const uint8_t *a, size_t a_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

AEAD ChaCha20-Poly1305 decrypt with AAD.

If the authentication tag tag is valid for the ciphertext c, the additional authenticated data a, the encryption key k and the nonce n, the ciphertext is decrypted and put into m. The decrypted message m has the same length c_len as the original ciphertext.

Remark

m and c can point to the same address.

Parameters
  • tag: Received authentication tag.

  • [out] m: Decoded message. Same length as received ciphertext.

  • c: Received ciphertext.

  • c_len: Length of c and m.

  • a: Received additional authenticated data.

  • a_len: Length of a.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

Return Value
  • 0: If tag is valid.

  • -1: Otherwise.

Defines

ocrypto_chacha20_poly1305_KEY_BYTES

Length of the encryption key.

ocrypto_chacha20_poly1305_NONCE_BYTES_MAX

Maximum length of the nonce.

ocrypto_chacha20_poly1305_TAG_BYTES

Length of the authentication tag.

Functions

void ocrypto_chacha20_poly1305_encrypt(uint8_t tag[(16)], uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

AEAD ChaCha20-Poly1305 encrypt.

The message m is encrypted using a ChaCha20 cipher stream derived from the encryption key k and the nonce n. The resulting ciphertext has the same length m_len as the input message m and is put into c.

Additionally, the ciphertext c is authenticated with a tag that is generated with Poly1305 using a unique subkey derived from k and n, and then put into tag.

Remark

c and m can point to the same address.

Remark

When reusing an encryption key k for a different message m, a different nonce n must be used.

Parameters
  • [out] tag: Generated authentication tag.

  • [out] c: Generated ciphertext. Same length as input message.

  • m: Input message.

  • m_len: Length of m and c.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

void ocrypto_chacha20_poly1305_encrypt_aad(uint8_t tag[(16)], uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *a, size_t a_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

AEAD ChaCha20-Poly1305 encrypt with AAD.

The message m is encrypted using a ChaCha20 cipher stream derived from the encryption key k and the nonce n. The resulting ciphertext has the same length m_len as the input message m and is put into c.

Additionally, the ciphertext c, as well as the additional authenticated data a, is authenticated with a tag that is generated with Poly1305 using a unique subkey derived from k and n, and then put into tag.

Remark

c and m can point to the same address.

Remark

When reusing an encryption key k for a different message m or different additional authenticated data a, a different nonce n must be used.

Parameters
  • [out] tag: Generated authentication tag.

  • [out] c: Generated ciphertext. Same length as input message.

  • m: Input message.

  • m_len: Length of m and c.

  • a: Additional authenticated data.

  • a_len: Length of a.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

ChaCha20 APIs

group nrf_oberon_chacha

Type declaration and APIs for the Chacha20 stream cipher algorithm.

ChaCha20 is a stream cipher developed by Daniel J. Bernstein based on the 20-round cipher Salsa20/20.

A 256-bit key is expanded into 2^64 randomly accessible streams, each containing 2^64 randomly accessible 64-byte (512-bit) blocks.

The changes from Salsa20/20 to ChaCha20 are designed to improve diffusion per round, conjecturally increasing resistance to cryptanalysis, while preserving - and often improving - time per round.

See

RFC 7539 - ChaCha20 and Poly1305 for IETF Protocols

See

The ChaCha family of stream ciphers

Defines

ocrypto_chacha20_KEY_BYTES

Length of the encryption key.

ocrypto_chacha20_NONCE_BYTES_MAX

Maximum length of the nonce.

Functions

void ocrypto_chacha20_stream(uint8_t *c, size_t c_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)], uint32_t count)

ChaCha20 cipher stream generator.

The encryption key k, the nonce n, and the initial block counter count are used to generate a pseudo random cipher stream.

Possible applications include key generation and random number generation.

Remark

When reusing an encryption key k, a different nonce n or initial block counter count must be used.

Remark

This function is equivalent to chacha20_stream_xor with a message m consisting of c_len zeroes.

Parameters
  • [out] c: Generated cipher stream.

  • c_len: Length of c.

  • n: Nonce.

  • n_len: Nonce length. 0 <= n_len <= ocrypto_chacha20_NONCE_BYTES_MAX.

  • k: Encryption key.

  • count: Initial block counter.

void ocrypto_chacha20_stream_xor(uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)], uint32_t count)

ChaCha20 cipher stream encoder.

The message m is encrypted by applying the XOR operation with a pseudo random cipher stream derived from the encryption key k, the nonce n, and the initial block counter count.

Calling the function a second time with the generated ciphertext as input message m decrypts it back to the original message.

Remark

c and m can point to the same address.

Remark

When reusing an encryption key k for a different message m, a different nonce n or initial block counter count must be used.

Parameters
  • [out] c: Generated ciphertext. Same length as input message.

  • m: Input message.

  • m_len: Length of c and m.

  • n: Nonce.

  • n_len: Nonce length. 0 <= n_len <= ocrypto_chacha20_NONCE_BYTES_MAX.

  • k: Encryption key.

  • count: Initial block counter.

ChaCha20-Poly1305 incremental APIs

group nrf_oberon_chacha_poly_inc

Type declaration and APIs for authenticated encryption and additional data using the ChaCha20-Poly1305 algorithm in incremental steps.

ChaCha20-Poly1305 is an authenticated encryption algorithm with optional additional authenticated data developed by Daniel J.Bernstein.

The ChaCha20 stream cipher is combined with the Poly1305 authenticator.

See

RFC 7539 - ChaCha20 and Poly1305 for IETF Protocols

Incremental ChaCha20-Poly1305 generator.

This group of functions can be used to incrementally encode and decode using the ChaCha20-Poly1305 stream cypher.

Use pattern:

Encoding:

ocrypto_chacha20_poly1305_init(ctx, nonce, nonce_len, key);
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key);
...
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key);
ocrypto_chacha20_poly1305_update_enc(ctx, ct, pt, pt_len, nonce, nonce_len, key);
...
ocrypto_chacha20_poly1305_update_enc(ctx, ct, pt, pt_len, nonce, nonce_len, key);
ocrypto_chacha20_poly1305_final_enc(ctx, tag);
Decoding:
ocrypto_chacha20_poly1305_init(ctx, nonce, nonce_len, key);
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key);
...
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key);
ocrypto_chacha20_poly1305_update_dec(ctx, pt, ct, ct_len, nonce, nonce_len, key);
...
ocrypto_chacha20_poly1305_update_dec(ctx, pt, ct, ct_len, nonce, nonce_len, key);
res = ocrypto_chacha20_poly1305_final_dec(ctx, tag);

void ocrypto_chacha20_poly1305_init(ocrypto_chacha20_poly1305_ctx *ctx, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

ChaCha20-Poly1305 initialization.

The generator state ctx is initialized by this function.

Parameters
  • [out] ctx: Generator state.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

void ocrypto_chacha20_poly1305_update_aad(ocrypto_chacha20_poly1305_ctx *ctx, const uint8_t *a, size_t a_len)

SHA-ChaCha20-Poly1305 incremental aad input.

The generator state ctx is updated to include a data chunk a.

This function can be called repeatedly until the whole data is processed.

Remark

Initialization of the generator state ctx through ocrypto_chacha20_poly1305_init is required before this function can be called.

Remark

ocrypto_chacha20_poly1305_update_aad must be called before any call to ocrypto_chacha20_poly1305_update_enc or ocrypto_chacha20_poly1305_update_dec.

Parameters
  • ctx: Generator state.

  • a: Additional authenticated data.

  • a_len: Length of a.

void ocrypto_chacha20_poly1305_update_enc(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

SHA-ChaCha20-Poly1305 incremental encoder input.

The generator state ctx is updated to include a message chunk m.

This function can be called repeatedly until the whole message is processed.

Remark

Initialization of the generator state ctx through ocrypto_chacha20_poly1305_init is required before this function can be called.

Remark

ocrypto_chacha20_poly1305_update_enc must be called after any call to ocrypto_chacha20_poly1305_update_aad.

Remark

c and m can point to the same address.

Parameters
  • ctx: Generator state.

  • [out] c: Generated ciphertext. Same length as input message.

  • m: Message chunk.

  • m_len: Length of m.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

void ocrypto_chacha20_poly1305_update_dec(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t *m, const uint8_t *c, size_t c_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])

SHA-ChaCha20-Poly1305 incremental decoder input.

The generator state ctx is updated to include a cyphertext chunk c.

This function can be called repeatedly until the whole cyphertext is processed.

Remark

Initialization of the generator state ctx through ocrypto_chacha20_poly1305_init is required before this function can be called.

Remark

ocrypto_chacha20_poly1305_update_dec must be called after any call to ocrypto_chacha20_poly1305_update_aad.

Remark

m and c can point to the same address.

Parameters
  • ctx: Generator state.

  • [out] m: Decoded message. Same length as received ciphertext.

  • c: Cyphertext chunk.

  • c_len: Length of c.

  • n: Nonce.

  • n_len: Length of n. 0 <= n_len <= ocrypto_chacha20_poly1305_NONCE_BYTES_MAX.

  • k: Encryption key.

void ocrypto_chacha20_poly1305_final_enc(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t tag[(16)])

SHA-ChaCha20-Poly1305 final encoder step.

The generator state ctx is used to finalize the encryption and generate the tag.

Parameters
  • ctx: Generator state.

  • [out] tag: Generated authentication tag.

int ocrypto_chacha20_poly1305_final_dec(ocrypto_chacha20_poly1305_ctx *ctx, const uint8_t tag[(16)])

SHA-ChaCha20-Poly1305 final decoder step.

The generator state ctx is used to finalize the decryption and check the tag.

Parameters
  • ctx: Generator state.

  • tag: Received authentication tag.

Return Value
  • 0: If tag is valid.

  • -1: Otherwise.

Constant time APIs

group nrf_oberon_constant_time

Timing-invariant functions to use with cryptography.

Collection of timing-invariant implementations of basic functions.

Functions

int ocrypto_constant_time_equal(const void *x, const void *y, size_t length)

Variable length comparison.

Parameters
  • x: Memory region to compare with y.

  • y: Memory region to compare with x.

  • length: Number of bytes to compare, length > 0.

Return Value
  • 1: If x and y point to equal memory regions.

  • 0: Otherwise.

int ocrypto_constant_time_is_zero(const void *x, size_t length)

Variable length compare to zero.

Parameters
  • x: Pointer to memory region that will be compared.

  • length: Number of bytes to compare, length > 0.

Return Value
  • 1: If x is equal to a zero memory region.

  • 0: Otherwise.

void ocrypto_constant_time_copy(void *x, const void *y, size_t length)

Variable length copy.

Parameters
  • x: Pointer to memory region to copy y to.

  • y: Pointer to memory region to copy to x.

  • length: Number of bytes to copy, length > 0.

void ocrypto_constant_time_fill_zero(void *x, size_t length)

Variable length fill with zero.

Parameters
  • x: Pointer to memory region to be filled with zero.

  • length: Number of bytes to fill, length > 0.

ECC secp256r1 low-level APIs

group nrf_oberon_p256

Type declarations and APIs for low-level elliptic curve point operations based on the NIST secp256r1 curve.

Functions

int ocrypto_curve_p256_from32bytes(ocrypto_cp_p256 *r, const uint8_t p[32])

Load r.x from bytes, keep r.y.

Parameters
  • [out] r: Point with r.x loaded, r.y kept.

  • p: x as as array of bytes.

Return Value
  • 0: If r is a valid curve point.

  • -1: Otherwise.

int ocrypto_curve_p256_from64bytes(ocrypto_cp_p256 *r, const uint8_t p[64])

Load point from bytes.

Parameters
  • [out] r: Loaded point.

  • p: Point as array of bytes.

Return Value
  • 0: If r is a valid curve point.

  • -1: Otherwise.

void ocrypto_curve_p256_to32bytes(uint8_t r[32], ocrypto_cp_p256 *p)

Store p.x to bytes.

Parameters
  • [out] r: x stored as array.

  • p: Point with x to be stored.

void ocrypto_curve_p256_to64bytes(uint8_t r[64], ocrypto_cp_p256 *p)

Store p.x to bytes.

Parameters
  • [out] r: Point stored as array.

  • p: Point to be stored.

int ocrypto_curve_p256_scalarmult(ocrypto_cp_p256 *r, const ocrypto_cp_p256 *p, const ocrypto_sc_p256 *s)

P256 scalar multiplication.

r = p * s r = [0,0] if p = [0,0] or s mod q = 0

Parameters
  • [out] r: Output point.

  • p: Input point.

  • s: Scalar.

Return Value
  • -1: If r = [0,0].

  • 0: If 0 < s < q.

  • 1: If s > q.

int ocrypto_curve_p256_scalarmult_base(ocrypto_cp_p256 *r, const ocrypto_sc_p256 *s)

P256 scalar base multiplication.

r = basePoint * s r = [0,0] if s mod q = 0

Parameters
  • [out] r: Output point.

  • s: Scalar.

Return Value
  • -1: If r = [0,0].

  • 0: If 0 < s < q.

  • 1: If s > q.

ECC Curve25519 low-level APIs

group nrf_oberon_curve25519

Type declarations and APIs for low-level elliptic curve point operations based on Curve25519.

Curve25519 is an elliptic curve offering 128 bits of security. It is designed for use in the Elliptic Curve Diffie-Hellman (ECDH) key agreement scheme.

See

RFC 7748 - Elliptic Curves for Security

See

Curve25519: high-speed elliptic-curve cryptography

Defines

ocrypto_curve25519_SCALAR_BYTES

Length of a scalar.

ocrypto_curve25519_BYTES

Length of a curve point.

Functions

void ocrypto_curve25519_scalarmult_base(uint8_t r[(32)], const uint8_t n[(32)])

Curve25519 scalar multiplication r = n * basePoint.

Given a secret key n, the corresponding Curve25519 public key is computed and put into r.

The inverse of this function is difficult to compute.

Remark

r and n can point to the same address.

Parameters
  • [out] r: Resulting curve point.

  • [in] n: Scalar factor.

void ocrypto_curve25519_scalarmult(uint8_t r[(32)], const uint8_t n[(32)], const uint8_t p[(32)])

Curve25519 scalar multiplication r = n * p.

A shared secret is computed from the local secret key n and another party’s public key p and put into r. The same shared secret is generated when the other party combines its private key with the local public key.

Remark

r and n can point to the same address.

Parameters
  • [out] r: Resulting curve point.

  • [in] n: Scalar factor.

  • [in] p: Point factor.

ECDH APIs

group nrf_oberon_ecdh

APIs to do Elliptic Curve Diffie-Hellman using the NIST secp256r1 curve.

Functions

int ocrypto_ecdh_p256_public_key(uint8_t r[64], const uint8_t s[32])

ECDH P-256 public key generation r = n * p.

Given a secret key s the corresponding public key is computed and put into r.

Remark

r may be same as s.

Parameters
  • [out] r: Generated public key.

  • s: Secret key. Must be pre-filled with random data.

Return Value
  • 0: If s is a valid secret key.

  • -1: Otherwise.

int ocrypto_ecdh_p256_common_secret(uint8_t r[32], const uint8_t s[32], const uint8_t p[64])

ECDH P-256 common secret.

The common secret is computed from both the client’s public key p and the server’s secret key s and put into r.

Remark

r may be same as s or p.

Parameters
  • [out] r: Generated common secret.

  • s: Server private key.

  • p: Client public key.

Return Value
  • 0: If s is a valid secret key and p is a valid public key.

  • -1: Otherwise.

ECDSA APIs

group nrf_oberon_ecdsa

Type declarations and APIs to do Elliptic Curve Digital Signature Algorith using the NIST secp256r1 curve.

Functions

int ocrypto_ecdsa_p256_public_key(uint8_t pk[64], const uint8_t sk[32])

ECDSA P-256 public key generation.

Given a secret key sk the corresponding public key is computed and put into pk.

Parameters
  • [out] pk: Generated public key.

  • sk: Secret key. Must be pre-filled with random data.

Return Value
  • 0: If sk is a valid secret key.

  • -1: Otherwise.

int ocrypto_ecdsa_p256_sign(uint8_t sig[64], const uint8_t *m, size_t mlen, const uint8_t sk[32], const uint8_t ek[32])

ECDSA P-256 signature generation.

The message m is signed using the secret key sk and the ephemeral session key ek. The signature is put into sig.

Parameters
  • [out] sig: Generated signature.

  • m: Input message.

  • mlen: Length of m.

  • sk: Secret key.

  • ek: Ephemeral session key.

Return Value
  • 0: If ek is a valid session key.

  • -1: Otherwise.

int ocrypto_ecdsa_p256_sign_hash(uint8_t sig[64], const uint8_t hash[32], const uint8_t sk[32], const uint8_t ek[32])

ECDSA P-256 signature generation from SHA256 hash.

The message hash hash is signed using the secret key sk and the ephemeral session key ek. The signature is put into sig.

Parameters
  • [out] sig: Generated signature.

  • hash: Input hash.

  • sk: Secret key.

  • ek: Ephemeral session key.

Return Value
  • 0: If ek is a valid session key.

  • -1: Otherwise.

int ocrypto_ecdsa_p256_verify(const uint8_t sig[64], const uint8_t *m, size_t mlen, const uint8_t pk[64])

ECDSA P-256 signature verification.

The signature sig of the input message m is verified using the signer’s public key pk.

Parameters
  • sig: Input signature.

  • m: Input message.

  • mlen: Length of m.

  • pk: Signer’s public key.

Return Value
  • 0: If the signature is valid.

  • -1: Otherwise.

int ocrypto_ecdsa_p256_verify_hash(const uint8_t sig[64], const uint8_t hash[32], const uint8_t pk[64])

ECDSA P-256 signature verification from SHA256 hash.

The signature sig of the message hash hash is verified using the signer’s public key pk.

Parameters
  • sig: Input signature.

  • hash: Input hash.

  • pk: Signer’s public key.

Return Value
  • 0: If the signature is valid.

  • -1: Otherwise.

Ed25519 APIs

group nrf_oberon_ed25519

Type declarations and APIs for the Ed25519 algorithm.

Ed25519 is a specific implementation of EdDSA, a digital signature scheme. EdDSA is based on Twisted Edwards curves and is designed to be faster than existing digital signature schemes without sacrificing security. It was developed by Daniel J. Bernstein, et al. Ed25519 is intended to provide attack resistance comparable to quality 128-bit symmetric ciphers.

See

Ed25519: high-speed high-security signatures

Defines

ocrypto_ed25519_PUBLIC_KEY_BYTES

Length of a public key.

ocrypto_ed25519_SECRET_KEY_BYTES

Length of a secret key.

ocrypto_ed25519_BYTES

Length of a signature.

Functions

void ocrypto_ed25519_public_key(uint8_t pk[(32)], const uint8_t sk[(32)])

Ed25519 signature key pair generation.

Given a secret key sk, the corresponding public key is computed and put into pk. The key pair can then be used to sign and verify message signatures.

Parameters
  • [out] pk: Generated public key.

  • sk: Secret key. Must be pre-filled with random data.

void ocrypto_ed25519_sign(uint8_t sig[(64)], const uint8_t *m, size_t m_len, const uint8_t sk[(32)], const uint8_t pk[(32)])

Ed25519 signature generate.

The message m is signed using the secret key sk and the corresponding public key pk. The signature is put into sig.

Parameters
  • [out] sig: Generated signature.

  • m: Input message.

  • m_len: Length of m.

  • sk: Secret key.

  • pk: Public key.

int ocrypto_ed25519_verify(const uint8_t sig[(64)], const uint8_t *m, size_t m_len, const uint8_t pk[(32)])

Ed25519 signature verification.

The signature sig of the input message m is verified using the signer’s public key pk.

Parameters
  • sig: Input signature.

  • m: Input message.

  • m_len: Length of m.

  • pk: Signer’s public key.

Return Value
  • 0: If the signature is valid.

  • -1: Otherwise.

HKDF - HMAC based Key Derivation Function

group nrf_oberon_hkdf

HKDF is a key derivation function based on HMAC Extract-and-Expand.

HKDF APIs using SHA-256

group nrf_oberon_hkdf_256

Type declarations and APIs for the HKDF-SHA256 algorithm.

HKDF-SHA256 is a key derivation function based on HMAC-SHA256.

See

RFC 5869 - HMAC-based Extract-and-Expand Key Derivation Function (HKDF)

Defines

ocrypto_hkdf_sha256_LENGTH_MAX

Maximum length of a derived key.

ocrypto_hkdf_sha256_SALT_LENGTH_MAX

Maximum salt length.

Functions

void ocrypto_hkdf_sha256(uint8_t *r, size_t r_len, const uint8_t *key, size_t key_len, const uint8_t *salt, size_t salt_len, const uint8_t *info, size_t info_len)

HKDF-SHA256 algorithm.

A new pseudo-random key of length r_len is derived from an input key key, a salt salt and additional information info. The new key is put into r.

Parameters
  • [out] r: Output key.

  • r_len: Length of r, 0 < r_len <= ocrypto_hkdf_sha256_LENGTH_MAX.

  • key: Input key.

  • key_len: Length of key.

  • salt: Salt.

  • salt_len: Length of salt salt. 0 <= salt_len <= ocrypto_hkdf_sha256_SALT_LENGTH_MAX.

  • info: Additional information.

  • info_len: Length of info.

HKDF APIs using SHA-512

group nrf_oberon_hkdf_512

Type declaration and APIs for the HKDF-SHA512 algorithm.

HKDF-SHA512 is a key derivation function based on HMAC-SHA512.

See

RFC 5869 - HMAC-based Extract-and-Expand Key Derivation Function (HKDF)

Defines

ocrypto_hkdf_sha512_LENGTH_MAX

Maximum length of a derived key.

ocrypto_hkdf_sha512_SALT_LENGTH_MAX

Maximum salt length.

Functions

void ocrypto_hkdf_sha512(uint8_t *r, size_t r_len, const uint8_t *key, size_t key_len, const uint8_t *salt, size_t salt_len, const uint8_t *info, size_t info_len)

HKDF-SHA512 algorithm.

A new pseudo-random key of length r_len is derived from an input key key, a salt salt and additional information info. The new key is put into r.

Parameters
  • [out] r: Output key.

  • r_len: Length of r, 0 < r_len <= ocrypto_hkdf_sha512_LENGTH_MAX.

  • key: Input key.

  • key_len: Length of key.

  • salt: Salt.

  • salt_len: Length of salt salt. 0 <= salt_len <= ocrypto_hkdf_sha512_SALT_LENGTH_MAX.

  • info: Additional information.

  • info_len: Length of info.

HMAC - Hash-based Aessage Authentication Code

group nrf_oberon_hmac

HMAC is a hash-based Message Authentication Code utilizing a secure hash function.

HMAC APIs using SHA-256

group nrf_oberon_hmac_256

Type declarations and APIs for the HMAC-SHA256 algorithm.

HMAC-SHA256 is an algorithm for message authentication using the cryptographic hash function SHA256 and a reusable secret key. Users in possession of the key can verify the integrity and authenticity of the message.

See

RFC 2104 - HMAC: Keyed-Hashing for Message Authentication

Incremental HMAC-SHA256 generator.

This group of functions can be used to incrementally compute HMAC-SHA256 for a given message.

void ocrypto_hmac_sha256_init(ocrypto_hmac_sha256_ctx *ctx, const uint8_t *key, size_t key_len)

HMAC-SHA256 initialization.

The generator state ctx is initialized by this function.

Parameters
  • [out] ctx: Generator state.

  • key: HMAC key.

  • key_len: Length of key.

void ocrypto_hmac_sha256_update(ocrypto_hmac_sha256_ctx *ctx, const uint8_t *in, size_t in_len)

HMAC-SHA256 incremental data input.

The generator state ctx is updated to hash a message chunk in.

This function can be called repeatedly until the whole message is processed.

Remark

Initialization of the generator state ctx through ocrypto_hmac_sha256_init is required before this function can be called.

Parameters
  • [inout] ctx: Generator state.

  • in: Input data.

  • in_len: Length of in.

void ocrypto_hmac_sha256_final(ocrypto_hmac_sha256_ctx *ctx, uint8_t r[(32)])

HMAC-SHA256 output.

The generator state ctx is updated to finalize the HMAC calculation. The HMAC digest is put into r.

Remark

Initialization of the generator state ctx through ocrypto_hmac_sha256_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_hmac_sha256_update and ocrypto_hmac_sha256_final unless it is reinitialized using ocrypto_hmac_sha256_init.

Parameters
  • [inout] ctx: Generator state.

  • [out] r: Generated HMAC digest.

Defines

ocrypto_hmac_sha256_KEY_BYTES_MAX

Maximum key length.

ocrypto_hmac_sha256_BYTES

Length of the authenticator.

Functions

void ocrypto_hmac_sha256(uint8_t r[(32)], const uint8_t *key, size_t key_len, const uint8_t *in, size_t in_len)

HMAC-SHA256 algorithm.

The input message in is authenticated using the key k. The computed authenticator is put into r. To verify the authenticator, the recipient needs to recompute the HMAC authenticator and can then compare it with the received authenticator.

Parameters
  • [out] r: HMAC output.

  • key: HMAC key.

  • key_len: Length of key. 0 <= key_len <= ocrypto_hmac_sha256_KEY_BYTES_MAX.

  • in: Input data.

  • in_len: Length of in.

HMAC APIs using SHA-512

group nrf_oberon_hmac_512

Type declarations and APIs for the HMAC-SHA512 algorithm.

HMAC-SHA512 is an algorithm for message authentication using the cryptographic hash function SHA512 and a reusable secret key. Users in possession of the key can verify the integrity and authenticity of the message.

See

RFC 2104 - HMAC: Keyed-Hashing for Message Authentication

Incremental HMAC-SHA512 generator.

This group of functions can be used to incrementally compute HMAC-SHA512 for a given message.

void ocrypto_hmac_sha512_init(ocrypto_hmac_sha512_ctx *ctx, const uint8_t *key, size_t key_len)

HMAC-SHA512 initialization.

The generator state ctx is initialized by this function.

Parameters
  • [out] ctx: Generator state.

  • key: HMAC key.

  • key_len: Length of key.

void ocrypto_hmac_sha512_update(ocrypto_hmac_sha512_ctx *ctx, const uint8_t *in, size_t in_len)

HMAC-SHA512 incremental data input.

The generator state ctx is updated to hash a message chunk in.

This function can be called repeatedly until the whole message is processed.

Remark

Initialization of the generator state ctx through ocrypto_hmac_sha512_init is required before this function can be called.

Parameters
  • [inout] ctx: Generator state.

  • in: Input data.

  • in_len: Length of in.

void ocrypto_hmac_sha512_final(ocrypto_hmac_sha512_ctx *ctx, uint8_t r[(64)])

HMAC-SHA512 output.

The generator state ctx is updated to finalize the HMAC calculation. The HMAC digest is put into r.

Remark

Initialization of the generator state ctx through ocrypto_hmac_sha512_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_hmac_sha512_update and ocrypto_hmac_sha512_final unless it is reinitialized using ocrypto_hmac_sha512_init.

Parameters
  • [inout] ctx: Generator state.

  • [out] r: Generated HMAC digest.

Defines

ocrypto_hmac_sha512_KEY_BYTES_MAX

Maximum key length.

ocrypto_hmac_sha512_BYTES

Length of the authenticator.

Functions

void ocrypto_hmac_sha512(uint8_t r[(64)], const uint8_t *key, size_t key_len, const uint8_t *in, size_t in_len)

HMAC-SHA512 algorithm.

The input message in is authenticated using the key k. The computed authenticator is put into r. To verify the authenticator, the recipient needs to recompute the HMAC authenticator and can then compare it with the received authenticator.

Parameters
  • [out] r: HMAC output.

  • key: HMAC key.

  • key_len: Length of key. 0 <= key_len <= ocrypto_hmac_sha512_KEY_BYTES_MAX.

  • in: Input data.

  • in_len: Length of in.

RSA - Rivest-Shamir-Adleman algorithm

group nrf_oberon_rsa

RSA is a number theoretic public-key encryption and signature algorithm.

RSA APIs

group nrf_oberon_rsa_api

APIs to for RSA encryption/decryption and sign/verify using PKCS1 v1.5, OEAP and PSS.

These functions support RSA encryption and signatures with 1024 and 2048-bit modulo and PKCS1 V1.5 padding.

1024-bit RSA Functions.

This group of functions is used for 1024-bit RSA.

int ocrypto_rsa1024_pkcs1_v15_encrypt(uint8_t c[128], const uint8_t *m, size_t mlen, const uint8_t *seed, size_t slen, const ocrypto_rsa1024_pub_key *pk)

1024 bit RSA PKCS1 V1.5 encryption.

The message m is encrypted to a ciphertext returned in c.

Remark

The key pk should be initialized with ocrypto_rsa1024_init_pub_key.

Remark

The seed should consist of non-zero random bytes.

Remark

c and m can point to the same address.

Parameters
  • [out] c: The generated 128-byte ciphertext.

  • m: The message to be encrypted.

  • mlen: Length of m. 0 <= mlen <= 117.

  • seed: The random seed to be used for the padding.

  • slen: Length of seed. slen >= 125 - mlen.

  • pk: A valid 1024-bit RSA public key.

Return Value
  • -1: If the message is too long (mlen > 117).

  • -2: If the seed is too short (slen < 125 - mlen).

  • 0: Otherwise.

int ocrypto_rsa1024_pkcs1_v15_decrypt(uint8_t *m, size_t mlen, const uint8_t c[128], const ocrypto_rsa1024_key *k)

1024-bit RSA PKCS1 V1.5 decryption.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa1024_init_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 128-byte ciphertext to decrypt.

  • k: A valid 1024-bit RSA secret key.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa1024_pkcs1_v15_crt_decrypt(uint8_t *m, size_t mlen, const uint8_t c[128], const ocrypto_rsa1024_crt_key *k)

1024-bit RSA PKCS1 V1.5 decryption with CRT acceleration.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 128-byte ciphertext to decrypt.

  • k: A valid 1024-bit RSA secret key with CRT coefficients.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa1024_oaep_sha256_encrypt(uint8_t c[128], const uint8_t *m, size_t mlen, const uint8_t *label, size_t llen, const uint8_t seed[32], const ocrypto_rsa1024_pub_key *pk)

1024-bit RSA OAEP SHA256 encryption.

The message m is encrypted to a ciphertext returned in c.

Remark

The key pk should be initialized with ocrypto_rsa1024_init_pub_key.

Remark

c and m can point to the same address.

Parameters
  • [out] c: The generated 128-byte ciphertext.

  • m: The message to be encrypted.

  • mlen: Length of m. 0 <= mlen <= 62.

  • label: The label associated with the message.

  • llen: Length of label. May be 0.

  • seed: 32-byte random seed.

  • pk: A valid 1024-bit RSA public key.

Return Value
  • -1: If the message is too long (mlen > 62).

  • 0: Otherwise.

int ocrypto_rsa1024_oaep_sha256_decrypt(uint8_t *m, size_t mlen, const uint8_t c[128], const uint8_t *label, size_t llen, const ocrypto_rsa1024_key *k)

1024-bit RSA OAEP SHA256 decryption.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa1024_init_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 128-byte ciphertext to decrypt.

  • label: The label associated with the message.

  • llen: Length of label. May be 0.

  • k: A valid 1024-bit RSA secret key.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa1024_oaep_sha256_crt_decrypt(uint8_t *m, size_t mlen, const uint8_t c[128], const uint8_t *label, size_t llen, const ocrypto_rsa1024_crt_key *k)

1024-bit RSA OAEP SHA256 decryption with CRT acceleration.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 128-byte ciphertext to decrypt.

  • label: The label associated with the message.

  • llen: Length of label. May be 0.

  • k: A valid 1024-bit RSA secret key with CRT coefficients.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa1024_pkcs1_v15_sha256_sign(uint8_t s[128], const uint8_t *m, size_t mlen, const ocrypto_rsa1024_key *k)

1024-bit RSA PKCS1 V1.5 SHA-256 sign.

The message m is signed and the signature returned in s.

Return

0

Remark

The key k should be initialized with ocrypto_rsa1024_init_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 128-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • k: A valid 1024-bit RSA secret key.

int ocrypto_rsa1024_pkcs1_v15_sha256_crt_sign(uint8_t s[128], const uint8_t *m, size_t mlen, const ocrypto_rsa1024_crt_key *k)

1024-bit RSA PKCS1 V1.5 SHA-256 sign with CRT acceleration.

The message m is signed and the signature returned in s.

Return

0

Remark

The key k should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 128-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • k: A valid 1024-bit RSA secret key with CRT coefficients.

int ocrypto_rsa1024_pkcs1_v15_sha256_verify(const uint8_t s[128], const uint8_t *m, size_t mlen, const ocrypto_rsa1024_pub_key *pk)

1024-bit RSA PKCS1 V1.5 SHA-256 signature verify.

The signature s is verified for a valid signature of message m.

Remark

The key pk should be initialized with ocrypto_rsa1024_init_pub_key.

Parameters
  • s: The 128-byte signature.

  • m: The signed message.

  • mlen: Length of m.

  • pk: A valid 1024-bit RSA public key.

Return Value
  • 0: If the signature is valid.

  • -1: If verification failed.

int ocrypto_rsa1024_pss_sha256_sign(uint8_t s[128], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa1024_key *k)

1024-bit RSA PSS SHA-256 sign.

The message m is signed and the signature returned in s.

Remark

The key k should be initialized with ocrypto_rsa1024_init_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 128-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • salt: The salt to be used.

  • slen: Length of salt.

  • k: A valid 1024-bit RSA secret key.

Return Value
  • -2: If the salt is too long.

  • 0: Otherwise.

int ocrypto_rsa1024_pss_sha256_crt_sign(uint8_t s[128], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa1024_crt_key *k)

1024-bit RSA PSS SHA-256 sign with CRT acceleration.

The message m is signed and the signature returned in s.

Remark

The key k should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 128-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • salt: The salt to be used.

  • slen: Length of salt.

  • k: A valid 1024-bit RSA secret key with CRT coefficients.

Return Value
  • -2: If the salt is too long.

  • 0: Otherwise.

int ocrypto_rsa1024_pss_sha256_verify(const uint8_t s[128], const uint8_t *m, size_t mlen, size_t slen, const ocrypto_rsa1024_pub_key *pk)

1024-bit RSA PSS SHA-256 signature verify.

The signature s is verified for a valid signature of message m.

Remark

The key pk should be initialized with ocrypto_rsa1024_init_pub_key.

Parameters
  • s: The 128-byte signature.

  • m: The signed message.

  • mlen: Length of m.

  • slen: The length of the salt.

  • pk: A valid 1024-bit RSA public key.

Return Value
  • 0: If the signature is valid.

  • -1: If verification failed.

  • -2: If the salt is too long.

2048-bit RSA Functions.

This group of functions is used for 2048-bit RSA.

int ocrypto_rsa2048_pkcs1_v15_encrypt(uint8_t c[256], const uint8_t *m, size_t mlen, const uint8_t *seed, size_t slen, const ocrypto_rsa2048_pub_key *pk)

2048-bit RSA PKCS1 V1.5 encryption.

The message m is encrypted to a ciphertext returned in c.

Remark

The key pk should be initialized with ocrypto_rsa2048_init_pub_key.

Remark

The seed should consist of non-zero random bytes.

Remark

c and m can point to the same address.

Parameters
  • [out] c: The generated 256-byte ciphertext.

  • m: The message to be encrypted.

  • mlen: Length of m. 0 <= mlen <= 245.

  • seed: The random seed to be used for the padding.

  • slen: Length of seed. slen >= 253 - mlen.

  • pk: A valid 2048-bit RSA public key.

Return Value
  • -1: If the message is too long (mlen > 245).

  • -2: If the seed is too short (slen < 253 - mlen).

  • 0: Otherwise.

int ocrypto_rsa2048_pkcs1_v15_decrypt(uint8_t *m, size_t mlen, const uint8_t c[256], const ocrypto_rsa2048_key *k)

2048-bit RSA PKCS1 V1.5 decryption.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa2048_init_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 256-byte ciphertext to decrypt.

  • k: A valid 2048-bit RSA secret key.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa2048_pkcs1_v15_crt_decrypt(uint8_t *m, size_t mlen, const uint8_t c[256], const ocrypto_rsa2048_crt_key *k)

2048-bit RSA PKCS1 V1.5 decryption with CRT acceleration.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 256-byte ciphertext to decrypt.

  • k: A valid 2048-bit RSA secret key with CRT coefficients.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa2048_oaep_sha256_encrypt(uint8_t c[256], const uint8_t *m, size_t mlen, const uint8_t *label, size_t llen, const uint8_t seed[32], const ocrypto_rsa2048_pub_key *pk)

2048-bit RSA OAEP SHA256 encryption.

The message m is encrypted to a ciphertext returned in c.

Remark

The key pk should be initialized with ocrypto_rsa2048_init_pub_key.

Remark

c and m can point to the same address.

Parameters
  • [out] c: The generated 256-byte ciphertext.

  • m: The message to be encrypted.

  • mlen: Length of m. 0 <= mlen <= 190.

  • label: The label associated with the message.

  • llen: Length of label. May be 0.

  • seed: 32-byte random seed.

  • pk: A valid 2048-bit RSA public key.

Return Value
  • -1: If the message is too long (mlen > 190).

  • 0: Otherwise.

int ocrypto_rsa2048_oaep_sha256_decrypt(uint8_t *m, size_t mlen, const uint8_t c[256], const uint8_t *label, size_t llen, const ocrypto_rsa2048_key *k)

2048-bit RSA OAEP SHA256 decryption.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa2048_init_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 256-byte ciphertext to decrypt.

  • label: The label associated with the message.

  • llen: Length of label. May be 0.

  • k: A valid 2048-bit RSA secret key.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa2048_oaep_sha256_crt_decrypt(uint8_t *m, size_t mlen, const uint8_t c[256], const uint8_t *label, size_t llen, const ocrypto_rsa2048_crt_key *k)

2048-bit RSA OAEP SHA256 decryption with CRT acceleration.

The ciphertext c is decrypted to the message returned in m.

Remark

The key k should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

m and c can point to the same address.

Parameters
  • [out] m: The decrypted message. The buffer must be long enough to hold the message.

  • mlen: Length of m.

  • c: The 256-byte ciphertext to decrypt.

  • label: The label associated with the message.

  • llen: Length of label. May be 0.

  • k: A valid 2048-bit RSA secret key with CRT coefficients.

Return Value
  • -1: If decryption failed.

  • -2: If the output buffer is too short (mlen < length of message).

  • n: If a message of length n was successfully decrypted.

int ocrypto_rsa2048_pkcs1_v15_sha256_sign(uint8_t s[256], const uint8_t *m, size_t mlen, const ocrypto_rsa2048_key *k)

2048-bit RSA PKCS1 V1.5 SHA-256 sign.

The message m is signed and the signature returned in s.

Return

0

Remark

The key k should be initialized with ocrypto_rsa2048_init_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 256-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • k: A valid 2048-bit RSA secret key.

int ocrypto_rsa2048_pkcs1_v15_sha256_crt_sign(uint8_t s[256], const uint8_t *m, size_t mlen, const ocrypto_rsa2048_crt_key *k)

2048-bit RSA PKCS1 V1.5 SHA-256 sign with CRT acceleration.

The message m is signed and the signature returned in s.

Return

0

Remark

The key k should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 256-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • k: A valid 2048-bit RSA secret key with CRT coefficients.

int ocrypto_rsa2048_pkcs1_v15_sha256_verify(const uint8_t s[256], const uint8_t *m, size_t mlen, const ocrypto_rsa2048_pub_key *pk)

2048-bit RSA PKCS1 V1.5 SHA-256 signature verify.

The signature s is verified for a correct signature of message m.

Remark

The key pk should be initialized with ocrypto_rsa2048_init_pub_key.

Parameters
  • s: The 256-byte signature.

  • m: The signed message.

  • mlen: Length of m.

  • pk: A valid 2048-bit RSA public key.

Return Value
  • 0: If the signature is valid.

  • -1: If verification failed.

int ocrypto_rsa2048_pss_sha256_sign(uint8_t s[256], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa2048_key *k)

2048-bit RSA PSS SHA-256 sign.

The message m is signed and the signature returned in s.

Remark

The key k should be initialized with ocrypto_rsa2048_init_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 256-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • salt: The salt to be used.

  • slen: Length of salt.

  • k: A valid 2048-bit RSA secret key.

Return Value
  • -2: If the salt is too long.

  • 0: Otherwise.

int ocrypto_rsa2048_pss_sha256_crt_sign(uint8_t s[256], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa2048_crt_key *k)

2048-bit RSA PSS SHA-256 sign with CRT acceleration.

The message m is signed and the signature returned in s.

Remark

The key k should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

s and m can point to the same address.

Parameters
  • [out] s: The generated 256-byte signature.

  • m: The message to be signed.

  • mlen: Length of m.

  • salt: The salt to be used.

  • slen: Length of salt.

  • k: A valid 2048-bit RSA secret key with CRT coefficients.

Return Value
  • -2: If the salt is too long.

  • 0: Otherwise.

int ocrypto_rsa2048_pss_sha256_verify(const uint8_t s[256], const uint8_t *m, size_t mlen, size_t slen, const ocrypto_rsa2048_pub_key *pk)

2048-bit RSA PSS SHA-256 signature verify.

The signature s is verified for a valid signature of message m.

Remark

The key pk should be initialized with ocrypto_rsa2048_init_pub_key.

Parameters
  • s: The 256-byte signature.

  • m: The signed message.

  • mlen: Length of m.

  • slen: The length of the salt.

  • pk: A valid 2048-bit RSA public key.

Return Value
  • 0: If the signature is valid.

  • -1: If verification failed.

  • -2: If the salt is too long.

RSA key APIs

group nrf_oberon_rsa_key

Type declarations for RSA APIs.

RSA is a number theoretic public-key encryption and signature algorithm.

These functions support the setup of 1024 and 2048 RSA secret and public keys.

1024-bit RSA key setup

This group of functions is used for 1024-bit RSA key setup.

int ocrypto_rsa1024_init_pub_key(ocrypto_rsa1024_pub_key *k, const uint8_t *n, size_t nlen)

1024-bit RSA public key setup.

Remark

The public exponent is fixed at 65537.

Parameters
  • [out] k: The initialized public key.

  • n: The RSA modulus. Must be exactly 1024 bits.

  • nlen: Length of n.

Return Value
  • -1: If the input length is invalid.

  • 0: Otherwise.

int ocrypto_rsa1024_init_key(ocrypto_rsa1024_key *k, const uint8_t *n, size_t nlen, const uint8_t *d, size_t dlen)

1024-bit RSA secret key setup.

Parameters
  • [out] k: The initialized public key.

  • n: The RSA modulus. Must be exactly 1024 bits.

  • nlen: Length of n.

  • d: The secret exponent. Must be <= 1024 bits.

  • dlen: Length of d.

Return Value
  • -1: If the input length is invalid.

  • 0: Otherwise.

int ocrypto_rsa1024_init_crt_key(ocrypto_rsa1024_crt_key *k, const uint8_t *p, size_t plen, const uint8_t *q, size_t qlen, const uint8_t *dp, size_t dplen, const uint8_t *dq, size_t dqlen, const uint8_t *qinv, size_t qilen)

1024-bit RSA secret key setup with CRT coefficients.

Parameters
  • [out] k: The initialized secret key.

  • p: The 1. RSA prime. Must be exactly 512 bits.

  • plen: Length of p.

  • q: The 2. RSA prime. Must be exactly 512 bits.

  • qlen: Length of q.

  • dp: The 1. CRT exponent. dp = d mod (p-1).

  • dplen: Length of dp.

  • dq: The 2. CRT exponent. dq = d mod (q-1).

  • dqlen: Length of dq.

  • qinv: The CRT coefficient. qinv = 1/q mod p.

  • qilen: Length of qinv.

Return Value
  • -1: If the input length is invalid.

  • 0: Otherwise.

2048-bit RSA key setup

This group of functions is used for 2048-bit RSA key setup.

int ocrypto_rsa2048_init_pub_key(ocrypto_rsa2048_pub_key *k, const uint8_t *n, size_t nlen)

2048-bit RSA public key setup.

Remark

The public exponent is fixed at 65537.

Parameters
  • [out] k: The initialized public key.

  • n: The RSA modulus. Must be exactly 2048 bits.

  • nlen: Length of n.

Return Value
  • -1: If the input length is invalid.

  • 0: Otherwise.

int ocrypto_rsa2048_init_key(ocrypto_rsa2048_key *k, const uint8_t *n, size_t nlen, const uint8_t *d, size_t dlen)

2048-bit RSA secret key setup.

Parameters
  • [out] k: The initialized public key.

  • n: The RSA modulus. Must be exactly 2048 bits.

  • nlen: Length of n.

  • d: The secret exponent. Must be <= 2048 bits.

  • dlen: Length of d.

Return Value
  • -1: If the input length is invalid.

  • 0: Otherwise.

int ocrypto_rsa2048_init_crt_key(ocrypto_rsa2048_crt_key *k, const uint8_t *p, size_t plen, const uint8_t *q, size_t qlen, const uint8_t *dp, size_t dplen, const uint8_t *dq, size_t dqlen, const uint8_t *qinv, size_t qilen)

2048-bit RSA secret key setup with CRT coefficients.

Parameters
  • [out] k: The initialized secret key.

  • p: The 1. RSA prime. Must be exactly 1024 bits.

  • plen: Length of p.

  • q: The 2. RSA prime. Must be exactly 1024 bits.

  • qlen: Length of q.

  • dp: The 1. CRT exponent. dp = d mod (p-1).

  • dplen: Length of dp.

  • dq: The 2. CRT exponent. dq = d mod (q-1).

  • dqlen: Length of dq.

  • qinv: The CRT coefficient. qinv = 1/q mod p.

  • qilen: Length of qinv.

Return Value
  • -1: If the input length is invalid.

  • 0: Otherwise.

Defines

PUB_EXP

The Public RSA Exponent.

struct ocrypto_rsa1024_pub_key
#include <ocrypto_rsa_key.h>

1024-bit RSA public key.

struct ocrypto_rsa1024_key
#include <ocrypto_rsa_key.h>

1024 bit RSA secret key.

struct ocrypto_rsa1024_crt_key
#include <ocrypto_rsa_key.h>

1024-bit RSA secret key with CRT coefficients.

struct ocrypto_rsa2048_pub_key
#include <ocrypto_rsa_key.h>

2048-bit RSA public key.

struct ocrypto_rsa2048_key
#include <ocrypto_rsa_key.h>

2048-bit RSA secret key.

struct ocrypto_rsa2048_crt_key
#include <ocrypto_rsa_key.h>

2048-bit RSA secret key with CRT coefficients.

SHA-256 APIs

group nrf_oberon_sha_256

Type declarations and APIs for the SHA-256 algorithm.

SHA-256 is part of the SHA-2 family that is a set of cryptographic hash functions designed by the NSA. It is the successor of the SHA-1 algorithm.

A fixed-sized message digest is computed from variable length input data. The function is practically impossible to revert, and small changes in the input message lead to major changes in the message digest.

Incremental SHA-256 generator

This group of functions can be used to incrementally compute the SHA-256 hash for a given message.

void ocrypto_sha256_init(ocrypto_sha256_ctx *ctx)

SHA-256 initialization.

The generator state ctx is initialized by this function.

Parameters
  • [out] ctx: Generator state.

void ocrypto_sha256_update(ocrypto_sha256_ctx *ctx, const uint8_t *in, size_t in_len)

SHA-256 incremental data input.

The generator state ctx is updated to hash a message chunk in.

This function can be called repeatedly until the whole message is processed.

Remark

Initialization of the generator state ctx through ocrypto_sha256_init is required before this function can be called.

Parameters
  • ctx: Generator state.

  • in: Input data.

  • in_len: Length of in.

void ocrypto_sha256_final(ocrypto_sha256_ctx *ctx, uint8_t r[(32)])

SHA-256 output.

The generator state ctx is updated to finalize the hash for the previously processed message chunks. The hash is put into r.

Remark

Initialization of the generator state ctx through ocrypto_sha256_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_sha256_update and ocrypto_sha256_final unless it is reinitialized using ocrypto_sha256_init.

Parameters
  • ctx: Generator state.

  • [out] r: Generated hash value.

Defines

ocrypto_sha256_BYTES

Length of SHA-256 hash.

Functions

void ocrypto_sha256(uint8_t r[(32)], const uint8_t *in, size_t in_len)

SHA-256 hash.

The SHA-256 hash of a given input message in is computed and put into r.

Parameters
  • [out] r: Generated hash.

  • in: Input data.

  • in_len: Length of in.

SHA-512 APIs

group nrf_oberon_sha_512

Type declarations and APIs for the SHA-512 algorithm.

SHA-512 is part of the SHA-2 family that is a set of cryptographic hash functions designed by the NSA. It is the successor of the SHA-1 algorithm.

A fixed-sized message digest is computed from variable length input data. The function is practically impossible to revert, and small changes in the input message lead to major changes in the message digest.

Incremental SHA-512 generator

This group of functions can be used to incrementally compute the SHA-512 hash for a given message.

void ocrypto_sha512_init(ocrypto_sha512_ctx *ctx)

SHA-512 initialization.

The generator state ctx is initialized by this function.

Parameters
  • [out] ctx: Generator state.

void ocrypto_sha512_update(ocrypto_sha512_ctx *ctx, const uint8_t *in, size_t in_len)

SHA-512 incremental data input.

The generator state ctx is updated to hash a message chunk in.

This function can be called repeatedly until the whole message is processed.

Remark

Initialization of the generator state ctx through ocrypto_sha512_init is required before this function can be called.

Parameters
  • ctx: Generator state.

  • in: Input data.

  • in_len: Length of in.

void ocrypto_sha512_final(ocrypto_sha512_ctx *ctx, uint8_t r[(64)])

SHA-512 output.

The generator state ctx is updated to finalize the hash for the previously processed message chunks. The hash is put into r.

Remark

Initialization of the generator state ctx through ocrypto_sha512_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_sha512_update and ocrypto_sha512_final unless it is reinitialized using ocrypto_sha512_init.

Parameters
  • ctx: Generator state.

  • [out] r: Generated hash value.

Defines

ocrypto_sha512_BYTES

Length of SHA-512 hash.

Functions

void ocrypto_sha512(uint8_t r[(64)], const uint8_t *in, size_t in_len)

SHA-512 hash.

The SHA-512 hash of a given input message in is computed and put into r.

Parameters
  • [out] r: Generated hash.

  • in: Input data.

  • in_len: Length of in.

SRP - Secure Remote Password APIs

group nrf_oberon_srp

Type declarations and APIs for the SRP key agreement protocol.

SRP is an augmented password-authenticated key agreement protocol, specifically designed to work around existing patents. SRP allows the use of user names and passwords over unencrypted channels and supplies a shared secret at the end of the authentication sequence that can be used to generate encryption keys.

An eavesdropper or man in the middle cannot obtain enough information to be able to brute force guess a password without further interactions with the parties for each guess.

The server does not store password-equivalent data. This means that an attacker who steals the server data cannot masquerade as the client unless they first perform a brute force search for the password.

The specific variant implemented here is SRP-6 3072 bit SHA-512.

Basic protocol overview

See

RFC 5054 - Using the Secure Remote Password (SRP) Protocol for TLS Authentication

See

The Stanford SRP Homepage

Setup

  1. Server generates a username / password combination together with a salt.

  2. Server derives a password verifier (see ocrypto_srp_verifier).

  3. The username, salt and verifier are stored and required to open sessions. The original password is no longer needed.

Session opening

  1. Client sends a username and the public key of an ephemeral key pair to the server.

  2. Server sends the salt and the public key of another ephemeral key pair to the client (see ocrypto_srp_public_key).

  3. Client and Server both compute the session key from this information (see ocrypto_srp_scrambling_parameter, ocrypto_srp_premaster_secret, ocrypto_srp_session_key).

  4. Client sends proof of the session key to the server.

  5. Server validates proof (see ocrypto_srp_proof_m1), then sends proof of the session key to the client (see ocrypto_srp_proof_m2).

  6. Client validates proof. Both parties know that they share the same private session key.

SRP-6 Password verifier generation

A password verifier is generated from a user name and a password. The password pass may be discarded, as only the verifier is used during later computations.

void ocrypto_srp_verifier(uint8_t v[(384)], const uint8_t salt[(16)], const uint8_t *user, size_t user_len, const uint8_t *pass, size_t pass_len)

SRP-6 Password Verifier.

The verifier is generated for a given user name user, a password pass and salt salt.

Parameters
  • [out] v: Generated password verifier, must be 32-bit aligned.

  • salt: Salt.

  • user: User name.

  • user_len: Length of user.

  • pass: Password.

  • pass_len: Length of pass.

SRP-6 Public key generation

An ephemeral keypair can be generated based on the password verifier to be used when opening a new session.

void ocrypto_srp_public_key(uint8_t pub_b[(384)], const uint8_t priv_b[(32)], const uint8_t v[(384)])

SRP-6 Public Key.

The public key for a given private key priv_b is generated using the password verifier v and put into pub_b.

Parameters
  • [out] pub_b: Generated public key, must be 32-bit aligned.

  • priv_b: Private key.

  • v: Password verifier.

SRP-6 Session key generation

A premaster secret can be derived from both the client’s and server’s public keys, the server’s private key and the password verifier. A shared session key can be generated from this premaster secret.

void ocrypto_srp_scrambling_parameter(uint8_t u[(64)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)])

SRP-6 Scrambling Parameter.

The scrambling parameter is computed from both the client’s public key pub_a and the server’s public key pub_b. The scrambling parameter is required to compute the premaster secret.

Parameters
  • [out] u: Generated scrambling parameter.

  • pub_a: Client public key.

  • pub_b: Server public key.

int ocrypto_srp_premaster_secret(uint8_t s[(384)], const uint8_t pub_a[(384)], const uint8_t priv_b[(32)], const uint8_t u[(64)], const uint8_t v[(384)])

SRP-6 Premaster Secret.

The premaster secret between the client and the server is computed using the client public key pub_a, the server private key priv_b, the scrambling parameter u and the password verifier v. If the client public key pub_a is valid, the premaster secret is then put into s. The premaster secret can be used to generate encryption keys.

Parameters
  • [out] s: Generated premaster secret, must be 32-bit aligned.

  • pub_a: Client public key.

  • priv_b: Server private key.

  • u: Scrambling parameter; generated with srp_scrambling_parameter.

  • v: Password verifier.

Return Value
  • 0: If pub_a is a valid public key.

  • 1: Otherwise.

void ocrypto_srp_session_key(uint8_t k[(64)], const uint8_t s[(384)])

SRP-6 SRP Session Key.

Generates the shared SRP session key from the premaster secret s and puts it into k.

Parameters
  • [out] k: Generated SRP session key.

  • s: Premaster secret.

SRP-6 Proof exchange

Proofs are exchanged from client to server and vice versa to ensure that both parties computed the same shared session key. The proofs only match if the correct password is used by the client.

void ocrypto_srp_proof_m1(uint8_t m1[(64)], const uint8_t *user, size_t user_len, const uint8_t salt[(16)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)], const uint8_t k[(64)])

SRP-6 Proof M1 (client to server).

A proof is generated by the client and sent to the server to assert that the client is in possession of the shared session key k. The server also generates the proof. Only if the proofs match, the process can continue. The proof is based on the salt salt, the client public key pub_a, the server public key pub_b and the shared session key k.

Parameters
  • [out] m1: Generated proof.

  • user: User name.

  • user_len: Length of user.

  • salt: Salt.

  • pub_a: Client public key.

  • pub_b: Server public key.

  • k: Session key.

void ocrypto_srp_proof_m2(uint8_t m2[(64)], const uint8_t pub_a[(384)], const uint8_t m1[(64)], const uint8_t k[(64)])

SRP-6 Proof M2 (server to client).

A second proof is generated by the server and sent back to the client to assert that the server is in possession of the shared session key k. The client also generates the proof. If the proofs match, both parties can assume that they share the same session key k. The second proof is based on the client public key pub_a, the first proof m1 and the session key k.

Parameters
  • [out] m2: Generated proof.

  • pub_a: Client public key.

  • m1: First proof. Generated with srp_proof_m1.

  • k: Session key.

Defines

ocrypto_srp_SALT_BYTES

Salt length.

ocrypto_srp_VERIFIER_BYTES

Password verifier length.

ocrypto_srp_SECRET_KEY_BYTES

Secret key length.

ocrypto_srp_PUBLIC_KEY_BYTES

Public key length.

ocrypto_srp_SCRAMBLING_PARAMETER_BYTES

Scrambling parameter length.

ocrypto_srp_PREMASTER_SECRET_BYTES

Premaster secret length.

ocrypto_srp_SESSION_KEY_BYTES

Session key length.

ocrypto_srp_PROOF_BYTES

Proof length.

SRPT - Secure Real-Time Transport Protocol APIs

group nrf_oberon_srpt

Type declarations and APIs for SRTP - Secure Real-time Transport Protocol.

Defines

ocrypto_srtp_AuthKeySize

SRTP Authentication Key Size.

ocrypto_srtp_SaltSize

SRTP Salt Size.

ocrypto_srtp_MaxKeySize

SRTP Maximum Key Size.

Functions

void ocrypto_srtp_setupContext(ocrypto_srtp_context *srtpContext, ocrypto_srtp_context *srtcpContext, const uint8_t *key, uint32_t keySize, const uint8_t *salt, uint32_t tagSize, uint32_t ssrc)

Setup SRTP contexts.

Parameters
  • [out] srtpContext: SRTP context to be setup.

  • [out] srtcpContext: SRTCP context to be setup.

  • key: Master key.

  • keySize: Size of the master key (16, 24, or 32 bytes)

  • salt: Master salt.

  • tagSize: Size of the authentication tag.

  • ssrc: Synchronization source.

void ocrypto_srtp_encrypt(const ocrypto_srtp_context *srtpContext, uint8_t *packet, const uint8_t *dataBytes, size_t numHeaderBytes, size_t numDataBytes, uint32_t index)

Encrypt SRTP packet.

The final packet consists of numHeaderBytes encrypted in place, followed by numDataBytes copied from dataBytes during encryption.

Parameters
  • srtpContext: SRTP context.

  • [inout] packet: Encrypted packet.

  • dataBytes: Data bytes to be encrypted.

  • numHeaderBytes: Number of header bytes.

  • numDataBytes: Number of data bytes.

  • index: Packet index.

void ocrypto_srtp_decrypt(const ocrypto_srtp_context *srtpContext, uint8_t *data, const uint8_t *packetBytes, size_t numPacketBytes, uint32_t index)

Decrypt SRTP packet.

Parameters
  • srtpContext: SRTP context.

  • [out] data: Decrypted data.

  • packetBytes: Packet bytes.

  • numPacketBytes: Number of packet bytes.

  • index: Packet index.

void ocrypto_srtp_authenticate(const ocrypto_srtp_context *context, uint8_t *tag, const uint8_t *bytes, size_t numBytes, uint32_t index)

Generate SRTP authentication tag from bytes and index.

Parameters
  • context: SRTP context.

  • [out] tag: Authentication tag generated.

  • bytes: Byte buffer.

  • numBytes: Number of bytes in buffer.

  • index: Index.

int ocrypto_srtp_verifyAuthentication(const ocrypto_srtp_context *context, const uint8_t *tag, const uint8_t *bytes, size_t numBytes, uint32_t index)

Check SRTP authentication tag against bytes and index.

Parameters
  • context: SRTP context.

  • tag: Tag.

  • bytes: Byte buffer.

  • numBytes: Number of bytes in buffer.

  • index: Index.

Return Value
  • 1: If the tag is valid.

  • 0: Otherwise.

struct ocrypto_srtp_context
#include <ocrypto_srtp.h>

SRTP Context.

Public Members

uint32_t keySize

Key size [bytes].

uint32_t tagSize

Tag size [bytes].

uint8_t encrKey[(((size_t)32))]

Session encryption key (max 256 bits).

uint8_t authKey[(20)]

Session authentication key 160 bits.

uint8_t saltKey[(14)]

Session salt 112 bits.