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 function 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 for 128 bit keys

NRF_CC3XX_PLATFORM_KMU_AES_ADDR_1: Address of the first 128 bits of AES key in CryptoCell

NRF_CC3XX_PLATFORM_KMU_AES_ADDR_2: Address of the subsequent bits of AES key register in CryptoCell HW

Note

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

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

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_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 cc_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.

CC3XX Platform - HMAC-DRBG APIs 

group nrf_cc3xx_platform_hmac_drbg

The nrf_cc3xx_platform_hmac_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_hmac_drbg but do not require setting up memory allocation before use.

Defines

NRF_CC3XX_PLATFORM_HMAC_CTX_SIZE_WORDS

Macro holding size of the opaque hmac_drbg context type.

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

Functions

int nrf_cc3xx_platform_hmac_drbg_init(nrf_cc3xx_platform_hmac_drbg_context_t *const context, const uint8_t *pers_string, size_t pers_string_len)

Function that initializes an hmac_drbg context.

Note

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

Parameters:

context – [inout] Pointer to structure holding the hmac_drbg context which must be used for subsequent calls to generate random data.
pers_string – [in] Personalization string used for the HMAC_DRBG_Instantiate_algorithm.
pers_string_len – [in] Length of the personalization string in bytes, which may be zero.

Returns:

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a non-zero failure according to the API mbedtls_hmac_drbg_seed.

void nrf_cc3xx_platform_hmac_drbg_free(nrf_cc3xx_platform_hmac_drbg_context_t *const context)

Function that deinitializes a hmac_drbg context.

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

