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).

retval 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

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

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

Return values

• 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

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

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

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

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

Return values

• 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

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

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

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

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

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

Return values

• 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

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

Return values

• 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

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

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

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

Return values

• 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

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

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

Return values

• 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 CC3XX platform library

group nrf_cc3xx_platform

nrf_cc3xx_platform library containing cc3xx hardware initialization and entropy gathering APIs. The library also contains APIs and companion source-files to setup RTOS dependent mutex and abort functionality for the nrf_cc3xx_mbedcrypto library in Zephyr RTOS and FreeRTOS.

CC3XX Platform - Defines

group nrf_cc3xx_platform_defines

nrf_cc3xx_platform shared defines and return codes.

Defines

NRF_CC3XX_PLATFORM_ENTROPY_MAX_GATHER

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

NRF_CC3XX_PLATFORM_EITS_NONCE_SIZE

Definition of the nonce size for EITS in bytes.

NRF_CC3XX_PLATFORM_TFM_BOOT_SEED_SIZE

Definition of the TF-M boot seed size in bytes.

NRF_CC3XX_PLATFORM_USE_COUNT_MAX

Definition of max count of concurrent usage.

Note

The max value will never be reached.

NRF_CC3XX_PLATFORM_SUCCESS

NRF_CC3XX_PLATFORM_TRUE

NRF_CC3XX_PLATFORM_FALSE

NRF_CC3XX_PLATFORM_ERROR_PARAM_NULL

NRF_CC3XX_PLATFORM_ERROR_INTERNAL

NRF_CC3XX_PLATFORM_ERROR_RNG_TEST_FAILED

NRF_CC3XX_PLATFORM_ERROR_HW_VERSION_FAILED

NRF_CC3XX_PLATFORM_ERROR_PARAM_WRITE_FAILED

NRF_CC3XX_PLATFORM_ERROR_MUTEX_NOT_INITIALIZED

NRF_CC3XX_PLATFORM_ERROR_MUTEX_FAILED

NRF_CC3XX_PLATFORM_ERROR_ENTROPY_NOT_INITIALIZED

NRF_CC3XX_PLATFORM_ERROR_ENTROPY_TRNG_TOO_LONG

NRF_CC3XX_PLATFORM_ERROR_KMU_INVALID_SLOT

NRF_CC3XX_PLATFORM_ERROR_KMU_ALREADY_FILLED

NRF_CC3XX_PLATFORM_ERROR_KMU_WRONG_ADDRESS

NRF_CC3XX_PLATFORM_ERROR_KMU_WRITE_KEY_FAILED

NRF_CC3XX_PLATFORM_ERROR_KMU_WRITE_INVALID_PERM

NRF_CC3XX_PLATFORM_ERROR_KDR_INVALID_WRITE

NRF_CC3XX_PLATFORM_ERROR_KDR_INVALID_PUSH

NRF_CC3XX_PLATFORM_ERROR_KMU_INVALID_KEY_TYPE

NRF_CC3XX_PLATFORM_ERROR_INVALID_PARAM

NRF_CC3XX_PLATFORM_ERROR_DERIVED_KEY_CTX_INVALID_STATE

NRF_CC3XX_PLATFORM_ERROR_IDENTITY_KEY_INVALID_SLOT

NRF_CC3XX_PLATFORM_ERROR_KIDENT_ALREADY_FILLED

NRF_CC3XX_PLATFORM_ERROR_KIDENT_WRITE_KEY_FAILED

NRF_CC3XX_PLATFORM_ERROR_KIDENT_READ_KEY_FAILED

NRF_CC3XX_PLATFORM_ERROR_KIDENT_MKEK_MISSING

NRF_CC3XX_PLATFORM_ERROR_KIDENT_INVALID_STATE

NRF_CC3XX_PLATFORM_DERIVED_KEY_CTX_INITIALIZED

NRF_CC3XX_PLATFORM_DERIVED_KEY_DERIV_INFO_SET

NRF_CC3XX_PLATFORM_DERIVED_KEY_CIPH_INFO_SET

NRF_CC3XX_PLATFORM_DERIVED_KEY_AUTH_INFO_SET

NRF_KMU_FIRST_SLOT

First addressable key slot in KMU.

NRF_KMU_SECOND_SLOT

Second addressable key slot in KMU.

NRF_KMU_LAST_SLOT

Last addressable key slot in KMU.

NRF_KMU_LAST_IDENTTY_KEY_SLOT

Last addressable KMU slot for an identity key (Two slots used)

NRF_KMU_SLOT_KDR

Key slot reserved for Kdr (Also known as HUK or Root derivation key).

NRF_KMU_SLOT_KDR_RESERVED

Key slot reserved for Kdr (CC312: Used for last 128 bits of key material).

NRF_KMU_SLOT_MKEK

Key slot reserved for MKEK (Master Key Encryption Key).

NRF_KMU_SLOT_MKEK_RESERVED

Key slot reserved for MKEK (CC312: Used for last 128 bits of key material).

NRF_KMU_SLOT_MEXT

Key slot reserved for MEXT (Master External storage encryption Key).

NRF_KMU_SLOT_MEXT_RESERVED

Key slot reserved for MEXT (CC312: Used for last 128 bits of key material).

NRF_KMU_SLOT_KIDENT

Key slot reserved for the encrypted KIDENT (Identity key).

NRF_KMU_SLOT_KIDENT_RESERVED

Key slot reserved for the encrypted KIDENT (Identity key, second slot).

CC3XX Platform - Initialization APIs

group nrf_cc3xx_platform_init

The nrf_cc3xx_platform APIs provides functions related to initialization of the Arm CryptoCell cc3xx hardware accelerator for usage in nrf_cc3xx_platform and dependent libraries.

Functions

int nrf_cc3xx_platform_init(void)

Function to initialize the nrf_cc3xx_platform with rng support. The function is using CTR_DRBG to generate a random seed.

Returns

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

int nrf_cc3xx_platform_init_hmac_drbg(void)

Function to initialize the nrf_cc3xx_platform with rng. The function is using HMAC_DRBG to generate a random seed.

Note

If this is called after nrf_cc3xx_platform_init it will create a new random seed using HMAC_DRBG.

Returns

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

int nrf_cc3xx_platform_init_no_rng(void)

Function to initialize the nrf_cc3xx_platform without rng support.

Returns

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

int nrf_cc3xx_platform_deinit(void)

Function to deinitialize the nrf_cc3xx_platform.

Returns

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

bool nrf_cc3xx_platform_is_initialized(void)

Function to check if the nrf_cc3xx_platform is initialized.

Return values

True – if initialized, otherwise false.

bool nrf_cc3xx_platform_rng_is_initialized(void)

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

Return values

True – if RNG is initialized, otherwise false.

void CRYPTOCELL_IRQHandler(void)

ISR Function for processing of cc3xx Interrupts. This cc3xx 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.

int nrf_cc3xx_platform_get_nonce_seed(uint8_t buffer[(8)])

Function to get the nonce seed used for encrypted ITS usage.

Parameters

• buffer – [in] Buffer to fill the nonce seed generated during boot.

Returns

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

int nrf_cc3xx_platform_get_boot_seed(uint8_t buffer[(32)])

Function to get the boot seed used by TF-M attestation.

Parameters

• buffer – [in] Buffer to fill the boot seed generated during boot.

Returns

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

CC3XX Platform - Entropy APIs

group nrf_cc3xx_platform_entropy

The nrf_cc3xx_platform_entropy APIs provides TRNG using Arm CC3xx hardware acceleration.

Functions

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

Function to generate entropy using Arm CryptoCell cc3xx.

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

Note

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

Parameters

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

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

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

Return values

0 – on success

Returns

Any other error code returned from mbedtls_hardware_poll

CC3XX Platform - Mutex APIs

group nrf_cc3xx_platform_mutex

The nrf_cc3xx_platform_mutex APIs provides RTOS integration for mutex usage in nrf_cc3xx_platform and dependent libraries.

Defines

NRF_CC3XX_PLATFORM_MUTEX_MASK_INVALID

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

NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_VALID

Mask value indicating that the mutex is valid for use.

NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_ALLOCATED

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

NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_ATOMIC

Mask value indicating that the mutex is atomic type.

NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_HW_MUTEX

Mask value indicating that the mutex is hardware mutex type.

NRF_CC3XX_PLATFORM_MUTEX_MASK_IS_INTERNAL_MUTEX

Mask value indicating that the mutex is an internal CryptoCell mutex.

Typedefs