int nrf_cc3xx_platform_hmac_drbg_set_pr(nrf_cc3xx_platform_hmac_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_hmac_drbg_get and nrf_cc3xx_platform_hmac_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_hmac_drbg_init

Note

The default configuration is to have prediction resistance turned off.

Parameters:

context – [inout] Pointer to a structure holding the hmac_drbg context.
pr_enabled – [in] Enables prediction resistance if true, otherwise false (default).

Returns:

NRF_CC3XX_PLATFORM_SUCCESS on success, NRF_CC3XX_PLATFORM_ERROR_ENTROPY_NOT_INITIALIZED when entropy is not initialized

int nrf_cc3xx_platform_hmac_drbg_set_reseed_interval(nrf_cc3xx_platform_hmac_drbg_context_t *const context, int interval)

Function to change the reseed interval.

This API controls when the hmac_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_hmac_drbg_init.

Note

Changing the reseed interval is optional.

Parameters:

context – [inout] Pointer to a structure holding the hmac_drbg context.
interval – [in] New reseed interval value.

Returns:

NRF_CC3XX_PLATFORM_SUCCESS on success, NRF_CC3XX_PLATFORM_ERROR_ENTROPY_NOT_INITIALIZED when entropy is not initialized

int nrf_cc3xx_platform_hmac_drbg_reseed(nrf_cc3xx_platform_hmac_drbg_context_t *const context, const uint8_t *additional, size_t add_len)

Function to do a manual reseed of hmac_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_hmac_drbg_get and nrf_cc3xx_platform_hmac_drbg_get_with_add functions will reseed automatically according to the reseed interval in the built-in mbedtls_hmac_drbg context.

Note

Before calling this API the context to must be initialized by calling nrf_cc3xx_platform_hmac_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 hmac_drbg is executed with prediction resistance turned on.

Parameters:

context – [inout] Pointer to a structure holding the hmac_drbg context.
additional – [in] Optional additional input to use for HMAC_DRBG_Reseed_function.
add_len – [in] Length of the additional input in bytes, may be zero.

Returns:

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a non-zero failure according to the API mbedtls_hmac_drbg_reseed.

int nrf_cc3xx_platform_hmac_drbg_get_with_add(nrf_cc3xx_platform_hmac_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 hmac_drbg and an additional string of data.

This function will calculate PRNG using HW accelerated HMAC(with SHA256) 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_hmac_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 hmac_drbg context.
buffer – [out] Pointer to buffer to hold PRNG data.
len – [in] Length of PRNG to get in bytes.
olen – [out] Length reported output in bytes.
additional – [in] Additional input to use with HMAC_DRBG_Generate_algorithm.
add_len – [in] Length of HMAC_DRBG additional input in bytes.

Returns:

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a non-zero failure according to the API mbedtls_hmac_drbg_get_with_add.

int nrf_cc3xx_platform_hmac_drbg_get(nrf_cc3xx_platform_hmac_drbg_context_t *const context, uint8_t *buffer, size_t len, size_t *olen)

Function to get PRNG data using hmac_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_hmac_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 hmac_drbg context.
buffer – [out] Pointer to buffer to hold PRNG data.
len – [in] Length of PRNG to get in bytes.
olen – [out] Actual number of bytes put into the buffer.

Returns:

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

Returns:

NRF_CC3XX_PLATFORM_SUCCESS on success, otherwise a non-zero failure according to the API mbedtls_hmac_drbg_random_with_add.

struct nrf_cc3xx_platform_hmac_drbg_context_t

#include <nrf_cc3xx_platform_hmac_drbg.h>

Opaque type for the context required for hmac_drbg generation.

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

Public Members

uint32_t is_initialized: Mask indicating if the hmac_drbg context has been initialized.

uint32_t buffer[(147)]: Internal buffer for the built-in entropy and hmac_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 request 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 request 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 request 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 request 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 

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-CBC - AES Cipher Block Chaining Mode

group ocrypto_aes_cbc

Type definitions and APIs for AES-CBC (AES Cipher Block Chaining).

AES-CBC (AES Cipher Block Chaining) is an AES block cipher mode which avoids the problems of the ECB mode by xoring each plaintext block with the previous ciphertext block before being encrypted.

Incremental AES-CBC encryption/decryption.

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

void ocrypto_aes_cbc_init_enc(ocrypto_aes_cbc_ctx *ctx, const uint8_t *key, size_t size, const uint8_t iv[16])

AES-CBC encrypt 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_cbc_init_dec(ocrypto_aes_cbc_ctx *ctx, const uint8_t *key, size_t size, const uint8_t iv[16])

AES-CBC decrypt 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_cbc_update_enc(ocrypto_aes_cbc_ctx *ctx, uint8_t *ct, const uint8_t *pt, size_t pt_len)

AES-CBC 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 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. Must be a multiple of the block size.

void ocrypto_aes_cbc_update_dec(ocrypto_aes_cbc_ctx *ctx, uint8_t *pt, const uint8_t *ct, size_t ct_len)

AES-CBC 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 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.
pt – [out] Plaintext.
ct – Ciphertext.
ct_len – Length of ct and pt. Must be a multiple of the block size.

Functions

void ocrypto_aes_cbc_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-CBC encryption.

Remark

ct may be same as pt.

Parameters:

ct – [out] Ciphertext.
pt – Plaintext.
pt_len – Plaintext length.
key – AES key.
size – Key size (16, 24, or 32).
iv – Initial vector.

void ocrypto_aes_cbc_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-CBC decryption.

Remark

ct may be same as pt.

Parameters:

pt – [out] Plaintext.
ct – Ciphertext.
ct_len – Ciphertext length.
key – AES key.
size – Key size (16, 24, or 32).
iv – Initial vector.

AES-CBC - AES CCipher Block Chaining Mode with PKCS7 padding

group ocrypto_aes_cbc_pkcs7

Type definitions and APIs for AES-CBC-PKCS7 (AES Cipher Block Chaining with PKCS7 padding).

AES-CBC (AES Cipher Block Chaining) is an AES block cipher mode which avoids the problems of the ECB mode by xoring each plaintext block with the previous ciphertext block before being encrypted. PKCS7 padding allows encoding/decoding of arbitrarily sized messages.

Incremental AES-CBC encryption/decryption.

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

void ocrypto_aes_cbc_pkcs_init(ocrypto_aes_cbc_pkcs_ctx *ctx, const uint8_t *key, size_t size, const uint8_t iv[16], int decrypt)

AES-CBC 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. If not set by the same call, key must be set before iv.

Parameters:

ctx – [out] Context.
key – AES key. May be NULL.
size – Key size (16, 24, or 32 bytes).
iv – Initial vector. May be NULL.
decrypt – If 0, initialize for encryption; If 1, initialize for decryption.

size_t ocrypto_aes_cbc_pkcs_output_size(ocrypto_aes_cbc_pkcs_ctx *ctx, size_t pt_len)

AES-CBC output size calculation.

Calculates the length of the output written to out in a call to ocrypto_aes_cbc_pkcs_update.

Remark

ocrypto_aes_cbc_pkcs_output_size must be called before ocrypto_aes_cbc_pkcs_update.

Remark

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

Parameters:

ctx – Context.
pt_len – Length of data to be added.

Returns:

The length of the output.

void ocrypto_aes_cbc_pkcs_update(ocrypto_aes_cbc_pkcs_ctx *ctx, uint8_t *out, const uint8_t *in, size_t in_len)

AES-CBC incremental encryption/decryption.

The input in is encrypted or decrypted to the output out using the context ctx.

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

Remark

in may be same as out.

Remark

A single common buffer may be used for the whole plaintext and ciphertext if in and out of the first call are equal and incremented individually by the input and output size for each further call (meaning the plaintext and ciphertext are stored contiguously in the common buffer).

Remark

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

Remark

The maximum length of out is in_len + 15.

Remark

The exact length of out is returned by ocrypto_aes_cbc_pkcs_output_size.

Parameters:

ctx – Context.
out – [out] Output, ciphertext for encryption, plaintext for decryption.
in – Input, plaintext for encryption, ciphertext for decryption.
in_len – Length of in.

void ocrypto_aes_cbc_pkcs_final_enc(ocrypto_aes_cbc_pkcs_ctx *ctx, uint8_t ct[16])

AES-CBC-PKCS7 final encryption output.

Parameters:

ctx – Context.
ct – [out] Last ciphertext block.

int ocrypto_aes_cbc_pkcs_final_dec(ocrypto_aes_cbc_pkcs_ctx *ctx, uint8_t *pt, size_t *pt_len)

AES-CBC-PKCS7 final decryption output.

Remark

The total length of the ciphertext added before a call to this function must be non-zero and a multiple of 16.

Remark

The maximum length of pt is 15.

Parameters:

ctx – Context.
pt – [out] Last part of the plaintext.
pt_len – [out] Length of pt.

Return values:

0 – If the ciphertext input is properly padded.
-1 – Otherwise.

Functions

void ocrypto_aes_cbc_pkcs_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-CBC-PKCS7 encryption.

Remark

ct may be same as pt.

Remark

The length of ct is pt_len + 1 rounded up to the next multiple of 16.

Parameters:

ct – [out] Ciphertext.
pt – Plaintext.
pt_len – Plaintext length.
key – AES key.
size – Key size (16, 24, or 32).
iv – Initial vector.

int ocrypto_aes_cbc_pkcs_decrypt(uint8_t *pt, size_t *pt_len, const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size, const uint8_t iv[16])

AES-CBC-PKCS7 decryption.

Remark

pt may be same as ct.

Remark

The maximum length of pt is ct_len - 1.

Parameters:

pt – [out] Plaintext.
pt_len – [out] Plaintext length.
ct – Ciphertext.
ct_len – Ciphertext length. Must be a multiple of 16.
key – AES key.
size – Key size (16, 24, or 32).
iv – Initial vector.

Return values:

0 – If the input is properly padded.
-1 – Otherwise.

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 Mode

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-CBC - AES Electronic Code Book Mode

group ocrypto_aes_ecb

Type definitions and APIs for AES-ECB (AES Electronic Codebook).

AES-ECB (AES Electronic Codebook) is a simple AES block cipher mode.

Incremental AES-ECB encryption/decryption.

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

void ocrypto_aes_ecb_init_enc(ocrypto_aes_ecb_ctx *ctx, const uint8_t *key, size_t size)

AES-ECB encrypt initialization.

The context ctx is initialized using the given key key.

Parameters:

ctx – [out] Context.
key – AES key.
size – Key size (16, 24, or 32 bytes).

void ocrypto_aes_ecb_init_dec(ocrypto_aes_ecb_ctx *ctx, const uint8_t *key, size_t size)

AES-ECB decrypt initialization.

The context ctx is initialized using the given key key.

Parameters:

ctx – [out] Context.
key – AES key.
size – Key size (16, 24, or 32 bytes).

void ocrypto_aes_ecb_update_enc(ocrypto_aes_ecb_ctx *ctx, uint8_t *ct, const uint8_t *pt, size_t pt_len)

AES-ECB 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 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. Must be a multiple of the block size.

void ocrypto_aes_ecb_update_dec(ocrypto_aes_ecb_ctx *ctx, uint8_t *pt, const uint8_t *ct, size_t ct_len)

AES-ECB 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 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.
pt – [out] Plaintext.
ct – Ciphertext.
ct_len – Length of ct and pt. Must be a multiple of the block size.

Functions

void ocrypto_aes_ecb_encrypt(uint8_t *ct, const uint8_t *pt, size_t pt_len, const uint8_t *key, size_t size)

AES-ECB encryption.

Remark

ct may be same as pt.

Parameters:

ct – [out] Ciphertext.
pt – Plaintext.
pt_len – Length of ct and pt.
key – AES key.
size – Key size (16, 24, or 32).

void ocrypto_aes_ecb_decrypt(uint8_t *pt, const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size)

AES-ECB decryption.

Remark

ct may be same as pt.

Parameters:

pt – [out] Plaintext.
ct – Ciphertext.
ct_len – Length of ct and pt.
key – AES key.
size – Key size (16, 24, or 32).

AES-CCM - AES Cipher-based Message Authentication Code

group ocrypto_aes_cmac

Type definitions and APIs for AES-CMAC (AES Cipher-based Message Authentication Code).

AES-CMAC (AES Cipher-based Message Authentication Code) is a block cipher-based message authentication code algorithm. The AES block cipher primitive is used in variant of the CBC mode to get the authentication tag.

Defines

ocrypto_aes_cmac_prf128_BYTES: Length of the pseudo random function.

Functions

void ocrypto_aes_cmac_authenticate(uint8_t *tag, size_t tag_len, const uint8_t *msg, size_t msg_len, const uint8_t *key, size_t size)

AES-CMAC authentication algorithm.

Parameters:

tag – [out] Resulting tag.
tag_len – Tag length, 0 < tag_len <= 16.
msg – Message to authenticate.
msg_len – Message length.
key – AES key.
size – Key size (16, 24, or 32).

void ocrypto_aes_cmac_prf128(uint8_t prf[(16)], const uint8_t *msg, size_t msg_len, const uint8_t *key, size_t key_len)

AES-CMAC-PRF-128 pseudo random function algorithm.

Parameters:

prf – [out] 16 byte PRF output.
msg – Message input.
msg_len – Message length.
key – Key.
key_len – Key length.

AES-CCM - AES Counter with CBC-MAC Mode

group ocrypto_aes_ccm

Type definitions and APIs for AES-CCM (AES Counter mode with CBC-MAC).

AES-CCM (AES counter mode with CBC-MAC) 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 an AES CBC-MAC is used for authentication.

Incremental AES-CCM encryption/decryption.

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

void ocrypto_aes_ccm_init(ocrypto_aes_ccm_ctx *ctx, const uint8_t *key, size_t size, const uint8_t *nonce, size_t n_len, size_t tag_len, size_t pt_len, size_t aa_len)

AES-CCM initialization.

The context ctx is initialized using the given key key and nonce nonce.

Remark

If key is NULL only nonce and lengths are set. If nonce is NULL only key is set. Both key and nonce 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).
nonce – Nonce. May be NULL.
n_len – Nonce length, 7 <= n_len <= 13.
tag_len – Tag length (4, 6, 8, 10, 12, 14, or 16).
pt_len – Plaintext length, 0 <= pt_len < 2^(8*(15-n_len)).
aa_len – Additional authentication data length.

void ocrypto_aes_ccm_update_aad(ocrypto_aes_ccm_ctx *ctx, const uint8_t *aa, size_t aa_len)

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

Remark

ocrypto_aes_ccm_update_aad must be called before any call to ocrypto_aes_ccm_update_enc or ocrypto_aes_ccm_update_dec.

Parameters:

ctx – Generator state.
aa – Additional authenticated data.
aa_len – Length of a.

void ocrypto_aes_ccm_update_enc(ocrypto_aes_ccm_ctx *ctx, uint8_t *ct, const uint8_t *pt, size_t pt_len)

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

Remark

Initialization of the context ctx through ocrypto_aes_ccm_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_ccm_update_dec(ocrypto_aes_ccm_ctx *ctx, uint8_t *pt, const uint8_t *ct, size_t ct_len)

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

Remark

Initialization of the context ctx through ocrypto_aes_ccm_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_ccm_final_enc(ocrypto_aes_ccm_ctx *ctx, uint8_t *tag, size_t tag_len)

AES-CCM 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 – Length of tag.

int ocrypto_aes_ccm_final_dec(ocrypto_aes_ccm_ctx *ctx, const uint8_t *tag, size_t tag_len)

AES-CCM 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 – Length of tag.

Return values:

0 – If tag is valid.
-1 – Otherwise.

Functions

void ocrypto_aes_ccm_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 *nonce, size_t n_len, const uint8_t *aa, size_t aa_len)

AES-CCM encryption.

Remark

ct may be same as pt.

Parameters:

ct – [out] Ciphertext.
tag – [out] Authentication tag.
tag_len – Tag length (4, 6, 8, 10, 12, 14, or 16).
pt – Plaintext.
pt_len – Plaintext length, 0 <= pt_len < 2^(8*(15-n_len)).
key – AES key.
size – Key size (16, 24, or 32).
nonce – Nonce.
n_len – Nonce length, 7 <= n_len <= 13.
aa – Additional authentication data.
aa_len – Additional authentication data length.

int ocrypto_aes_ccm_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 *nonce, size_t n_len, const uint8_t *aa, size_t aa_len)

AES-CCM decryption.

Remark

ct may be same as pt.

Parameters:

pt – [out] Plaintext.
tag – Authentication tag.
tag_len – Tag length (4, 6, 8, 10, 12, 14, or 16).
ct – Ciphertext.
ct_len – Ciphertext length, 0 <= ct_len < 2^(8*(15-n_len)).
key – AES key.
size – Key size (16, 24, or 32).
nonce – Nonce.
n_len – Nonce length, 7 <= n_len <= 13.
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

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

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

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

group ocrypto_chacha_poly_inc

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

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

The ChaCha20 stream cipher is combined with the Poly1305 authenticator.

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

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

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 writen 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 

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.

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.