typedef void (*nrf_cc3xx_platform_mutex_init_fn_t)(nrf_cc3xx_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.

Param mutex

[in] Pointer to a mutex to initialize.

typedef void (*nrf_cc3xx_platform_mutex_free_fn_t)(nrf_cc3xx_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.

Param mutex

[in] Pointer to a mutex to free.

typedef int (*nrf_cc3xx_platform_mutex_lock_fn_t)(nrf_cc3xx_platform_mutex_t *mutex)

Type definition of function pointer to lock a mutex.

Calling this function pointer should lock a mutex.

Param mutex

[in] Pointer to a mutex to lock.

typedef int (*nrf_cc3xx_platform_mutex_unlock_fn_t)(nrf_cc3xx_platform_mutex_t *mutex)

Type definition of function pointer to unlock a mutex.

Calling this function pointer should unlock a mutex.

Param mutex

[in] Pointer to a mutex to unlock.

Functions

void nrf_cc3xx_platform_set_mutexes(nrf_cc3xx_platform_mutex_apis_t const *const apis, nrf_cc3xx_platform_mutexes_t const *const mutexes)

Function to set platform mutex APIs and mutexes.

Parameters

• apis – [in] Structure holding the mutex APIs.

• mutexes – [in] Structure holding the mutexes.

void nrf_cc3xx_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_cc3xx_platform initialization APIs or nrf_cc3xx_platform_init_no_rng.

Note

This function is not expected to be thread-safe.

Variables

nrf_cc3xx_platform_mutex_apis_t platform_mutex_apis

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

nrf_cc3xx_platform_mutexes_t platform_mutexes

External reference to currently set platform hw mutexes.

struct nrf_cc3xx_platform_mutex_t

#include <nrf_cc3xx_platform_mutex.h>

Type definition of architecture neutral mutex type.

struct nrf_cc3xx_platform_mutex_apis_t

#include <nrf_cc3xx_platform_mutex.h>

Type definition of structure holding platform mutex APIs.

struct nrf_cc3xx_platform_mutexes_t

#include <nrf_cc3xx_platform_mutex.h>

Type definition of structure to platform hw mutexes.

CC3XX Platform - Abort APIs

group nrf_cc3xx_platform_abort

The nrf_cc3xx_platform_entropy APIs provides callbacks to abort from nrf_cc3xx_platform and/or dependent libraries.

Typedefs

typedef void *nrf_cc3xx_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_cc3xx_platform_abort_fn_t)(char const *const reason)

Type definition of platform abort function.

Note

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

Functions

void nrf_cc3xx_platform_set_abort(nrf_cc3xx_platform_abort_apis_t const *const apis)

Function to set platform abort APIs.

Parameters

• apis – [in] Pointer to platform APIs.

void nrf_cc3xx_platform_abort_init(void)

Function to initialize platform abort APIs.

Note

This function must be called once before calling nrf_cc3xx_platform initialization APIs or nrf_cc3xx_platform_init_no_rng.

Note

This function is not expected to be thread-safe.

Variables

nrf_cc3xx_platform_abort_apis_t platform_abort_apis

External reference to the platform abort APIs.

struct nrf_cc3xx_platform_abort_apis_t

#include <nrf_cc3xx_platform_abort.h>

Type definition of structure holding platform abort APIs.

Public Members

nrf_cc3xx_platform_abort_handle_t abort_handle

Handle to use when crypto operations are aborted.

nrf_cc3xx_platform_abort_fn_t abort_fn

Function to use when crypto operations are aborted.

CC3XX Platform - KMU APIs

group nrf_cc3xx_platform_kmu

The nrf_cc3xx_platform_kmu APIs provides RTOS integration for storing keys in KMU hardware peripherals.

Defines

NRF_CC3XX_PLATFORM_KMU_DEFAULT_PERMISSIONS

Constant value representing the default permission to use when writing a key to KMU.

This sets up the written key to be non-writable, non-readable and pushable.

Warning

Deviating from this mask when setting up permissions may allow reading the key from CPU, which has security implications.

NRF_CC3XX_PLATFORM_KMU_IDENTITY_KEY_PERMISSIONS

Constant value representing the permission to use when writing an indentity_key to KMU.

This sets up the written key to be non-writable, readable and non-pushable

NRF_CC3XX_PLATFORM_KMU_AES_ADDR

Address of the AES key register in CryptoCell.

NRF_CC3XX_PLATFORM_KMU_CHACHAPOLY_ADDR

Address of the ChaChaPoly key register in CryptoCell for 128 bit keys.

NRF_CC3XX_PLATFORM_KMU_CHACHAPOLY_ADDR1

Address of the first 128 bits of ChaChaPoly key in CryptoCell

NRF_CC3XX_PLATFORM_KMU_CHACHAPOLY_ADDR2

Address of the last 128 bits bits of ChaChaPoly key register in CryptoCell HW

Note

Used only when ChaChaPoly key is larger than 128 bits, in which case the ChaChaPoly key is split between two slots in KMU

NRF_CC3XX_PLATFORM_NRF9160_KDR_ADDR

Enums

enum nrf_cc3xx_platform_key_type_t

Enumeration type listing the key types which support the CryptoCell push operation.

Values:

enumerator NRF_CC3XX_PLATFORM_KEY_TYPE_KDR_AES_128_BIT

AES 128 bit key to be used in KDR.

enumerator NRF_CC3XX_PLATFORM_KEY_TYPE_CHACHAPOLY_256_BIT

ChaChaPoly 256 bit key to be used in a KMU slot.

enumerator NRF_CC3XX_PLATFORM_KEY_TYPE_AES_128_BIT

AES 128 bit key to be used in a KMU slot.

enumerator NRF_CC3XX_PLATFORM_KEY_TYPE_AES_256_BIT

AES 256 bit key to be used in a KMU slot.

Functions

int nrf_cc3xx_platform_kmu_write_key(uint32_t slot_id, nrf_cc3xx_platform_key_type_t key_type, nrf_cc3xx_platform_key_buff_t key_buff)

Write a key into the KMU.

This writes a key into the KMU slot defined by slot_id. If the key is larger than 128 bit it will occupy two consecutive KMU slots.

Note

This function uses the default KMU key permissions, see NRF_CC3XX_PLATFORM_KMU_DEFAULT_PERMISSIONS.

Parameters

• slot_id – [in] KMU slot ID for the new key (2 - 127).

• key_type – [in] The type of the key to store in the KMU.

• key_buff – [in] Buffer containing the key material.

Returns

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a negative value.

int nrf_cc3xx_platform_kmu_write_key_slot(uint32_t slot_id, uint32_t key_addr, uint32_t key_perm, const uint8_t key[16])

Write a 128 bit key into a KMU slot.

This writes a key to KMU with the destination of the subsequent push operation set to the address of the AES or ChaChaPoly key registers in Arm CryptoCell.

Note

The default mask for permissions is recommended to use. Please see NRF_CC3XX_PLATFORM_KMU_DEFAULT_PERMISSIONS.

Note

AES keys of 128 bits can use NRF_CC3XX_PLATFORM_KMU_AES_ADDR as the key_addr. ChaChaPoly keys of 128 bits can use NRF_CC3XX_PLATFORM_KMU_CHACHAPOLY_ADDR as the key addr. Keys larger than 128 bits must be split up to use two KMU slots. For AES (only applicable to nRF5340): Use NRF_CC3XX_PLATFORM_KMU_AES_ADDR_1 for the first 128 bits of the key. Use NRF_CC3XX_PLATFORM_KMU_AES_ADDR_2 for the subsequent bits of the key. For ChaChaPoly: Use NRF_CC3XX_PLATFORM_KMU_CHACHAPOLY_ADDR_1 for the first 128 bits of the key. Use NRF_CC3XX_PLATFORM_KMU_CHACHAPOLY_ADDR_2 for the subsequent bits of the key.

Parameters

• slot_id – [in] KMU slot ID for the new key (2 - 127).

• key_addr – [in] Destination address in CryptoCell used for key push.

• key_perm – [in] Permissions to set for the KMU slot.

• key – [in] Array with the 128 bit key to put in the KMU slot.

Returns

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a negative value.

int nrf_cc3xx_platform_kmu_write_kdr_slot(uint32_t slot_id, const uint8_t key[16])

Write a 128 bit AES key into a KMU slot for KDR use.

This writes a key to KMU with the destination of the subsequent push operation set to the address of the KDR registers in Arm CryptoCell.

Note

The permission set by this function is “non-writable, non-readable

and pushable”. Please see

NRF_CC3XX_PLATFORM_KMU_DEFAULT_PERMISSIONS.

Parameters

• slot_id – [in] Slot id for the KDR key.

• key – [in] Array with the 128 bit key to put in the KMU slot.

Returns

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a negative value.

int nrf_cc3xx_platform_kmu_push_kdr_slot_and_lock(uint32_t slot_id)

Push the 128 bit AES key from a KMU slot into CryptoCell KDR registers and set LCS state to secure.

Note

This function must be run once on every boot to load the KDR key and to set the LCS state to secure.

Note

The KDR key will be stored in the Always on Domain (AO) until the next reset. It is not possible to set the KDR value once the LCS state is set to secure.

Returns

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a negative value.

int nrf_cc3xx_platform_kdr_load_key(uint8_t key[16])

Load a unique 128 bit root key into CryptoCell KDR registers and set CryptoCell LCS state to secure.

Note

This function must be run once on every boot do load an AES key into KDR. It is recommended that this is done in an immutable bootloader stage and the page holding the key is ACL read+write protected after it has been loaded into KDR with this API.

Note

The KDR key should be a randomly generated unique key.

Note

The KDR key will be stored in the Always on Domain (AO) until the next reset. It is not possible to set the KDR value once the LCS state is set to secure.

Parameters

• key – [in] Array with the AES 128 bit key.

Returns

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a negative value.

int nrf_cc3xx_platform_kmu_shadow_key_derive(uint32_t slot_id, unsigned int keybits, uint8_t const *label, size_t label_size, uint8_t const *context, size_t context_size, uint8_t *output, size_t output_size)

Function to use CMAC to derive a key stored in KMU/KDR.

The KDF is using a PRF function described in the Special publication 800-108: Recommendation for Key Derivation Using Pseudorandom Functions https://csrc.nist.gov/publications/detail/sp/800-108/final.

This algorithm is described in chapter 5.1 - KDF in Counter Mode

The format of the PRF (the input) is as follows: PRF (KI, i || Label || 0x00 || Context || L)

KI: The Key derivation key i : The counter value for each iteration of the PRF represented as one byte. label: A string identifying the purpose of the derived key that is up to 64 bytes long. 0x00: A single byte delimiter. Context: Fixed information about the derived keying material that is up to 64 bytes long. L : The length of derived key material in bits represented as two bytes.

Note

On nRF52840 only slot_id == 0 is valid, pointing to the Kdr key (also known as a HUK key) loaded into the CryptoCell.

Parameters

• slot_id – Identifier of the key slot.

• keybits – Key size in bits.

• label – Label to use for KDF.

• label_size – Size of the label in bytes to use for KDF.

• context – Context info to use for KDF.

• context_size – Context info size in bytes to use for KDF.

• output – Output buffer.

• output_size – Size of the output buffer in bytes.

Returns

0 on success, otherwise a negative number.

union nrf_cc3xx_platform_key_buff_t

#include <nrf_cc3xx_platform_kmu.h>

Union type holding the key material to be loaded in the CryptoCell.

Public Members

uint8_t buff_128[16]

uint8_t buff_256[32]

CC3XX Platform - CTR_DRBG APIs

group nrf_cc3xx_platform_ctr_drbg

The nrf_cc3xx_platform_ctr_drbg APIs provide PRNG seeded by TRNG in accordance with NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators The generation of TRNG/PRNG data is using Arm CryptoCell cc3xx hardware acceleration.

The pre-built APIs are based on mbedtls_entropy and mbedtls_ctr_drbg but doesn’t require setting up memory allocation before use.

Defines

NRF_CC3XX_PLATFORM_ENTROPY_SIZE_WORDS

Macro holding size of the opaque ctr_drbg context type.

This corresponds to a structure with the combined size of mbedtls_entropy_context and mbedtls_ctr_drbg_context in Arm CryptoCell code base which is sized differently than in vanilla mbed TLS software.

Functions

int nrf_cc3xx_platform_ctr_drbg_init(nrf_cc3xx_platform_ctr_drbg_context_t *const context, const uint8_t *pers_string, size_t pers_string_len)

Function that initializes a ctr_drbg context.

Note

If the context is NULL the function uses an internal context.

Parameters

• context – [inout] Pointer to structure holding the ctr_drbg context which must be used for subsequent calls to generate random data.

• pers_string – [in] Personalization string used for the CTR_DRBG_Instantiate_algorithm.

• pers_string_len – [in] Length of the personalization string, which may be zero.

Returns

0 on success, otherwise a non-zero failure from mbedtls_ctrl_drbg_seed.

int nrf_cc3xx_platform_ctr_drbg_free(nrf_cc3xx_platform_ctr_drbg_context_t *const context)

Function that deintializes a ctr_drbg context.

Param[in,out] context Pointer to structure holding ctr_drbg context which is to be deinitialized.

int nrf_cc3xx_platform_ctr_drbg_set_pr(nrf_cc3xx_platform_ctr_drbg_context_t *const context, bool pr_enabled)

Function to enable prediction resistance.

If prediction resistance is enabled, TRNG is gathered at the beginning of every call to nrf_cc3xx_platform_ctr_drbg_get and nrf_cc3xx_platform_ctr_drbg_get_with_add. This leads to a higher power draw and longer execution time.

Note

If the context is NULL the function uses an internal context.

Note

Before calling this api the context to must be initialized by calling nrf_cc3xx_platform_ctr_drbg_init

Note

The default configuration is to have prediction resistance turned off.

Parameters

• context – [inout] Pointer to a structure holding the ctr_drbg context.

• pr_enabled – [in] Enables prediction resistance if true, otherwise false (default).

Returns

0 on success, otherwise a non-zero failure.

int nrf_cc3xx_platform_ctr_drbg_set_reseed_interval(nrf_cc3xx_platform_ctr_drbg_context_t *const context, int interval)

Function to change the reseed interval.

This API controls when the ctr_drbg is automatically reseeded

Note

If the context is NULL the function uses an internal context.

Note

Before calling this api the context to must be initialized by calling nrf_cc3xx_platform_ctr_drbg_init.

Note

Changing the reseed interval is optional.

Parameters

• context – [inout] Pointer to a structure holding the ctr_drbg context.

• interval – [in] New reeseed interval value.

Returns

0 on success, otherwise a non-zero failure according to the API mbedtls_ctrl_drbg_reseed.

int nrf_cc3xx_platform_ctr_drbg_reseed(nrf_cc3xx_platform_ctr_drbg_context_t *const context, const uint8_t *additional, size_t add_len)

Function to do a manual reseed of ctr_drbg (using TRNG)

Note

If the context is NULL the function uses an internal context.

Note

Calling this API is optional as the APIs nrf_cc3xx_platform_ctr_drbg_get and nrf_cc3xx_platform_ctr_drbg_get_with_add functions will reseed automatically according to the reseed interval in the built-in mbedtls_ctr_drbg context.

Note

Before calling this api the context to must be initialized by calling nrf_cc3xx_platform_ctr_drbg_init.

Note

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

Note

This API is unneccesary if ctr_drbg is executed with prediction resistance turned on.

Parameters

• context – [inout] Pointer to a structure holding the ctr_drbg context.

• additional – [in] Optional additional input to use for CTR_DRBG_Reseed_function.

• add_len – [in] Length of the additional input, may be zero.

Returns

0 on success, otherwise a non-zero failure according to the API mbedtls_ctrl_drbg_seed.

int nrf_cc3xx_platform_ctr_drbg_get_with_add(nrf_cc3xx_platform_ctr_drbg_context_t *const context, uint8_t *buffer, size_t len, size_t *olen, const uint8_t *additional, size_t add_len)

Function to get PRNG using ctr_drbg and an additional string of data.

This function will calculate PRNG using HW accelerated AES CTR_DRBG with a 16-byte key and reseed with TRNG using ARM CryptoCEll cc3xx HW according to a reseed interval.

This function calculates random numbers using PRNG seeded by TRNG as defined in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators. The random numbers are generated using Arm CryptoCell cc3xx hardware acceleration.

Note

If the context is NULL the function uses an internal context.

Note

Before calling this api the context to must be initialized by calling nrf_cc3xx_platform_ctr_drbg_init.

Note

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

Parameters

• context – [inout] Pointer to structure holding the ctr_drbg context.

• buffer – [in] Pointer to buffer to hold PRNG data.

• len – [in] Length of PRNG to get.

• olen – [out] Length reported out.

• additional – [in] Additional input to use with CTR_DRBG_Generate_algorithm.

• add_len – [in] Length of CTR_DRBG additional input.

Returns

0 on success, otherwise a non-zero failure according to the API mbedtls_ctrl_drbg_get_with_add.

int nrf_cc3xx_platform_ctr_drbg_get(nrf_cc3xx_platform_ctr_drbg_context_t *const context, uint8_t *buffer, size_t length, size_t *olen)

Function to get PRNG data using ctr_drbg.

This function calculates random numbers using PRNG seeded by TRNG as defined in NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators. The random numbers are generated using Arm CryptoCell cc3xx hardware acceleration.

Note

If the context is NULL the function uses an internal context.

Note

Before calling this api the context to must be initialized by calling nrf_cc3xx_platform_ctr_drbg_init.

Note

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

Parameters

• context – [inout] Pointer to structure holding the ctr_drbg context.

• buffer – [in] Pointer to buffer to hold PRNG data.

• length – [in] Length of PRNG to get.

• olen – [out] Length reported out.

Returns

0 on success, otherwise a non-zero failure according to the API mbedtls_ctr_drbg_random.

struct nrf_cc3xx_platform_ctr_drbg_context_t

#include <nrf_cc3xx_platform_ctr_drbg.h>

Opaque type for the context required for ctr_drbg generation.

Note: This opaque type contains contexts for mbed TLS entropy generation (TRNG) and ctr_drbg (PRNG).

Public Members

uint32_t is_initialized

Mask indicating if the ctr_drbg context has been initialized.

uint32_t buffer[(111)]

Internal buffer for the built-in entropy and ctrl_drbg contexts.

nRF CC3XX mbedcrypto library

group nrf_cc3xx_mbedcrypto

nrf_cc3xx_mbedcrypto nrf_cc3xx_mbedcrypto library containing cc3xx APIs for the KMU or KDR peripherals. Further documentation can be found on : https://tls.mbed.org

KMU/KDR APIs

group nrf_cc3xx_mbedcrypto_kmu

The nrf_cc3xx_mbedcrypto_kmu APIs can be utilized to directly use or derive keys from KMU or KDR in ARM CryptoCell devices.

Defines

MBEDTLS_SHADOW_KEY_KDF_MAX_LABEL_SIZE_IN_BYTES

KDF input “label” can be 0 to 64 bytes.

MBEDTLS_SHADOW_KEY_KDF_MAX_CONTEXT_SIZE_IN_BYTES

KDF input “context” can be 0 to 64 bytes.

MBEDTLS_SHADOW_KEY_KDF_MAX_DERIVED_SIZE_IN_BYTES

KDF max length for derived material.

MBEDTLS_ERR_SHADOW_KEY_KEY_OK

The shadow key operation was succesful.

MBEDTLS_ERR_SHADOW_KEY_INVALID_SLOT

The shadow key operation used an invalid slot.

MBEDTLS_ERR_SHADOW_KEY_INVALID_SIZE

The shadow key was of invalid size.

MBEDTLS_ERR_SHADOW_KEY_KDF_INVALID_LABEL

The KDF input label is invalid.

MBEDTLS_ERR_SHADOW_KEY_KDF_INVALID_CONTEXT

The KDF input context is invalid.

MBEDTLS_ERR_SHADOW_KEY_KDF_INVALID_INPUT

The KDF input is invalid.

MBEDTLS_ERR_SHADOW_KEY_INTERNAL_ERROR

KMU/KDF internal error.

Functions

int mbedtls_aes_setkey_enc_shadow_key(mbedtls_aes_context *const ctx, uint32_t slot_id, unsigned int keybits)

Function to configure AES to use one or more KMU key slot for encryption.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_aes_setkey_enc.

Note

Using this API enforces raw key usage of keys in the KMU slots. If derived key usage is intended, please use the API nrf_cc3xx_platform_kmu_aes_setkey_enc_shadow_key_derived.

Parameters

• ctx – AES context to set the key by KMU slot

• slot_id – Identifier of the key slot (0 - 127)

• keybits – Key size in bits

Returns

0 on success, otherwise a negative number.

int mbedtls_aes_setkey_dec_shadow_key(mbedtls_aes_context *const ctx, uint32_t slot_id, unsigned int keybits)

Function to configure AES to use one or more KMU key slot for decryption.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_aes_setkey_dec.

Note

Using this API enforces raw key usage of keys in the KMU slots. If derived key usage is intended, please use the API nrf_cc3xx_platform_kmu_aes_setkey_dec_shadow_key_derived.

Parameters

• ctx – AES context to set the key by KMU slot.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

Returns

0 on success, otherwise a negative number.

int mbedtls_aes_setkey_enc_shadow_key_derived(mbedtls_aes_context *const ctx, uint32_t slot_id, unsigned int keybits, uint8_t const *label, size_t label_size, uint8_t const *context, size_t context_size)

Function to configure AES to use a key derived from one or more slots in KMU for encryption.

See mbedtls_derive_kmu_key for details on the KDF function.

Note

Replaces the API mbedtls_aes_setkey_dec.

Note

The key derivation is executed before each requests to encrypt. this function only configures the context to use a derived key.

Note

When deriving the key from KMU registers, the derived keys exist in SRAM for a brief period of time, before being loaded into the write-only CryptoCell HW registers for AES keys before encryption.

Parameters

• ctx – AES context to set the decryption key by KMU slot.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

• label – Label to use for KDF.

• label_size – Size of the label to use for KDF.

• context – Context info to use for KDF.

• context_size – Context info size to use for KDF.

Returns

0 on success, otherwise a negative number.

int mbedtls_aes_setkey_dec_shadow_key_derived(mbedtls_aes_context *const ctx, uint32_t slot_id, unsigned int keybits, uint8_t const *label, size_t label_size, uint8_t const *context, size_t context_size)

Function to configure AES to use a key derived from one or more slots in KMU for decryption.

See mbedtls_derive_kmu_key for details on the KDF function.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_aes_setkey_enc.

Note

The key derivation is executed before each requests to decrypt. This function only configures the context to use a derived key.

Note

When deriving the key from KMU registers, the derived keys exist in SRAM for a brief period of time, before being loaded into the write-only CryptoCell HW registers for AES keys before decryption.

Parameters

• ctx – AES context to set the decryption key by KMU slot.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

• label – Label to use for KDF.

• label_size – Size of the label to use for KDF.

• context – Context info to use for KDF.

• context_size – Context info size to use for KDF.

Returns

0 on success, otherwise a negative number.

int mbedtls_ccm_setkey_shadow_key(mbedtls_ccm_context *const ctx, mbedtls_cipher_id_t cipher, uint32_t slot_id, unsigned int keybits)

Function to configure AES CCM to use one or more KMU key slot as encryption key.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_ccm_setkey.

Note

Using this API enforces raw key usage of keys in the KMU slots. If derived key usage is intended, please use the API nrf_cc3xx_platform_kmu_aes_setkey_enc_shadow_key_derived.

Parameters

• ctx – AES context to set the key by KMU slot.

• cipher – Cipher id to use.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

Returns

0 on success, otherwise a negative number.

int mbedtls_ccm_setkey_shadow_key_derived(mbedtls_ccm_context *const ctx, mbedtls_cipher_id_t cipher, uint32_t slot_id, unsigned int keybits, uint8_t const *label, size_t label_size, uint8_t const *context, size_t context_size)

Function to configure AES CCM to use a key derived from one or more slots in KMU for encryption.

See mbedtls_derive_kmu_key for details on the KDF function.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_ccm_setkey.

Note

The key derivation is executed before each requests to decrypt. This function only configures the context to use a derived key.

Note

When deriving the key from KMU registers, the derived keys exist in SRAM for a brief period of time, before being loaded into the write-only CryptoCell HW registers for AES keys before decryption.

Parameters

• ctx – AES context to set the decryption key by KMU slot.

• cipher – Cipher id to use.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

• label – Label to use for KDF.

• label_size – Size of the label to use for KDF.

• context – Context info to use for KDF.

• context_size – Context info size to use for KDF.

Returns

0 on success, otherwise a negative number.

int mbedtls_gcm_setkey_shadow_key(mbedtls_gcm_context *const ctx, mbedtls_cipher_id_t cipher, uint32_t slot_id, unsigned int keybits)

Function to configure AES GCM to use one or more KMU key slot as encryption key.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_gcm_setkey.

Note

Using this API enforces raw key usage of keys in the KMU slots. If derived key usage is intended, please use the API nrf_cc3xx_platform_kmu_aes_setkey_enc_shadow_key_derived.

Parameters

• ctx – AES context to set the key by KMU slot.

• cipher – Cipher id to use.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

Returns

0 on success, otherwise a negative number.

int mbedtls_gcm_setkey_shadow_key_derived(mbedtls_gcm_context *const ctx, mbedtls_cipher_id_t cipher, uint32_t slot_id, unsigned int keybits, uint8_t const *label, size_t label_size, uint8_t const *context, size_t context_size)

Function to configure AES GCM to use a key derived from one or more slots in KMU for encryption.

See mbedtls_derive_kmu_key for details on the KDF function.

Note

A shadow key is not directly accessible, only reference information is stored in the context type

Note

Replaces the API mbedtls_gcm_setkey.

Note

The key derivation is executed before each requests to decrypt. this function only configures the context to use a derived key.

Note

When deriving the key from KMU registers, the derived keys exist in SRAM for a brief period of time, before being loaded into the write-only CryptoCell HW registers for AES keys before decryption.

Parameters

• ctx – AES context to set the decryption key by KMU slot.

• cipher – Cipher id to use.

• slot_id – Identifier of the key slot (0 - 127).

• keybits – Key size in bits.

• label – Label to use for KDF.

• label_size – Size of the label to use for KDF.

• context – Context info to use for KDF.

• context_size – Context info size to use for KDF.

Returns

0 on success, otherwise a negative number.

int mbedtls_shadow_key_derive(uint32_t slot_id, unsigned int keybits, uint8_t const *label, size_t label_size, uint8_t const *context, size_t context_size, uint8_t *output, size_t output_size)

Function to use CMAC to derive a key stored in KMU/Kdr.

The KDF is using a PRF function described in the Special publication 800-108: Recommendation for Key Derivation Using Pseudorandom Functions https://csrc.nist.gov/publications/detail/sp/800-108/final.

This algorithm is described in chapter 5.1 - KDF in Counter Mode

The format of the PRF (the input) is as follows: PRF (KI, i || Label || 0x00 || Context || L)

KI: The Key derivation key i : The counter value for each iteration of the PRF represented as one byte. label: A string identifying the purpose of the derived key that is up to 64 bytes long. 0x00: a single byte delimiter. Context: Fixed information about the derived keying material that is up to 64 bytes long. L : The length of derived key material in bits represented as two bytes.

Note

On nRF52840 only slot_id == 0 is valid, pointing to the Kdr key (also known as a HUK key) loaded into the CryptoCell.

Parameters

• slot_id – Identifier of the key slot.

• keybits – Key size in bits.

• label – Label to use for KDF.

• label_size – Size of the label to use for KDF.

• context – Context info to use for KDF.

• context_size – Context info size to use for KDF.

• output – Output buffer.

• output_size – Size of output buffer in bytes.

Returns

0 on success, otherwise a negative number.

nrf_oberon crypto library

group ocrypto

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 ocrypto_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 ocrypto_aes_ctr

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

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 cipher 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.

Remark

If key is NULL only iv is set. If iv is NULL only key is set. Both key and iv must be set before update is called.

Parameters

• ctx – [out] Context.

• key – AES key. May be NULL.

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

• iv – Initial vector. May be NULL.

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

AES-CTR incremental encryption/decryption.

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 may be same as pt.

Remark

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

Parameters

• ctx – Context.

• ct – [out] Ciphertext.

• pt – Plaintext.

• pt_len – Length of pt and ct.

Functions

void ocrypto_aes_ctr_encrypt(uint8_t *ct, const uint8_t *pt, size_t pt_len, const uint8_t *key, size_t size, const uint8_t iv[16])

AES-CTR encryption.

Remark

ct may be same as pt.

Parameters

• ct – [out] Ciphertext.

• pt – Plaintext.

• pt_len – Length of pt and ct.

• key – AES key.

• size – Key size (16, 24, or 32).

• iv – Initial vector.

void ocrypto_aes_ctr_decrypt(uint8_t *pt, const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size, const uint8_t iv[16])

AES-CTR decryption.

Remark

ct may be same as pt.

Parameters

• pt – [out] Plaintext.

• ct – Ciphertext.

• ct_len – Length of pt and ct.

• key – AES key.

• size – Key size (16, 24, or 32).

• iv – Initial vector.

AES EAX APIs

group ocrypto_aes_eax

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

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 may be same as pt.

Parameters

• ct – [out] Ciphertext.

• tag – [out] Authentication tag.

• pt – Plaintext.

• pt_len – Length of pt and ct.

• 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 may be same as pt.

Parameters

• pt – [out] Plaintext.

• tag – Authentication tag.

• ct – Ciphertext.

• ct_len – Length of pt and ct.

• 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 values

• 0 – If tag is valid.

• -1 – Otherwise.

AES GCM - AES Galois/Counter Mode APIs

group ocrypto_aes_gcm

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

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.

Incremental AES-GCM encryption/decryption.

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

void ocrypto_aes_gcm_init(ocrypto_aes_gcm_ctx *ctx, const uint8_t *key, size_t size, const uint8_t iv[12])

AES-GCM initialization.

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

Remark

If key is NULL only iv is set. If iv is NULL only key is set. Both key and iv must be set before update is called.

Parameters

• ctx – [out] Context.

• key – AES key. May be NULL.

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

• iv – Initial vector. May be NULL.

void ocrypto_aes_gcm_init_iv(ocrypto_aes_gcm_ctx *ctx, const uint8_t *iv, size_t iv_len)

AES-GCM iv initialization.

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

Parameters

• ctx – [out] Context.

• iv – Initial vector.

• iv_len – Length of iv.

void ocrypto_aes_gcm_update_aad(ocrypto_aes_gcm_ctx *ctx, const uint8_t *aa, size_t aa_len)

AES-GCM incremental aad input.

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

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

Remark

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

Remark

ocrypto_aes_gcm_update_aad must be called before any call to ocrypto_aes_gcm_update_enc or ocrypto_aes_gcm_update_dec.

Parameters

• ctx – Generator state.

• aa – Additional authenticated data.

• aa_len – Length of aa.

void ocrypto_aes_gcm_update_enc(ocrypto_aes_gcm_ctx *ctx, uint8_t *ct, const uint8_t *pt, size_t pt_len)

AES-GCM 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_gcm_init is required before this function can be called.

Parameters

• ctx – Context.

• ct – [out] Ciphertext.

• pt – Plaintext.

• pt_len – Length of pt and ct.

void ocrypto_aes_gcm_update_dec(ocrypto_aes_gcm_ctx *ctx, uint8_t *pt, const uint8_t *ct, size_t ct_len)

AES-GCM 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_gcm_init is required before this function can be called.

Parameters

• ctx – Context.

• pt – [out] Plaintext.

• ct – Ciphertext.

• ct_len – Length of ct and pt.

void ocrypto_aes_gcm_final_enc(ocrypto_aes_gcm_ctx *ctx, uint8_t *tag, size_t tag_len)

AES-GCM final encoder step.

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

Parameters

• ctx – Generator state.

• tag – [out] Generated authentication tag.

• tag_len – Authentication tag length, 0 < tag_len <= 16.

int ocrypto_aes_gcm_final_dec(ocrypto_aes_gcm_ctx *ctx, const uint8_t *tag, size_t tag_len)

AES-GCM 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.

• tag_len – Authentication tag length.

Return values

• 0 – If tag is valid.

• -1 – Otherwise.

Functions

void ocrypto_aes_gcm_encrypt(uint8_t *ct, uint8_t *tag, size_t tag_len, 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 may be same as pt.

Parameters

• ct – [out] Ciphertext.

• tag – [out] Authentication tag.

• tag_len – Authentication tag length, 0 < tag_len <= 16.

• pt – Plaintext.

• pt_len – Plaintext length, 0 < ct_len < 2^36-32 bytes.

• key – AES key.

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

• iv – Initial vector.

• aa – Additional authentication data.

• aa_len – Additional authentication data length, 0 < aa_len < 2^61 bytes.

int ocrypto_aes_gcm_decrypt(uint8_t *pt, const uint8_t *tag, size_t tag_len, 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 may be same as pt.

Parameters

• pt – [out] Plaintext.

• tag – Authentication tag.

• tag_len – Authentication tag length, 0 < tag_len <= 16.

• ct – Ciphertext.

• ct_len – Ciphertext length, 0 < ct_len < 2^36-32 bytes.

• key – AES key.

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

• iv – Initial vector.

• aa – Additional authentication data.

• aa_len – Additional authentication data length, 0 < aa_len < 2^61 bytes.

Return values

• 0 – If tag is valid.

• -1 – Otherwise.

AES key sizes

group ocrypto_aes_key

Type definition of AES key sizes.

AES key sizes in bytes.

Defines

ocrypto_aes128_KEY_BYTES

Length of AES-128 key.

ocrypto_aes192_KEY_BYTES

Length of AES-192 key.

ocrypto_aes256_KEY_BYTES

Length of AES-256 key.

ChaCha20-Poly1305

group ocrypto_chacha_poly

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

ChaCha20-Poly1305 APIs

group ocrypto_chacha_poly_apis

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 also

RFC 8439 - ChaCha20 and Poly1305 for IETF Protocols

Incremental ChaCha20-Poly1305 generator.

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

Use pattern:

Encoding:

ocrypto_chacha20_poly1305_init(ctx, nonce, nonce_len, key);
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len);
...
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len);
ocrypto_chacha20_poly1305_update_enc(ctx, ct, pt, pt_len);
...
ocrypto_chacha20_poly1305_update_enc(ctx, ct, pt, pt_len);
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);
...
ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len);
ocrypto_chacha20_poly1305_update_dec(ctx, pt, ct, ct_len);
...
ocrypto_chacha20_poly1305_update_dec(ctx, pt, ct, ct_len);
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