ocrypto_constant_time_fill(x, val, length)

Variable length fill with a fixed value.

Parameters:

x – Memory region to be filled with value.
val – Value filled into memory.
length – Number of bytes to fill.

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 secp224r1 low-level 

group ocrypto_p224

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

Functions

int ocrypto_curve_p224_from28bytes(ocrypto_cp_p224 *r, const uint8_t p[28])

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_p224_from56bytes(ocrypto_cp_p224 *r, const uint8_t p[56])

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_p224_to28bytes(uint8_t r[28], ocrypto_cp_p224 *p)

Store p.x to bytes.

Parameters:

r – [out] x stored as array.
p – Point with x to be stored.

void ocrypto_curve_p224_to56bytes(uint8_t r[56], ocrypto_cp_p224 *p)

Store p.x to bytes.

Parameters:

r – [out] Point stored as array.
p – Point to be stored.

int ocrypto_curve_p224_scalarmult(ocrypto_cp_p224 *r, const ocrypto_cp_p224 *p, const ocrypto_sc_p224 *s)

P224 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_p224_scalarmult_base(ocrypto_cp_p224 *r, const ocrypto_sc_p224 *s)

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

int ocrypto_curve_p224_add(ocrypto_cp_p224 *r, const ocrypto_cp_p224 *p, const ocrypto_cp_p224 *q)

P224 add and double

r = p + q p == [0,0] -> r = q q == [0,0] -> r = p p == -q -> r = [0,0]

Parameters:

r – [out] Resulting point
p – Input point.
q – input point.

Return values:

-1 – if r = [0,0].
0 – if successfull.

ECC secp256r1 low-level 

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 

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

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 

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.

Remark

To generate a valid secret key use the following code pattern:

do get_random(sk); while (ocrypto_ecdh_p224_secret_key_check(sk));

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 pk[56], const uint8_t sk[28])

ECDH P-224 public key generation.

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

Remark

pk may be same as sk.

Remark

To generate a valid key pair use the following code pattern:

do get_random(sk); while (ocrypto_ecdh_p224_public_key(pk, sk));

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

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 pk[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.
pk – [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.

Remark

To generate a valid secret key use the following code pattern:

do get_random(sk); while (ocrypto_ecdh_p256_secret_key_check(sk));

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 pk[64], const uint8_t sk[32])

ECDH P-256 public key generation.

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

Remark

pk may be same as sk.

Remark

To generate a valid key pair use the following code pattern:

do get_random(sk); while (ocrypto_ecdh_p256_public_key(pk, sk));

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_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_p384

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

Functions

int ocrypto_ecdh_p384_secret_key_check(const uint8_t sk[48])

ECDH P-384 secret key check.

Remark

To generate a valid secret key use the following code pattern:

do get_random(sk); while (ocrypto_ecdh_p384_secret_key_check(sk));

Parameters:

sk – Secret key to check.

Return values:

0 – If sk is a valid secret key.
-1 – Otherwise.

int ocrypto_ecdh_p384_public_key_check(const uint8_t pk[96])

ECDH P-384 public key check.

Parameters:

pk – Public key to check.

Return values:

0 – If pk is a valid public key.
-1 – Otherwise.

int ocrypto_ecdh_p384_public_key(uint8_t pk[96], const uint8_t sk[48])

ECDH P-384 public key generation.

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

Remark

pk may be same as sk.

Remark

To generate a valid key pair use the following code pattern:

do get_random(sk); while (ocrypto_ecdh_p384_public_key(pk, sk));

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_ecdh_p384_common_secret(uint8_t r[48], const uint8_t sk[48], const uint8_t pk[96])

ECDH P-384 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 

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.

Remark

To generate a valid key pair use the following code pattern:

do get_random(sk); while (ocrypto_ecdsa_p224_public_key(pk, sk));

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.

Remark

To generate a valid signature use the following code pattern:

do get_random(ek); while (ocrypto_ecdsa_p224_sign(sig, m, mlen, sk, ek));

Parameters:

sig – [out] Generated signature.
m – Input message.
mlen – Length of m.
sk – Secret key.
ek – Session key. Must be pre-filled with random data.

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.

Remark

To generate a valid signature use the following code pattern:

do get_random(ek); while (ocrypto_ecdsa_p224_sign_hash(sig, hash, sk, ek));

Parameters:

sig – [out] Generated signature.
hash – Input hash.
sk – Secret key.
ek – Session key. Must be pre-filled with random data.

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.

group ocrypto_ecdsa_p256

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

Type declarations and APIs to do Elliptic Curve Digital Signature Algorith 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.

Remark

To generate a valid key pair use the following code pattern:

do get_random(sk); while (ocrypto_ecdsa_p256_public_key(pk, sk));

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.

Remark

To generate a valid signature use the following code pattern:

do get_random(ek); while (ocrypto_ecdsa_p256_sign(sig, m, mlen, sk, ek));

Parameters:

sig – [out] Generated signature.
m – Input message.
mlen – Length of m.
sk – Secret key.
ek – Session key. Must be pre-filled with random data.

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.

Remark

To generate a valid signature use the following code pattern:

do get_random(ek); while (ocrypto_ecdsa_p256_sign_hash(sig, hash, sk, ek));

Parameters:

sig – [out] Generated signature.
hash – Input hash.
sk – Secret key.
ek – Session key. Must be pre-filled with random data.

Return values:

0 – If ek is a valid session key.
-1 – Otherwise.

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

ECDSA P-256 signature verification.

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

Parameters:

sig – Input signature.
m – Input message.
mlen – Length of m.
pk – Signer’s public key.

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

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.

group ocrypto_ecdsa_p384

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

Functions

int ocrypto_ecdsa_p384_public_key(uint8_t pk[96], const uint8_t sk[48])

ECDSA P-384 public key generation.

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

Remark

To generate a valid key pair use the following code pattern:

do get_random(sk); while (ocrypto_ecdsa_p384_public_key(pk, sk));

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_p384_sign(uint8_t sig[96], const uint8_t *m, size_t mlen, const uint8_t sk[48], const uint8_t ek[48])

ECDSA P-384 signature generation.

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

Remark

To generate a valid signature use the following code pattern:

do get_random(ek); while (ocrypto_ecdsa_p384_sign(sig, m, mlen, sk, ek));

Parameters:

sig – [out] Generated signature.
m – Input message.
mlen – Length of m.
sk – Secret key.
ek – Session key. Must be pre-filled with random data.

Return values:

0 – If ek is a valid session key.
-1 – Otherwise.

int ocrypto_ecdsa_p384_sign_hash(uint8_t sig[96], const uint8_t hash[48], const uint8_t sk[48], const uint8_t ek[48])

ECDSA P-384 signature generation from SHA384 hash.

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

Remark

To generate a valid signature use the following code pattern:

do get_random(ek); while (ocrypto_ecdsa_p384_sign_hash(sig, hash, sk, ek));

Parameters:

sig – [out] Generated signature.
hash – Input hash.
sk – Secret key.
ek – Session key. Must be pre-filled with random data.

Return values:

0 – If ek is a valid session key.
-1 – Otherwise.

int ocrypto_ecdsa_p384_verify(const uint8_t sig[96], const uint8_t *m, size_t mlen, const uint8_t pk[96])

ECDSA P-384 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_p384_verify_hash(const uint8_t sig[96], const uint8_t hash[48], const uint8_t pk[96])

ECDSA P-384 signature verification from SHA384 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.

Warning

doxygengroup: Cannot find group “ocrypto_ecdsa_p521” in doxygen xml output for project “nrfxlib” from directory: /home/runner/work/sdk-nrf/sdk-nrf/ncs/nrf/doc/_build/nrfxlib/doxygen/xml

EC-JPAKE 

group ocrypto_ecjpake

Type declarations and APIs for EC-JPAKE-P256.

Functions

int ocrypto_ecjpake_get_public_key(uint8_t X[64], const uint8_t G[64], const uint8_t x[32])

EC-JPAKE-P256 public key.

Parameters:

X – [out] Public key.
G – Generator. May be NULL to use the default generator.
x – Secret key. 0 < x < group order

Return values:

0 – If inputs are valid.
-1 – Otherwise.

void ocrypto_ecjpake_get_zkp_hash(uint8_t hash[32], const uint8_t X[64], const uint8_t V[64], const uint8_t G[64], const char *id, size_t id_len)

EC-JPAKE-P256 zero knowledge proof hash.

Parameters:

hash – [out] Generated hash.
X – Public key.
V – ZKP ephemeral public key.
G – Generator. May be NULL to use the default generator.
id – Identity of originator.
id_len – Identity length.

int ocrypto_ecjpake_zkp_sign(uint8_t r[32], const uint8_t x[32], const uint8_t v[32], const uint8_t *hash, size_t hash_len)

EC-JPAKE-P256 zero knowledge proof generation.

Parameters:

r – [out] ZKP signature.
x – Secret key. 0 < x < group order
v – ZKP ephemeral secret key. 0 < v < group order
hash – Identity of originator.
hash_len – Identity length.

Return values:

0 – If inputs are valid.
-1 – Otherwise.

int ocrypto_ecjpake_zkp_verify(const uint8_t G[64], const uint8_t X[64], const uint8_t V[64], const uint8_t r[32], const uint8_t *hash, size_t hash_len)

EC-JPAKE-P256 zero knowledge proof verification.

Parameters:

G – Generator. May be NULL to use the default generator.
X – Public key.
V – ZKP ephemeral public key.
r – ZKP signature.
hash – Identity of originator.
hash_len – Identity length.

Return values:

0 – If the proof is valid.
-1 – Otherwise.

int ocrypto_ecjpake_get_key(uint8_t X[64], uint8_t V[64], uint8_t r[32], const uint8_t G[64], const uint8_t x[32], const uint8_t v[32], const char *id, size_t id_len)

EC-JPAKE-P256 public key and zero knowledge proof generation.

Parameters:

X – [out] Public key.
V – [out] ZKP ephemeral public key.
r – [out] ZKP signature.
G – Generator. May be NULL to use the default generator.
x – Secret key. 0 < x < group order
v – ZKP ephemeral secret key. 0 < v < group order
id – Identity of originator.
id_len – Identity length.

Return values:

0 – If inputs are valid.
-1 – Otherwise.

int ocrypto_ecjpake_verify_key(const uint8_t G[64], const uint8_t X[64], const uint8_t V[64], const uint8_t r[32], const char *id, size_t id_len)

EC-JPAKE-P256 zero knowledge proof verification.

Parameters:

G – Generator. May be NULL to use the default generator.
X – Public key.
V – ZKP ephemeral public key.
r – ZKP signature.
id – Identity of originator.
id_len – Identity length.

Return values:

0 – If proof is valid.
-1 – Otherwise.

int ocrypto_ecjpake_get_generator(uint8_t G[64], const uint8_t X1[64], const uint8_t X2[64], const uint8_t X3[64])

EC-JPAKE-P256 generator derivation.

Parameters:

G – [out] Generator.
X1 – Public key 1.
X2 – Public key 2.
X3 – Public key 3.

Return values:

0 – If the generator is valid.
-1 – Otherwise.

void ocrypto_ecjpake_read_shared_secret(uint8_t rs[32], const uint8_t *secret, size_t secret_len)

EC-JPAKE-P256 read shared secret.

Parameters:

rs – [out] Reduced shared secret.
secret – Shared secret.
secret_len – Secret length.

int ocrypto_ecjpake_process_shared_secret(uint8_t xs[32], const uint8_t x2[32], const uint8_t rs[32])

EC-JPAKE-P256 shared secret handling.

Parameters:

xs – [out] Client/server secret key.
x2 – Secret key 2.
rs – Reduced shared secret.

Return values:

0 – If the derived secret key is valid.
-1 – Otherwise.

int ocrypto_ecjpake_get_premaster_secret_key(uint8_t secret[64], const uint8_t Xr[64], const uint8_t X2[64], const uint8_t xs[32], const uint8_t x2[32])

EC-JPAKE-P256 premaster secret key generation.

Parameters:

secret – [out] Resulting premaster secret key (curve point).
Xr – Remote client/server public key.
X2 – Remote public key 2.
xs – Client/server secret key.
x2 – Secret key 2.

Return values:

0 – If the premaster secret key is valid.
-1 – Otherwise.

int ocrypto_ecjpake_get_premaster_secret(uint8_t secret[32], const uint8_t Xr[64], const uint8_t X2[64], const uint8_t xs[32], const uint8_t x2[32])

EC-JPAKE-P256 premaster secret generation.

Parameters:

secret – [out] Resulting premaster secret.
Xr – Remote client/server public key.
X2 – Remote public key 2.
xs – Client/server secret key.
x2 – Secret key 2.

Return values:

0 – If the secret is valid.
-1 – Otherwise.

Ed25519 

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.

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

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.

group ocrypto_ed25519ph

Type declarations and APIs for the Ed25519ph algorithm.

Ed25519ph is a specific implementation of EdDSA, a digital signature scheme with prehashing. 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. Ed25519ph is intended to provide attack resistance comparable to quality 128-bit symmetric ciphers.

Defines

ocrypto_ed25519ph_PUBLIC_KEY_BYTES: Length of a public key.

ocrypto_ed25519ph_SECRET_KEY_BYTES: Length of a secret key.

ocrypto_ed25519ph_HASH_BYTES: Length of a message hash.

ocrypto_ed25519ph_BYTES: Length of a signature.

Functions

void ocrypto_ed25519ph_public_key(uint8_t pk[(32)], const uint8_t sk[(32)])

Ed25519ph 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_ed25519ph_sign(uint8_t sig[(64)], const uint8_t hash[(64)], const uint8_t sk[(32)], const uint8_t pk[(32)])

Ed25519ph 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.
hash – Message hash, SHA-512(message).
sk – Secret key.
pk – Public key.

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

Ed25519ph signature verification.

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

Parameters:

sig – Input signature.
hash – Message hash, SHA-512(message).
pk – Signer’s public key.

Return values:

0 – If the signature is valid.
-1 – Otherwise.

void ocrypto_ed25519ph_public_key_ctx(ocrypto_ed25519ph_ctx *ctx, uint8_t pk[(32)], const uint8_t sk[(32)])

Ed25519ph 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_ed25519ph_sign_ctx(ocrypto_ed25519ph_ctx *ctx, uint8_t sig[(64)], const uint8_t hash[(64)], const uint8_t sk[(32)], const uint8_t pk[(32)])

Ed25519ph 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.
hash – Message hash, SHA-512(message).
sk – Secret key.
pk – Public key.

int ocrypto_ed25519ph_verify_ctx(ocrypto_ed25519ph_ctx *ctx, const uint8_t sig[(64)], const uint8_t hash[(64)], const uint8_t pk[(32)])

Ed25519ph 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.
hash – Message hash, SHA-512(message).
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 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.

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 using SHA-512

group ocrypto_hkdf_512

Type declaration and APIs for the HKDF-SHA512 algorithm.

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

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 Message Authentication Code 

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

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

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

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.

PBKDF2 

group ocrypto_pbkdf2

Type declaration and APIs for PBKDF2 with AES-CMAC-PRF-128.

Type declaration and APIs for PBKDF2 with HMAC-SHA256.

Type declaration and APIs for PBKDF2 with HMAC-SHA1.

PBKDF2 with HMAC-AES-CMAC-PRF-128 is password-based key derivation function defined in RFC2898 and RFC4615.

PBKDF2 with HMAC-SHA1 is password-based key derivation function defined in RFC2898.

Functions

void ocrypto_pbkdf2_aes_cmac_prf128(uint8_t *key, size_t key_len, const uint8_t *password, size_t password_len, const uint8_t *salt, size_t salt_len, uint32_t count)

Computes the PBKDF2-AES-CMAC-PRF-128 key from password, salt, and iteration count.

Parameters:

key – [out] PBKDF2 key to generate.
key_len – Length of key.
password – Password to use.
password_len – Length of password.
salt – Salt to use.
salt_len – Length of salt. 0 < salt_len <= 32.
count – Iteration count.

void ocrypto_pbkdf2_hmac_sha1(uint8_t *key, size_t key_len, const uint8_t *password, size_t password_len, const uint8_t *salt, size_t salt_len, uint32_t count)

Computes the PBKDF2-HMAC-SHA1 key from password, salt, and iteration count.

Parameters:

key – [out] PBKDF2 key to generate.
key_len – Length of key.
password – Password to use.
password_len – Length of password.
salt – Salt to use.
salt_len – Length of salt.
count – Iteration count.

void ocrypto_pbkdf2_hmac_sha256(uint8_t *key, size_t key_len, const uint8_t *password, size_t password_len, const uint8_t *salt, size_t salt_len, uint32_t count)

Computes the PBKDF2-HMAC-SHA256 key from password, salt, and iteration count.

Parameters:

key – [out] PBKDF2 key to generate.
key_len – Length of key.
password – Password to use.
password_len – Length of password.
salt – Salt to use.
salt_len – Length of salt.
count – Iteration count.

RSA - Rivest-Shamir-Adleman algorithm 

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

RSA

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 –

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

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 Hashing algorithms 

SHA-1

group ocrypto_sha_1

Type declarations and APIs for the SHA-1 algorithm.

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

SHA-1 is no longer considered secure against well-funded opponents; replacement by SHA-2 or SHA-3 is recommended.

Incremental SHA-1 generator.

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

void ocrypto_sha1_init(ocrypto_sha1_ctx *ctx)

SHA-1 initialization.

The generator state ctx is initialized by this function.

Parameters:

ctx – [out] Generator state.

void ocrypto_sha1_update(ocrypto_sha1_ctx *ctx, const uint8_t *in, size_t in_len)

SHA-1 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_sha1_init is required before this function can be called.

Parameters:

ctx – Generator state.
in – Input data.
in_len – Length of in.

void ocrypto_sha1_final(ocrypto_sha1_ctx *ctx, uint8_t r[(20)])

SHA-1 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_sha1_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_sha1_update and ocrypto_sha1_final unless it is reinitialized using ocrypto_sha1_init.

Parameters:

ctx – Generator state.
r – [out] Generated hash value.

Defines

ocrypto_sha1_BYTES: Length of SHA-1 hash.

Functions

void ocrypto_sha1(uint8_t r[(20)], const uint8_t *in, size_t in_len)

SHA-1 hash.

The SHA-1 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-224

group ocrypto_sha_224

Type declarations and APIs for the SHA-224 algorithm.

SHA-224 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-224 generator.

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

void ocrypto_sha224_init(ocrypto_sha224_ctx *ctx)

SHA-224 initialization.

The generator state ctx is initialized by this function.

Parameters:

ctx – [out] Generator state.

void ocrypto_sha224_update(ocrypto_sha224_ctx *ctx, const uint8_t *in, size_t in_len)

SHA-224 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_sha224_init is required before this function can be called.

Parameters:

ctx – Generator state.
in – Input data.
in_len – Length of in.

void ocrypto_sha224_final(ocrypto_sha224_ctx *ctx, uint8_t r[(28)])

SHA-224 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_sha224_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_sha224_update and ocrypto_sha224_final unless it is reinitialized using ocrypto_sha224_init.

Parameters:

ctx – Generator state.
r – [out] Generated hash value.

Defines

ocrypto_sha224_BYTES: Length of SHA-224 hash.

Functions

void ocrypto_sha224(uint8_t r[(28)], const uint8_t *in, size_t in_len)

SHA-224 hash.

The SHA-224 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-256

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-256

group ocrypto_sha_384

Type declarations and APIs for the SHA-384 algorithm.

SHA-384 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-384 generator.

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

void ocrypto_sha384_init(ocrypto_sha384_ctx *ctx)

SHA-384 initialization.

The generator state ctx is initialized by this function.

Parameters:

ctx – [out] Generator state.

void ocrypto_sha384_update(ocrypto_sha384_ctx *ctx, const uint8_t *in, size_t in_len)

SHA-384 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_sha384_init is required before this function can be called.

Parameters:

ctx – Generator state.
in – Input data.
in_len – Length of in.

void ocrypto_sha384_final(ocrypto_sha384_ctx *ctx, uint8_t r[(48)])

SHA-384 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_sha384_init is required before this function can be called.

Remark

After return, the generator state ctx must no longer be used with ocrypto_sha384_update and ocrypto_sha384_final unless it is reinitialized using ocrypto_sha384_init.

Parameters:

ctx – Generator state.
r – [out] Generated hash value.

Defines

ocrypto_sha384_BYTES: Length of SHA-384 hash.

Functions

void ocrypto_sha384(uint8_t r[(48)], const uint8_t *in, size_t in_len)

SHA-384 hash.

The SHA-384 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

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.

SPAKE2+

group ocrypto_spake2p

Type declarations and APIs for SPAKE2+ P256.

Functions

void ocrypto_spake2p_p256_reduce(uint8_t x[32], const uint8_t *xs, size_t xs_len)

SPAKE2+ P256 secret key reduction.

Parameters:

x – [out] Reduced secret key.
xs – Extended secret key.
xs_len – Extended secret key length.

int ocrypto_spake2p_p256_check_key(const uint8_t K[65])

SPAKE2+ P256 public key validation check.

Parameters:

K – Public key.

Return values:

0 – If the key is valid.
-1 – Otherwise.

int ocrypto_spake2p_p256_get_key_share(uint8_t XY[65], const uint8_t w0[32], const uint8_t xy[32], const uint8_t MN[65])

SPAKE2+ P256 key share calculation.

Parameters:

XY – [out] Public key share.
w0 – First password hash.
xy – Secret key.
MN – Random element.

Return values:

0 – If the key share is valid.
-1 – Otherwise.

void ocrypto_spake2p_p256_get_ZV(uint8_t Z[65], uint8_t V[65], const uint8_t w0[32], const uint8_t w1[32], const uint8_t xy[32], const uint8_t YX[65], const uint8_t NM[65], const uint8_t L[65])

SPAKE2+ P256 common value calculation.

Parameters:

Z – [out] Common value Z.
V – [out] Common value V.
w0 – First password hash.
w1 – Second password hash. NULL on server side.
xy – Secret key.
YX – Peer key share.
NM – Peer random element.
L – Password registration. NULL on client side.

SRP - Secure Remote Password 

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

The Stanford SRP Homepage

Setup

Server generates a username / password combination together with a salt.
Server derives a password verifier (see ocrypto_srp_verifier).
The username, salt and verifier are stored and required to open sessions. The original password is no longer needed.

Session opening

Client sends a username and the public key of an ephemeral key pair to the server.
Server sends the salt and the public key of another ephemeral key pair to the client (see ocrypto_srp_public_key).
Client and Server both compute the session key from this information (see ocrypto_srp_scrambling_parameter, ocrypto_srp_premaster_secret, ocrypto_srp_session_key).
Client sends proof of the session key to the server.
Server validates proof (see ocrypto_srp_proof_m1), then sends proof of the session key to the client (see ocrypto_srp_proof_m2).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 

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.

ocrypto internal types 

group ocrypto_types

Declarations of internal types used in public interfaces. Their fields and sizes are subject to change.

struct ocrypto_mod25519: #include <ocrypto_types.h>

struct ocrypto_sc25519: #include <ocrypto_types.h>

struct ocrypto_ge25519: #include <ocrypto_types.h>

struct ocrypto_ge25519_ext: #include <ocrypto_types.h>

struct ocrypto_ge25519_comp: #include <ocrypto_types.h>

struct ocrypto_ge25519_ctx: #include <ocrypto_types.h>

struct ocrypto_ed25519_ctx: #include <ocrypto_types.h>

struct ocrypto_curve25519_ctx: #include <ocrypto_types.h>

struct ocrypto_mod_p256: #include <ocrypto_types.h>

struct ocrypto_sc_p256: #include <ocrypto_types.h>

struct ocrypto_p256_inv_ctx: #include <ocrypto_types.h>

struct ocrypto_cp_p256: #include <ocrypto_types.h>

struct ocrypto_p256_mult_ctx: #include <ocrypto_types.h>

struct ocrypto_srp_mg: #include <ocrypto_types.h>

struct ocrypto_srp_math_ctx: #include <ocrypto_types.h>

struct ocrypto_srp_ctx: #include <ocrypto_types.h>