• ctx – [out] 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)

ChaCha20-Poly1305 incremental aad input.

The generator state ctx is updated to include an additional authenticated 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)

ChaCha20-Poly1305 incremental encoder input.

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

This function can be called repeatedly on arbitrarily small chunks of the message until the whole message has been 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 may be same as m.

Parameters

• ctx – Generator state.

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

• m – Message chunk.

• m_len – Length of m.

void ocrypto_chacha20_poly1305_update_dec(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t *m, const uint8_t *c, size_t c_len)

ChaCha20-Poly1305 incremental decoder input.

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

This function can be called repeatedly on arbitrarily small chunks of the ciphertext until the whole ciphertext has been 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 may be same as c.

Parameters

• ctx – Generator state.

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

• c – Ciphertext chunk.

• c_len – Length of c.

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

ChaCha20-Poly1305 final encoder step.

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

Parameters

• ctx – Generator state.

• tag – [out] Generated authentication tag.

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

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 values

• 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 *a, size_t a_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, 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 may be same as m.

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

• tag – [out] Generated authentication tag.

• c – [out] 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. May be 0.

• n – Nonce.

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

• k – Encryption key.

int ocrypto_chacha20_poly1305_decrypt(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.

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 may be same as c.

Parameters

• tag – Received authentication tag.

• m – [out] 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. May be 0.

• n – Nonce.

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

• k – Encryption key.

Return values

• 0 – If tag is valid.

• -1 – Otherwise.

ChaCha20 APIs

group ocrypto_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 also

RFC 8439 - ChaCha20 and Poly1305 for IETF Protocols

See also

The ChaCha family of stream ciphers

Incremental ChaCha20 Encoder.

This group of functions can be used to incrementally compute the ChaCha20 encryption for a given message and key, by segmenting a message into smaller chunks.

Use pattern:

Encoding/Decoding:

ocrypto_chacha20_init(ctx, n, n_len, key, count);
ocrypto_chacha20_update(ctx, c, m, m_len);
...
ocrypto_chacha20_update(ctx, c, m, m_len);

void ocrypto_chacha20_init(ocrypto_chacha20_ctx *ctx, const uint8_t *n, size_t n_len, const uint8_t key[(32)], uint32_t count)

ChaCha20 encoder initialization.

The generator state ctx is initialized by this function.

Remark

If key is NULL only n and count are set. If n is NULL only key is set. Both key and n must be set before update is called.

Remark

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

Parameters

• ctx – [out] Encoder state.

• n – Nonce. May be NULL.

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

• key – Authentication key. May be NULL.

• count – Initial block counter, usually 0 or 1.

void ocrypto_chacha20_update(ocrypto_chacha20_ctx *ctx, uint8_t *c, const uint8_t *m, size_t m_len)

ChaCha20 encoder.

The message m is ChaCha20 encrypted and the resulting cipher stream is written to c.

This function can be called repeatedly on arbitrarily small chunks of a larger message until the whole message has been processed.

Remark

Initialization of the encoder state ctx through ocrypto_chacha20_init is required before this function can be called.

Parameters

• ctx – Encoder state.

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

• m – Input message.

• m_len – Length of c and m; m_len < 2^38 bytes.

Defines

ocrypto_chacha20_KEY_BYTES

Length of the encryption key.

ocrypto_chacha20_NONCE_BYTES_MAX

Maximum length of the nonce.

Functions

void ocrypto_chacha20_encode(uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t key[(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 key, 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 may be same as m.

Remark

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

Parameters

• c – [out] 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.

• key – Encryption key.

• count – Initial block counter.

Constant time APIs

group ocrypto_constant_time

Timing-invariant functions to use with cryptography.

Defines

ocrypto_constant_time_copy(x, y, length)

Variable length copy.

Parameters

• x – Memory region to copy y to.

• y – Memory region to copy to x.

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

ocrypto_constant_time_fill_zero(x, length)

Variable length fill with zero.

Parameters

• x – Memory region to be filled with zero.

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

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 values

• 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 – Memory region that will be compared.

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

Return values

• 1 – If x is equal to a zero memory region.

• 0 – Otherwise.

void ocrypto_constant_time_xor(void *r, const void *x, const void *y, size_t length)

Variable length bitwise xor.

Remark

r may be same as x or y.

Parameters

• r – Memory region to store the result.

• x – Memory region containing the first argument.

• y – Memory region containing the second argument.

• length – Number of bytes in both arguments, length > 0.

ECC secp256r1 low-level APIs

group ocrypto_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

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

• p – x as as array of bytes.

Return values

• 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

• r – [out] Loaded point.

• p – Point as array of bytes.

Return values

• 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

• r – [out] 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

• r – [out] 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

• r – [out] Output point.

• p – Input point.

• s – Scalar.

Return values

• -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

• r – [out] Output point.

• s – Scalar.

Return values

• -1 – If r = [0,0].

• 0 – If 0 < s < q.

• 1 – If s > q.

ECC Curve25519 low-level APIs

group ocrypto_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 also

RFC 7748 - Elliptic Curves for Security

See also

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.

Remark

r may be same as n.

Parameters

• r – [out] Resulting curve point.

• n – [in] 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 may be same as n.

Parameters

• r – [out] Resulting curve point.

• n – [in] Scalar factor.

• p – [in] Point factor.

void ocrypto_curve25519_scalarmult_base_ctx(ocrypto_curve25519_ctx *ctx, uint8_t r[(32)], const uint8_t n[(32)])

Curve25519 scalar multiplication r = n * basePoint with context.

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

Remark

r may be same as n.

Parameters

• ctx – Context.

• r – [out] Resulting curve point.

• n – [in] Scalar factor.

void ocrypto_curve25519_scalarmult_ctx(ocrypto_curve25519_ctx *ctx, uint8_t r[(32)], const uint8_t n[(32)], const uint8_t p[(32)])

Curve25519 scalar multiplication r = n * p with context.

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 may be same as n.

Parameters

• ctx – Context.

• r – [out] Resulting curve point.

• n – [in] Scalar factor.

• p – [in] Point factor.

ECDH APIs

group ocrypto_ecdh_p256

Type declarations and APIs for low-level elliptic curve point operations to do Elliptic Curve Diffie-Hellman based on the NIST secp256r1 curve.

Incremental ECDH P-256 calculation.

This group of functions can be used to incrementally calculate the ECDH P-256 public key and common secret. Each call completes in less than 25ms on a 16MHz Cortex-M0.

Use pattern:

Public Key:

ocrypto_ecdh_p256_public_key_init(ctx, sKey);
while (ocrypto_ecdh_p256_public_key_iterate(ctx));
res = ocrypto_ecdh_p256_public_key_final(ctx, pKey);

Common Secret:

ocrypto_ecdh_p256_common_secret_init(ctx, sKey, pKey);
while (ocrypto_ecdh_p256_common_secret_iterate(ctx));
res = ocrypto_ecdh_p256_common_secret_final(ctx, secet);

void ocrypto_ecdh_p256_public_key_init(ocrypto_ecdh_p256_ctx *ctx, const uint8_t sk[32])

Incremental ECDH P-256 public key generation start.

Key generation is started and the context ctx is initialized by this function.

Parameters

• ctx – [out] Context.

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

int ocrypto_ecdh_p256_public_key_iterate(ocrypto_ecdh_p256_ctx *ctx)

Incremental ECDH P-256 public key generation step.

The key calculation is advanced and the context ctx is updated by this function.

Parameters

• ctx – Context.

Return values

• 1 – If another call to ocrypto_ecdh_p256_public_key_init is needed.

• 0 – If key generation should be completed by a call to ocrypto_ecdh_p256_public_key_final.

int ocrypto_ecdh_p256_public_key_final(ocrypto_ecdh_p256_ctx *ctx, uint8_t r[64])

Incremental ECDH P-256 public key generation final step.

Key generation is finalized and the context ctx is used to generate the key.

Parameters

• ctx – Context.

• r – [out] Generated public key.

Return values

• 0 – If sk is a valid secret key.

• -1 – Otherwise.

void ocrypto_ecdh_p256_common_secret_init(ocrypto_ecdh_p256_ctx *ctx, const uint8_t sk[32], const uint8_t pk[64])

Incremental ECDH P-256 common secret generation start.

Common secret calculation is started and the context ctx is initialized by this function.

Parameters

• ctx – [out] Context.

• sk – Server private key.

• pk – Client public key.

int ocrypto_ecdh_p256_common_secret_iterate(ocrypto_ecdh_p256_ctx *ctx)

Incremental ECDH P-256 common secret generation step.

Common secret calculation is advanced and the context ctx is updated by this function.

Parameters

• ctx – Context.

Return values

• 1 – If another call to ocrypto_ecdh_p256_common_secret_iterate is needed.

• 0 – If key generation should be completed by a call to ocrypto_ecdh_p256_common_secret_final.

int ocrypto_ecdh_p256_common_secret_final(ocrypto_ecdh_p256_ctx *ctx, uint8_t r[32])

Incremental ECDH P-256 common secret generation final step.

Common secret calculation is finalized and the context ctx is used to generate the secret.

Parameters

• ctx – Context.

• r – [out] Generated common secret.

Return values

• 0 – If sk is a valid secret key and pk is a valid public key.

• -1 – Otherwise.

Functions

int ocrypto_ecdh_p256_secret_key_check(const uint8_t sk[32])

ECDH P-256 secret key check.

Parameters

• sk – Secret key to check.

Return values

• 0 – If sk is a valid secret key.

• -1 – Otherwise.

int ocrypto_ecdh_p256_public_key_check(const uint8_t pk[64])

ECDH P-256 public key check.

Parameters

• pk – Public key to check.

Return values

• 0 – If pk is a valid public key.

• -1 – Otherwise.

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

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

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

Remark

r may be same as sk.

Parameters

• r – [out] Generated public key.

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

Return values

• 0 – If sk is a valid secret key.

• -1 – Otherwise.

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

ECDH P-256 common secret.

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

Remark

r may be same as sk or pk.

Parameters

• r – [out] Generated common secret.

• sk – Server private key.

• pk – Client public key.

Return values

• 0 – If sk is a valid secret key and pk is a valid public key.

• -1 – Otherwise.

group ocrypto_ecdh_p224

Type declarations and APIs for low-level elliptic curve point operations to do Elliptic Curve Diffie-Hellman based on the NIST secp224r1 curve.

Functions

int ocrypto_ecdh_p224_secret_key_check(const uint8_t sk[28])

ECDH P-224 secret key check.

Parameters

• sk – Secret key to check.

Return values

• 0 – If sk is a valid secret key.

• -1 – Otherwise.

int ocrypto_ecdh_p224_public_key_check(const uint8_t pk[56])

ECDH P-224 public key check.

Parameters

• pk – Public key to check.

Return values

• 0 – If pk is a valid public key.

• -1 – Otherwise.

int ocrypto_ecdh_p224_public_key(uint8_t r[56], const uint8_t sk[28])

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

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

Remark

r may be same as sk.

Parameters

• r – [out] Generated public key.

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

Return values

• 0 – If sk is a valid secret key.

• -1 – Otherwise.

int ocrypto_ecdh_p224_common_secret(uint8_t r[28], const uint8_t sk[28], const uint8_t pk[56])

ECDH P-224 common secret.

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

Remark

r may be same as sk or pk.

Parameters

• r – [out] Generated common secret.

• sk – Server private key.

• pk – Client public key.

Return values

• 0 – If sk is a valid secret key and pk is a valid public key.

• -1 – Otherwise.

ECDSA APIs

group ocrypto_ecdsa_p256

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

ECDSA P-256 is a specific implementation of a digital signature scheme.

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

• pk – [out] Generated public key.

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

Return values

• 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

• sig – [out] Generated signature.

• m – Input message.

• mlen – Length of m.

• sk – Secret key.

• ek – Session key.

Return values

• 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

• sig – [out] Generated signature.

• hash – Input hash.

• sk – Secret key.

• ek – Session key.

Return values

• 0 – If ek is a valid session key.

• -1 – Otherwise.

void ocrypto_ecdsa_p256_det_sign(uint8_t sig[64], const uint8_t *m, size_t mlen, const uint8_t sk[32])

ECDSA P-256 deterministic signature generation.

The message m is signed using the secret key sk and a session key calculated from message hash and key. The signature is put into sig.

Parameters

• sig – [out] Generated signature.

• m – Input message.

• mlen – Length of m.

• sk – Secret key.

void ocrypto_ecdsa_p256_det_sign_hash(uint8_t sig[64], const uint8_t hash[32], const uint8_t sk[32])

ECDSA P-256 deterministic signature generation from SHA256 hash.

The message hash hash is signed using the secret key sk and a session key calculated from hash and key. The signature is put into sig.

Parameters

• sig – [out] Generated signature.

• hash – Input hash.

• sk – Secret key.

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 values

• 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 values

• 0 – If the signature is valid.

• -1 – Otherwise.

group ocrypto_ecdsa_p224

Type declarations and APIs to do Elliptic Curve Digital Signature Algorithm using the NIST secp224r1 curve.

ECDSA P-224 is a specific implementation of a digital signature scheme.

Functions

int ocrypto_ecdsa_p224_public_key(uint8_t pk[56], const uint8_t sk[28])

ECDSA P-224 public key generation.

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

Parameters

• pk – [out] Generated public key.

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

Return values

• 0 – If sk is a valid secret key.

• -1 – Otherwise.

int ocrypto_ecdsa_p224_sign(uint8_t sig[56], const uint8_t *m, size_t mlen, const uint8_t sk[28], const uint8_t ek[28])

ECDSA P-224 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

• sig – [out] Generated signature.

• m – Input message.

• mlen – Length of m.

• sk – Secret key.

• ek – Session key.

Return values

• 0 – If ek is a valid session key.

• -1 – Otherwise.

int ocrypto_ecdsa_p224_sign_hash(uint8_t sig[56], const uint8_t hash[28], const uint8_t sk[28], const uint8_t ek[28])

ECDSA P-224 signature generation from SHA224 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

• sig – [out] Generated signature.

• hash – Input hash.

• sk – Secret key.

• ek – Session key.

Return values

• 0 – If ek is a valid session key.

• -1 – Otherwise.

int ocrypto_ecdsa_p224_verify(const uint8_t sig[56], const uint8_t *m, size_t mlen, const uint8_t pk[56])

ECDSA P-224 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 values

• 0 – If the signature is valid.

• -1 – Otherwise.

int ocrypto_ecdsa_p224_verify_hash(const uint8_t sig[56], const uint8_t hash[28], const uint8_t pk[56])

ECDSA P-224 signature verification from SHA224 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 values

• 0 – If the signature is valid.

• -1 – Otherwise.

Ed25519 APIs

group ocrypto_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 also

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

• pk – [out] 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

• sig – [out] 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 values

• 0 – If the signature is valid.

• -1 – Otherwise.

void ocrypto_ed25519_public_key_ctx(ocrypto_ed25519_ctx *ctx, uint8_t pk[(32)], const uint8_t sk[(32)])

Ed25519 signature key pair generation with context.

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

• ctx – Context.

• pk – [out] Generated public key.

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

void ocrypto_ed25519_sign_ctx(ocrypto_ed25519_ctx *ctx, 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 with context.

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

Parameters

• ctx – Context.

• sig – [out] Generated signature.

• m – Input message.

• m_len – Length of m.

• sk – Secret key.

• pk – Public key.

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

Ed25519 signature verification with context.

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

Parameters

• ctx – Context.

• sig – Input signature.

• m – Input message.

• m_len – Length of m.

• pk – Signer’s public key.

Return values

• 0 – If the signature is valid.

• -1 – Otherwise.

HKDF - HMAC based Key Derivation Function

group ocrypto_hkdf

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

HKDF APIs using SHA-256

group ocrypto_hkdf_sha256

Type declarations and APIs for the HKDF-SHA256 algorithm.

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

See also

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

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

• r – [out] Output key.

• r_len – Length of r.

• key – Input key.

• key_len – Length of key.

• salt – Salt.

• salt_len – Length of salt salt.

• info – Additional information.

• info_len – Length of info.

HKDF APIs using SHA-512

group ocrypto_hkdf_sha512

Type declaration and APIs for the HKDF-SHA512 algorithm.

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

See also

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

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

• r – [out] Output key.

• r_len – Length of r.

• key – Input key.

• key_len – Length of key.

• salt – Salt.

• salt_len – Length of salt salt.

• info – Additional information.

• info_len – Length of info.

HMAC - Hash-based Aessage Authentication Code

group ocrypto_hmac

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

HMAC APIs using SHA-256

group ocrypto_hmac_sha256

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 also

RFC 2104 - HMAC: Keyed-Hashing for Message Authentication

Incremental HMAC-SHA-256 generator.

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

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

HMAC-SHA-256 initialization.

The generator state ctx is initialized by this function.

Parameters

• ctx – [out] 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-SHA-256 incremental data input.

The generator state ctx is updated to authenticate 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

• 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-SHA-256 output.

The generator state ctx is updated to finalize the HMAC for the previously processed message chunks. The authenticator 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

• ctx – Generator state.

• r – [out] Generated HMAC value.

Defines

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 key. 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

• r – [out] HMAC output.

• key – HMAC key.

• key_len – Length of key.

• in – Input data.

• in_len – Length of in.

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

HMAC-SHA256 algorithm with AAD.

Parameters

• r – [out] HMAC output

• key – HMAC key.

• key_len – Length of key.

• in – Input data.

• in_len – Length of in.

• aad – Additional authentication data. May be NULL.

• aad_len – Length of aad.

HMAC APIs using SHA-512

group ocrypto_hmac_sha512

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 also

RFC 2104 - HMAC: Keyed-Hashing for Message Authentication

Incremental HMAC-SHA-512 generator.

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

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

HMAC-SHA-512 initialization.

The generator state ctx is initialized by this function.

Parameters

• ctx – [out] 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-SHA-512 incremental data input.

The generator state ctx is updated to authenticate 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

• 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-SHA-512 output.

The generator state ctx is updated to finalize the HMAC for the previously processed message chunks. The authenticator 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

• ctx – Generator state.

• r – [out] Generated HMAC value.

Defines

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 key. 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

• r – [out] HMAC output.

• key – HMAC key.

• key_len – Length of key.

• in – Input data.

• in_len – Length of in.

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

HMAC-SHA512 algorithm with AAD.

Parameters

• r – [out] HMAC output

• key – HMAC key.

• key_len – Length of key.

• in – Input data.

• in_len – Length of in.

• aad – Additional authentication data. May be NULL.

• aad_len – Length of aad.

RSA - Rivest-Shamir-Adleman algorithm

group ocrypto_rsa

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

RSA APIs

group ocrypto_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, PKCS1 V1.5, OEAP and PSS 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 m_len, const uint8_t *seed, size_t s_len, 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 may be same as m.

Parameters

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

• m – The message to be encrypted.

• m_len – Length of m. 0 <= m_len <= 117.

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

• s_len – Length of seed. s_len >= 125 - m_len

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

Return values

• -1 – If the message is too long (m_len > 117).

• -2 – If the seed is too short (s_len < 125 - m_len).

• 0 – On success.

int ocrypto_rsa1024_pkcs1_v15_decrypt(uint8_t *m, size_t m_len, const uint8_t c[128], const ocrypto_rsa1024_key *sk)

1024-bit RSA PKCS1 V1.5 decryption.

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_key.

Remark

m may be same as c.

Parameters

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

• m_len – Length of m.

• c – The 128-byte ciphertext to decrypt.

• sk – A valid 1024-bit RSA secret key.

Return values

• -1 – If decryption failed.

• -2 – If the output buffer is too short (m_len < 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 m_len, const uint8_t c[128], const ocrypto_rsa1024_crt_key *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

m may be same as c.

Parameters

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

• m_len – Length of m.

• c – The 128-byte ciphertext to decrypt.

• sk – A valid 1024-bit RSA secret key with CRT coefficients.

Return values

• -1 – If decryption failed.

• -2 – If the output buffer is too short (m_len < 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 m_len, const uint8_t *label, size_t l_len, 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 may be same as m.

Parameters

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

• m – The message to be encrypted.

• m_len – Length of m. 0 <= m_len <= 62.

• label – The label associated with the message.

• l_len – Length of label. May be 0.

• seed – 32-byte random seed.

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

Return values

• -1 – If the message is too long (m_len > 62).

• 0 – On success.

int ocrypto_rsa1024_oaep_sha256_decrypt(uint8_t *m, size_t m_len, const uint8_t c[128], const uint8_t *label, size_t l_len, const ocrypto_rsa1024_key *sk)

1024 bit RSA OAEP SHA256 decryption.

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_key.

Remark

m may be same as c.

Parameters

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

• m_len – Length of m.

• c – The 128 byte ciphertext to decrypt.

• label – The label associated with the message.

• l_len – Length of label. May be 0.

• sk – A valid 1024 bit RSA secret key.

Return values

• -1 – If decryption failed.

• -2 – If the output buffer is too short (m_len < 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 m_len, const uint8_t c[128], const uint8_t *label, size_t l_len, const ocrypto_rsa1024_crt_key *sk)

1024-bit RSA OAEP SHA256 decryption with CRT acceleration.

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

m may be same as c.

Parameters

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

• m_len – Length of m.

• c – The 128-byte ciphertext to decrypt.

• label – The label associated with the message.

• l_len – Length of label. May be 0.

• sk – A valid 1024-bit RSA secret key with CRT coefficients.

Return values

• -1 – If decryption failed.

• -2 – If the output buffer is too short (m_len < 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 m_len, const ocrypto_rsa1024_key *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_key.

Remark

s may be same as m.

Parameters

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

• m – The message to be signed.

• m_len – Length of m.

• sk – A valid 1024-bit RSA secret key.

Return values

0 – on success.

int ocrypto_rsa1024_pkcs1_v15_sha256_crt_sign(uint8_t s[128], const uint8_t *m, size_t m_len, const ocrypto_rsa1024_crt_key *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

s may be same as m.

Parameters

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

• m – The message to be signed.

• m_len – Length of m.

• sk – A valid 1024-bit RSA secret key with CRT coefficients.

Return values

0 –

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

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

The signature s of the input message m is verified.

Remark

The key pk should be initialized with ocrypto_rsa1024_init_pub_key.

Parameters

• s – The 128-byte signature.

• m – The signed message.

• m_len – Length of m.

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

Return values

• 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 m_len, const uint8_t *salt, size_t s_len, const ocrypto_rsa1024_key *sk)

1024-bit RSA PSS SHA-256 sign.

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_key.

Remark

s may be same as m.

Parameters

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

• m – The message to be signed.

• m_len – Length of m.

• salt – The salt to be used.

• s_len – Length of salt.

• sk – A valid 1024-bit RSA secret key.

Return values

• -2 – If the salt is too long.

• 0 – On success.

int ocrypto_rsa1024_pss_sha256_crt_sign(uint8_t s[128], const uint8_t *m, size_t m_len, const uint8_t *salt, size_t s_len, const ocrypto_rsa1024_crt_key *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa1024_init_crt_key.

Remark

s may be same as m.

Parameters

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

• m – The message to be signed.

• m_len – Length of m.

• salt – The salt to be used.

• s_len – Length of salt.

• sk – A valid 1024-bit RSA secret key with CRT coefficients.

Return values

• -2 – If the salt is too long.

• 0 – On success.

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

1024-bit RSA PSS SHA-256 signature verify.

The signature s of the input message m is verified.

Remark

The key pk should be initialized with ocrypto_rsa1024_init_pub_key.

Parameters

• s – The 128-byte signature.

• m – The signed message.

• m_len – Length of m.

• s_len – The length of the salt.

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

Return values

• 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 may be same as m.

Parameters

• c – [out] 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 values

• -1 – If the message is too long (mlen > 245).

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

• 0 – On success.

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

2048-bit RSA PKCS1 V1.5 decryption.

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_key.

Remark

m may be same as c.

Parameters

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

• mlen – Length of m.

• c – The 256-byte ciphertext to decrypt.

• sk – A valid 2048-bit RSA secret key.

Return values

• -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 *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

m may be same as c.

Parameters

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

• mlen – Length of m.

• c – The 256-byte ciphertext to decrypt.

• sk – A valid 2048-bit RSA secret key with CRT coefficients.

Return values

• -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 may be same as m.

Parameters

• c – [out] 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 values

• -1 – If the message is too long (mlen > 190).

• 0 – On success.

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 *sk)

2048-bit RSA OAEP SHA256 decryption.

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_key.

Remark

m may be same as c.

Parameters

• m – [out] 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.

• sk – A valid 2048-bit RSA secret key.

Return values

• -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 *sk)

2048-bit RSA OAEP SHA256 decryption with CRT acceleration.

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

m may be same as c.

Parameters

• m – [out] 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.

• sk – A valid 2048-bit RSA secret key with CRT coefficients.

Return values

• -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 *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_key.

Remark

s may be same as m.

Parameters

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

• m – The message to be signed.

• mlen – Length of m.

• sk – A valid 2048-bit RSA secret key.

Return values

0 –

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

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

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

s may be same as m.

Parameters

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

• m – The message to be signed.

• mlen – Length of m.

• sk – A valid 2048-bit RSA secret key with CRT coefficients.

Return values

0 –

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 of the input message m is verified.

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 values

• 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 *sk)

2048-bit RSA PSS SHA-256 sign.

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_key.

Remark

s may be same as m.

Parameters

• s – [out] 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.

• sk – A valid 2048-bit RSA secret key.

Return values

• -2 – If the salt is too long.

• 0 – On success.

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 *sk)

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

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

Remark

The key sk should be initialized with ocrypto_rsa2048_init_crt_key.

Remark

s may be same as m.

Parameters

• s – [out] 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.

• sk – A valid 2048-bit RSA secret key with CRT coefficients.

Return values

• -2 – If the salt is too long.

• 0 – On success.

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 of the input message m is verified.

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 values

• 0 – If the signature is valid.

• -1 – If verification failed.

• -2 – If the salt is too long.

RSA key APIs

group ocrypto_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 *pk, const uint8_t *n, size_t n_len)

1024-bit RSA public key setup.

Remark

The public exponent is fixed at 65537.

Parameters

• pk – [out] The initialized public key.

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

• n_len – Length of n.

Return values

• -1 – If the input length is invalid.

• 0 – On success.

int ocrypto_rsa1024_init_key(ocrypto_rsa1024_key *pk, const uint8_t *n, size_t n_len, const uint8_t *d, size_t d_len)

1024-bit RSA secret key setup.

Parameters

• pk – [out] The initialized public key.

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

• n_len – Length of n.

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

• d_len – Length of d.

Return values

• -1 – If the input length is invalid.

• 0 – On success.

int ocrypto_rsa1024_init_crt_key(ocrypto_rsa1024_crt_key *sk, const uint8_t *p, size_t p_len, const uint8_t *q, size_t q_len, const uint8_t *dp, size_t dp_len, const uint8_t *dq, size_t dq_len, const uint8_t *qinv, size_t qi_len)

1024-bit RSA secret key setup with CRT coefficients.

Parameters

• sk – [out] The initialized secret key.

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

• p_len – Length of p.

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

• q_len – Length of q.

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

• dp_len – Length of dp.

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

• dq_len – Length of dq.

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

• qi_len – Length of qinv.

Return values

• -1 – If the input length is invalid.

• 0 – On success.

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 *pk, const uint8_t *n, size_t n_len)

2048-bit RSA public key setup.

Remark

The public exponent is fixed at 65537.

Parameters

• pk – [out] The initialized public key.

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

• n_len – Length of n.

Return values

• -1 – If the input length is invalid.

• 0 – On success.

int ocrypto_rsa2048_init_key(ocrypto_rsa2048_key *sk, const uint8_t *n, size_t n_len, const uint8_t *d, size_t d_len)

2048-bit RSA secret key setup.

Parameters

• sk – [out] The initialized public key.

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

• n_len – Length of n.

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

• d_len – Length of d.

Return values

• -1 – If the input length is invalid.

• 0 – On success.

int ocrypto_rsa2048_init_crt_key(ocrypto_rsa2048_crt_key *sk, const uint8_t *p, size_t p_len, const uint8_t *q, size_t q_len, const uint8_t *dp, size_t dp_len, const uint8_t *dq, size_t dq_len, const uint8_t *qinv, size_t qi_len)

2048-bit RSA secret key setup with CRT coefficients.

Parameters

• sk – [out] The initialized secret key.

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

• p_len – Length of p.

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

• q_len – Length of q.

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

• dp_len – Length of dp.

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

• dq_len – Length of dq.

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

• qi_len – Length of qinv.

Return values

• -1 – If the input length is invalid.

• 0 – On success.

Defines

ocrypto_rsa_PUBLIC_EXPONENT

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 ocrypto_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

• ctx – [out] 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.

• r – [out] 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

• r – [out] Generated hash.

• in – Input data.

• in_len – Length of in.

SHA-512 APIs

group ocrypto_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

• ctx – [out] 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.

• r – [out] 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

• r – [out] Generated hash.

• in – Input data.

• in_len – Length of in.

SRP - Secure Remote Password APIs

group ocrypto_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 also

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

See also

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

• v – [out] 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

• pub_b – [out] 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

• u – [out] 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

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

• pub_a – Client public key.

• priv_b – Server private key.

• u – Scrambling parameter; generated with ocrypto_srp_scrambling_parameter.

• v – Password verifier.

Return values

• 0 – If pub_a is a valid public key.

• 1 – Otherwise.

int ocrypto_srp_server_premaster_secret(uint8_t s[(384)], const uint8_t pub_a[(384)], const uint8_t priv_b[(32)], const uint8_t *u, size_t u_len, const uint8_t v[(384)])

SRP-6 server 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

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

• pub_a – Client public key.

• priv_b – Server private key.

• u – Scrambling parameter; generated with ocrypto_srp_scrambling_parameter.

• u_len – Length of u.

• v – Password verifier.

Return values

• 0 – If pub_a is a valid public key.

• 1 – Otherwise.

int ocrypto_srp_client_premaster_secret(uint8_t s[(384)], const uint8_t priv_a[(32)], const uint8_t pub_b[(384)], const uint8_t k[(384)], const uint8_t *u, const uint8_t *h, size_t h_len)

SRP-6 client premaster secret.

Parameters

• s – [out] Generated premaster secret, must be 32 bit aligned.

• priv_a – Client private key.

• pub_b – Server public key.

• k – Multiplier.

• u – Scrambling parameter; generated with srp_scrambling_parameter.

• h – Password hash.

• h_len – Length of h and u.

Return values

• 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

• k – [out] 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

• m1 – [out] 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

• m2 – [out] Generated proof.

• pub_a – Client public key.

• m1 – First proof; generated with ocrypto_srp_proof_m1.

• k – Session key.

SRP-6 password verifier generation with context.

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

void ocrypto_srp_verifier_ctx(ocrypto_srp_ctx *ctx, 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

• ctx – Context.

• v – [out] 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 with context.

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

void ocrypto_srp_public_key_ctx(ocrypto_srp_ctx *ctx, 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

• ctx – Context.

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

• priv_b – Private key.

• v – Password verifier.

SRP-6 session key generation with context.

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_ctx(ocrypto_srp_ctx *ctx, 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

• ctx – Context.

• u – [out] Generated scrambling parameter.

• pub_a – Client public key.

• pub_b – Server public key.

int ocrypto_srp_premaster_secret_ctx(ocrypto_srp_ctx *ctx, 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 with context.

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

• ctx – Context.

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

• pub_a – Client public key.

• priv_b – Server private key.

• u – Scrambling parameter; generated with ocrypto_srp_scrambling_parameter.

• v – Password verifier.

Return values

• 0 – If pub_a is a valid public key.

• 1 – Otherwise.

void ocrypto_srp_session_key_ctx(ocrypto_srp_ctx *ctx, uint8_t k[(64)], const uint8_t s[(384)])

SRP-6 SRP session Key with context.

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

Parameters

• ctx – Context.

• k – [out] Generated SRP session key.

• s – Premaster secret.

SRP-6 proof exchange with context.

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_ctx(ocrypto_srp_ctx *ctx, 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) with context.

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

• ctx – Context.

• m1 – [out] 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_ctx(ocrypto_srp_ctx *ctx, 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) with context.

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

• ctx – Context.

• m2 – [out] Generated proof.

• pub_a – Client public key.

• m1 – First proof; generated with ocrypto_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.

Functions

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

SRP-6 Server Public Key.

Parameters

• pub_b – [out] Generated public key, must be 32 bit aligned.

• priv_b – Private key.

• k – Multiplier.

• v – Password verifier.

void ocrypto_srp_client_public_key(unsigned char pub_a[(384)], const unsigned char *priv_a, size_t a_len)

SRP - 6 Client Public Key.

Parameters

• pub_a – [out] Generated public key.

• priv_a – Private key.

• a_len – Length of priv_a.

SRPT - Secure Real-Time Transport Protocol APIs

group ocrypto_srtp

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

SRTP is an extension of the RTP protocol with an enhanced security mechanism.

Defines

ocrypto_srtp_AUTH_KEY_SIZE

SRTP Authentication Key Size.

ocrypto_srtp_SALT_SIZE

SRTP Salt Size.

ocrypto_srtp_MAX_KEY_SIZE

SRTP Maximum Key Size.

Functions

void ocrypto_srtp_setup_ctx(ocrypto_srtp_ctx *srtp_ctx, ocrypto_srtp_ctx *srtcp_ctx, const uint8_t *key, uint32_t key_size, const uint8_t *salt, uint32_t tag_size, uint32_t ssrc)

Setup SRTP contexts.

Parameters

• srtp_ctx – [out] SRTP context to be setup.

• srtcp_ctx – [out] SRTCP context to be setup.

• key – Master key.

• key_size – Size of the master key (16, 24, or 32 bytes).

• salt – Master salt (ocrypto_srtp_SALT_SIZE bytes).

• tag_size – Size of the authentication tag.

• ssrc – Synchronization source.

void ocrypto_srtp_encrypt(const ocrypto_srtp_ctx *srtp_ctx, uint8_t *packet, const uint8_t *data_bytes, size_t num_header_bytes, size_t num_data_bytes, uint32_t index)

Encrypt SRTP packet.

The final packet consists of num_header_bytes encrypted in place, followed by num_data_bytes copied from data_bytes during encryption.

Parameters

• srtp_ctx – SRTP context.

• packet – [inout] Encrypted packet.

• data_bytes – Data bytes to be encrypted.

• num_header_bytes – Number of header bytes.

• num_data_bytes – Number of data bytes.

• index – Packet index.

void ocrypto_srtp_decrypt(const ocrypto_srtp_ctx *srtp_ctx, uint8_t *data, const uint8_t *packet_bytes, size_t num_packet_bytes, uint32_t index)

Decrypt SRTP packet.

Parameters

• srtp_ctx – SRTP context.

• data – [out] Decrypted data.

• packet_bytes – Packet bytes.

• num_packet_bytes – Number of packet bytes.

• index – Packet index.

void ocrypto_srtp_authenticate(const ocrypto_srtp_ctx *srtp_ctx, uint8_t *tag, const uint8_t *bytes, size_t num_bytes, uint32_t index)

Generate SRTP authentication tag from bytes and index.

Parameters

• srtp_ctx – SRTP context.

• tag – [out] Authentication tag generated.

• bytes – Byte buffer.

• num_bytes – Number of bytes in buffer.

• index – Index.

int ocrypto_srtp_verify_authentication(const ocrypto_srtp_ctx *srtp_ctx, const uint8_t *tag, const uint8_t *bytes, size_t num_bytes, uint32_t index)

Check SRTP authentication tag against bytes and index.

Parameters

• srtp_ctx – SRTP context.

• tag – Tag.

• bytes – Byte buffer.

• num_bytes – Number of bytes in buffer.

• index – Index.

Return values

• 1 – If the tag is valid.

• 0 – Otherwise.

struct ocrypto_srtp_ctx

#include <ocrypto_srtp.h>

SRTP Context.

Public Members

uint32_t key_size

Key size [bytes].

uint32_t tag_size

Tag size [bytes].

uint8_t encr_key[(((size_t)32))]

Session encryption key (max 256 bits).

uint8_t auth_key[(20)]

Session authentication key 160 bits.

uint8_t salt_key[(14)]

Session salt 112 bits.