API documentation¶
nRF CC310 bootloader crypto library¶
-
group
nrf_cc310_bl
Common declarations for nrf_cc310_bl ECDSA verify APIs.
Function for initializing the CC310 hardware and runtime library.
Type definitions and public APIs for nrf_cc310_bl HASH using SHA-256.
Shared declarations used by nrf_cc310_bl for hash APIs.
Type definitions and APIs for nrf_cc310_bl ECDSA verify using curve secp256r1.
- Note
Running this initialization is intended for cases where there is no direct requirement for the RNG subsystem (all operations are deterministic).
- Return Value
CRYS_OK
: Initialization was successful.
Defines
-
NRF_CC310_BL_ECDSA_CONTEXT_INITIALIZED
¶
-
NRF_CC310_BL_ECDSA_VERIFY_CONTEXT_SIZE_SECP224R1
¶ Macro for the size of the ECDSA Verify context.
-
NRF_CC310_BL_ECDSA_VERIFY_CONTEXT_SIZE_SECP256R1
¶ Macro for the size of the ECDSA Verify context.
-
NRF_CC310_BL_HASH_CONTEXT_INITIALIZED
¶ Value indicating that the hash context is initialized.
-
NRF_CC310_BL_HASH_CONTEXT_BUFFER_SIZE_SHA256
¶ Size of internal representation of SHA-256 hash context.
-
NRF_CC310_BL_SHA256_DIGEST_SIZE_IN_WORDS
¶ Size of SHA-256 hash digest in words.
-
NRF_CC310_BL_SHA256_DIGEST_SIZE_IN_BYTES
¶ Size of SHA-256 hash digest in bytes.
Typedefs
-
typedef uint8_t
nrf_cc310_bl_hash_digest_sha256_t
[(32)]¶ Array to hold SHA-256 hash digest.
Functions
-
CRYSError_t
nrf_cc310_bl_ecdsa_verify_init_secp256r1
(nrf_cc310_bl_ecdsa_verify_context_secp256r1_t *const p_context, nrf_cc310_bl_ecc_public_key_secp256r1_t const *const p_public_key)¶ Function for initializing the context information for an ECDSA verify operation.
- Note
The memory that holds the context object must be allocated prior to this call.
- Parameters
[inout] p_context
: Pointer to the structure holding context information for the ECDSA verify operation.[in] p_public_key
: Pointer to the structure holding the public key for the ECDSA verify operation.
- Return Value
CRYS_ECDSA_VERIFY_INVALID_USER_CONTEXT_PTR_ERROR
: p_context was NULL.CRYS_ECDSA_VERIFY_SIGNER_PUBL_KEY_VALIDATION_TAG_ERROR
: p_public_key was NULL.
-
CRYSError_t
nrf_cc310_bl_ecdsa_verify_hash_secp256r1
(nrf_cc310_bl_ecdsa_verify_context_secp256r1_t *const p_context, nrf_cc310_bl_ecc_signature_secp256r1_t const *const p_signature, uint8_t const *const p_hash, uint32_t hash_len)¶ Function for executing an ECDSA verify operation using secp256r1 with hash input.
- Note
The ECDSA verify context structure must be initialized prior to this call using nrf_cc310_bl_ecdsa_verify_init_secp256r1.
- Parameters
[inout] p_context
: Pointer to the structure holding context information for the ECDSA verify operation.[in] p_signature
: Pointer to the structure holding the signature to use for the ECDSA verify operation.[in] p_hash
: Pointer to the hash to use in the ECDSA verify operation.[in] hash_len
: Length of the hash to verify.
- Return Value
CRYS_OK
: Signature was successfully verified.CRYS_ECDSA_VERIFY_INVALID_USER_CONTEXT_PTR_ERROR
: p_context was NULL.CRYS_ECDSA_VERIFY_USER_CONTEXT_VALIDATION_TAG_ERROR
: p_context was not initialized.CRYS_ECDSA_VERIFY_INVALID_SIGNATURE_IN_PTR_ERROR
: p_signature was NULL.CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_PTR_ERROR
: p_hash was NULL.CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_SIZE_ERROR
: hash_len was invalid.CRYS_ECDSA_VERIFY_INCONSISTENT_VERIFY_ERROR
: Signature verification failed.
-
CRYSError_t
nrf_cc310_bl_ecdsa_verify_secp256r1
(nrf_cc310_bl_ecdsa_verify_context_secp256r1_t *const p_context, nrf_cc310_bl_ecc_public_key_secp256r1_t const *const p_public_key, nrf_cc310_bl_ecc_signature_secp256r1_t const *const p_signature, uint8_t const *const p_hash, uint32_t hash_len)¶ Function for executing an ECDSA verify operation using secp256r1 with hash input in integrated form.
- Note
This will run initialization of ECDSA context and run ECDSA verify in a single step.
- Parameters
[inout] p_context
: Pointer to the structure holding context information for the ECDSA verify operation.[in] p_public_key
: Pointer to the structure holding the public key for the ECDSA verify operation.[in] p_signature
: Pointer to the structure holding the signature to use for the ECDSA verify operation.[in] p_hash
: Pointer to the hash to use in the ECDSA verify operation.[in] hash_len
: Length of the hash to verify.
- Return Value
CRYS_OK
: Signature was successfully verified.CRYS_ECDSA_VERIFY_INVALID_USER_CONTEXT_PTR_ERROR
: p_context was NULL.CRYS_ECDSA_VERIFY_USER_CONTEXT_VALIDATION_TAG_ERROR
: p_context was not initialized.CRYS_ECDSA_VERIFY_SIGNER_PUBL_KEY_VALIDATION_TAG_ERROR
: p_public_key was NULL.CRYS_ECDSA_VERIFY_INVALID_SIGNATURE_IN_PTR_ERROR
: p_signature was NULL.CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_PTR_ERROR
: p_hash was NULL.CRYS_ECDSA_VERIFY_INVALID_MESSAGE_DATA_IN_SIZE_ERROR
: hash_len was invalid.CRYS_ECDSA_VERIFY_INCONSISTENT_VERIFY_ERROR
: Signature verification failed.
-
CRYSError_t
nrf_cc310_bl_hash_sha256_init
(nrf_cc310_bl_hash_context_sha256_t *const p_hash_context)¶ Function for initializing the SHA-256 context.
- Note
Memory pointed to in hash context must be allocated prior to this call.
- Parameters
[inout] p_hash_context
: Structure holding context information for the SHA-256 operation.
- Return Value
CRYS_OK
: If call was successful.CRYS_HASH_INVALID_USER_CONTEXT_POINTER_ERROR
: p_hash_context was NULL.
-
CRYSError_t
nrf_cc310_bl_hash_sha256_update
(nrf_cc310_bl_hash_context_sha256_t *const p_hash_context, uint8_t const *p_src, uint32_t len)¶ Function for running an update to the SHA-256 hash calculation.
- Parameters
[inout] p_hash_context
: Structure holding context information for the SHA-256 operation.[in] p_src
: Input data to be added to the digest.[in] len
: Amount of data passed in p_src.
- Return Value
CRYS_OK
: If call was successful.CRYS_HASH_INVALID_USER_CONTEXT_POINTER_ERROR
: p_hash_context was NULL.CRYS_HASH_USER_CONTEXT_CORRUPTED_ERROR
: p_hash_context not initialized.CRYS_HASH_LAST_BLOCK_ALREADY_PROCESSED_ERROR
: p_hash_context already finalized.
-
CRYSError_t
nrf_cc310_bl_hash_sha256_finalize
(nrf_cc310_bl_hash_context_sha256_t *const p_hash_context, nrf_cc310_bl_hash_digest_sha256_t *const p_digest)¶ Function for finalizing the hash calculation.
- Note
Memory pointed to in hash digest must be allocated prior to this call.
- Parameters
[inout] p_hash_context
: Structure holding context information for the SHA-256 operation.[inout] p_digest
: Pointer to the structure holding SHA-256 hash digest. Data pointed to must be 32 bytes long.
- Return Value
CRYS_HASH_INVALID_USER_CONTEXT_POINTER_ERROR
: p_hash_context was NULL.CRYS_HASH_USER_CONTEXT_CORRUPTED_ERROR
: p_hash_context was corrupted.CRYS_HASH_INVALID_RESULT_BUFFER_POINTER_ERROR
: p_digest was NULL.
-
CRYSError_t
nrf_cc310_bl_init
(void)¶
-
struct
nrf_cc310_bl_ecc_public_key_secp256r1_t
¶ - #include <nrf_cc310_bl_ecdsa_verify_secp256r1.h>
Structure holding the secp256r1 public key represented by X,Y coordinates.
-
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.
-
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 setus 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_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_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
¶
-
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.
- Return
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.
- Return
Zero on success, otherwise a non-zero error code.
-
int
nrf_cc3xx_platform_deinit
(void)¶ Function to deintialize the nrf_cc3xx_platform.
- Return
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 Value
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 Value
True
: if RNG is initialized, otherwise false.
-
void
CRYPTOCELL_IRQHandler
(void)¶ ISR Function for processing of cc3xx Interrupts. This cc3xx interrupt service routine function should be called for interrupt processing. Either by placing this functions directly in the vector table or by calling it from the ISR in the OS.
-
int
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.
- Return
Any other error code returned from mbedtls_hardware_poll
- Parameters
[out] buffer
: Pointer to buffer to hold the entropy data.[in] length
: Length of the buffer to fill with entropy data.[out] olen
: Pointer to variable that will hold the length of generated entropy.
- Return Value
0
: on success
-
int
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.
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.
- Parameters
[in] mutex
: 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.
- Parameters
[in] mutex
: 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.
- Parameters
[in] mutex
: 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.
- Parameters
[in] mutex
: 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
[in] apis
: Structure holding the mutex APIs.[in] mutexes
: 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
[in] apis
: 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.
-
nrf_cc3xx_platform_abort_handle_t
-
typedef void *
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.
CC3XX Platform - CTR_DRBG APIs¶
-
group
nrf_cc3xx_platform_ctr_drbg
The nrf_cc3xx_platform_ctr_drbg APIs provide PRNG seeded by TRNG in accordance with NIST SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators The generation of TRNG/PRNG data is using Arm CryptoCell cc3xx hardware acceleration.
The pre-built APIs are based on mbedtls_entropy and mbedtls_ctr_drbg but doesn’t require setting up memory allocation before use.
Defines
-
NRF_CC3XX_PLATFORM_ENTROPY_SIZE_WORDS
¶ Macro holding size of the opaque ctr_drbg context type.
This corresponds to a structure with the combined size of mbedtls_entropy_context and mbedtls_ctr_drbg_context in Arm CryptoCell code base which is sized differently than in vanilla mbed TLS software.
Functions
-
int
nrf_cc3xx_platform_ctr_drbg_init
(nrf_cc3xx_platform_ctr_drbg_context_t *const context, const uint8_t *pers_string, size_t pers_string_len)¶ Function that initializes an ctr_drbg context.
- Return
0 on success, otherwise a non-zero failure from mbedtls_ctrl_drbg_seed.
- Parameters
[inout] context
: Pointer to structure holding the ctr_drbg context which must be used for subsequent calls to generate random data.[in] pers_string
: Personalization string used for the CTR_DRBG_Instantiate_algorithm.[in] pers_string_len
: Length of the personalization string, which may be zero.
- Return Value
NRF_CC3XX_PLATFORM_ERROR_PARAM_NULL
: Context was NULL.
-
int
nrf_cc3xx_platform_ctr_drbg_free
(nrf_cc3xx_platform_ctr_drbg_context_t *const context)¶ Function that deintializes an 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
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.
- Return
0 on success, otherwise a non-zero failure.
- Parameters
[inout] context
: Pointer to a structure holding the ctr_drbg context.[in] pr_enabled
: Enables prediction resistance if true, otherwise false (default).
- Return Value
NRF_CC3XX_PLATFORM_ERROR_PARAM_NULL
: Context was NULL.
-
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
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.
- Return
0 on success, otherwise a non-zero failure according to the API mbedtls_ctrl_drbg_reseed.
- Parameters
[inout] context
: Pointer to a structure holding the ctr_drbg context.[in] interval
: New reeseed interval value.
- Return Value
NRF_CC3XX_PLATFORM_ERROR_PARAM_NULL
: Context was NULL.
-
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
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.
- Return
0 on success, otherwise a non-zero failure according to the API mbedtls_ctrl_drbg_seed.
- Parameters
[inout] context
: Pointer to a structure holding the ctr_drbg context.[in] additional
: Optional additional input to use for CTR_DRBG_Reseed_function.[in] add_len
: Length of the additional input, may be zero.
- Return Value
NRF_CC3XX_PLATFORM_ERROR_PARAM_NULL
: Context was NULL.
-
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 accelarated 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
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.
- Return
0 on success, otherwise a non-zero failure according to the API mbedtls_ctrl_drbg_get_with_add.
- Parameters
[inout] context
: Pointer to structure holding the ctr_drbg context.[in] buffer
: Pointer to buffer to hold PRNG data.[in] len
: Length of PRNG to get.[out] olen
: Length reported out.[in] additional
: Additional input to use with CTR_DRBG_Generate_algorithm.[in] add_len
: Length of CTR_DRBG additional input.
- Return Value
NRF_CC3XX_PLATFORM_ERROR_PARAM_NULL
: Context was NULL.
-
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
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.
- Return
0 on success, otherwise a non-zero failure according to the API mbedtls_ctr_drbg_random.
- Parameters
[inout] context
: Pointer to structure holding the ctr_drbg context.[in] buffer
: Pointer to buffer to hold PRNG data.[in] length
: Length of PRNG to get.[out] olen
: Length reported out.
-
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).
-
nrf_oberon crypto library¶
-
group
nrf_oberon
Highly optimized cryptographic algorithm implementation for Cortex-M0, Cortex-M4, and Cortex-M33. Created by Oberon, under distribution license with Nordic Semiconductor ASA.
AES - Advanced Encryption Standard APIs¶
-
group
nrf_oberon_aes
AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.
AES-CTR - AES Counter Mode¶
-
group
nrf_oberon_aes_ctr
Type definitions and APIs for AES-CTR (AES Counter mode).
AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.
AES-CTR (AES counter mode) is an AES mode which effectively turns the block cipher into a stream cipher. The AES block encryption is used on a value which is incremented for each new block. The resulting cypher stream is then xor combined with the plaintext to get the ciphertext. In contrast to AES itself, encryption and decryption operations are identical for AES-CTR.
Incremental AES-CTR encryption/decryption.
This group of functions can be used to incrementally compute the AES-CTR encryption/decryption for a given message.
-
void
ocrypto_aes_ctr_init
(ocrypto_aes_ctr_ctx *ctx, const uint8_t *key, size_t size, const uint8_t iv[16])¶ AES-CTR initialization.
The context
ctx
is initialized using the given keykey
and initial vectoriv
.- Parameters
[out] ctx
: Context.key
: AES key.size
: Key size (16, 24, or 32 bytes).iv
: Initial vector.
-
void
ocrypto_aes_ctr_encrypt
(ocrypto_aes_ctr_ctx *ctx, uint8_t *ct, const uint8_t *pt, size_t pt_len)¶ AES-CTR incremental encryption.
The plaintext
pt
is encrypted to the ciphertextct
using the contextctx
.This function can be called repeatedly until the whole message is processed.
- Remark
ct
andpt
can point to the same address.- Remark
Initialization of the context
ctx
throughocrypto_aes_ctr_init
is required before this function can be called.- Parameters
ctx
: Context.[out] ct
: Ciphertext.pt
: Plaintext.pt_len
: Length ofpt
andct
.
-
void
ocrypto_aes_ctr_decrypt
(ocrypto_aes_ctr_ctx *ctx, uint8_t *pt, const uint8_t *ct, size_t ct_len)¶ AES-CTR incremental decryption.
The ciphertext
ct
is decrypted to the plaintextpt
using the contextctx
.This function can be called repeatedly until the whole message is processed.
- Remark
ct
andpt
can point to the same address.- Remark
Initialization of the context
ctx
throughocrypto_aes_ctr_init
is required before this function can be called.- Parameters
ctx
: Context.[out] pt
: Plaintext.ct
: Ciphertext.ct_len
: Length ofct
andpt
.
-
void
AES EAX APIs¶
-
group
nrf_oberon_aes_eax
Type definitions and APIS for AES EAX (Encrypt-then-authenticate-then-translate)
AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.
AES-EAX (encrypt-then-authenticate-then-translate) is an AES mode which effectively turns the block cipher into a stream cipher. The AES block cipher primitive is used in CTR mode for encryption and as OMAC for authentication over each block.
Functions
-
void
ocrypto_aes_eax_encrypt
(uint8_t *ct, uint8_t tag[16], const uint8_t *pt, size_t pt_len, const uint8_t *key, size_t size, const uint8_t *iv, size_t iv_len, const uint8_t *aa, size_t aa_len)¶ AES-EAX encryption.
- Remark
ct
andpt
can point to the same address.- Parameters
[out] ct
: Cyphertext.[out] tag
: Authentication tag.pt
: Plaintext.pt_len
: Plaintext length.key
: AES key.size
: Key size (16, 24, or 32 bytes).iv
: Initial vector.iv_len
: Initial vector length.aa
: Additional authentication data.aa_len
: Additional authentication data length.
-
int
ocrypto_aes_eax_decrypt
(uint8_t *pt, const uint8_t tag[16], const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size, const uint8_t *iv, size_t iv_len, const uint8_t *aa, size_t aa_len)¶ AES-EAX decryption.
- Remark
ct
andpt
can point to the same address.- Parameters
[out] pt
: Plaintext.tag
: Authentication tag.ct
: Cyphertext.ct_len
: Cyphertext length.key
: AES key.size
: Key size (16, 24, or 32 bytes).iv
: Initial vector.iv_len
: Initial vector length.aa
: Additional authentication data.aa_len
: Additional authentication data length.
- Return Value
0
: Iftag
is valid.-1
: Otherwise.
-
void
AES GCM - AES Galois/Counter Mode APIs¶
-
group
nrf_oberon_aes_gcm
Type definitions and APIs for AES-GCM (AES Galois/Counter Mode).
AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.
AES-GCM (AES Galois/Counter Mode) is an AES mode which effectively turns the block cipher into a stream cipher. The AES block cipher primitive is used in CTR mode for encryption and decryption. In addition, 128-bit Galois Field multiplication is used for authentication.
Functions
-
void
ocrypto_aes_gcm_encrypt
(uint8_t *ct, uint8_t tag[16], const uint8_t *pt, size_t pt_len, const uint8_t *key, size_t size, const uint8_t iv[12], const uint8_t *aa, size_t aa_len)¶ AES-GCM encryption.
- Remark
ct
andpt
can point to the same address.- Parameters
[out] ct
: Cyphertext.[out] tag
: Authentication tag.pt
: Plaintext.pt_len
: Plaintext length.key
: AES key.size
: Key size (16, 24, or 32 bytes).iv
: Initial vector.aa
: Additional authentication data.aa_len
: Additional authentication data length.
-
int
ocrypto_aes_gcm_decrypt
(uint8_t *pt, const uint8_t tag[16], const uint8_t *ct, size_t ct_len, const uint8_t *key, size_t size, const uint8_t iv[12], const uint8_t *aa, size_t aa_len)¶ AES-GCM decryption.
- Remark
ct
andpt
can point to the same address.- Parameters
[out] pt
: Plaintext.tag
: Authentication tag.ct
: Cyphertext.ct_len
: Cyphertext length.key
: AES key.size
: Key size (16, 24, or 32 bytes).iv
: Initial vector.aa
: Additional authentication data.aa_len
: Additional authentication data length.
- Return Value
0
: Iftag
is valid.-1
: Otherwise.
-
void
AES key sizes¶
-
group
nrf_oberon_aes_key
Type definition of AES key sizes.
AES (advanced encryption standard) is a symmetric encryption algorithm standardized by NIST. AES transfers a 128-bit block of data into an encrypted block of the same size.
ChaCha20-Poly1305¶
-
group
nrf_oberon_chacha_poly
ChaCha20-Poly1305 is an authenticated encryption algorithm with optional additional authenticated data developed by Daniel J.Bernstein.
ChaCha20-Poly1305 APIs¶
-
group
nrf_oberon_chacha_poly_apis
Type declaration and APIs for authenticated encryption and additional data using the ChaCha20-Poly1305 algorithm.
ChaCha20-Poly1305 is an authenticated encryption algorithm with optional additional authenticated data developed by Daniel J.Bernstein.
The ChaCha20 stream cipher is combined with the Poly1305 authenticator.
Unnamed Group
-
int
ocrypto_chacha20_poly1305_decrypt
(const uint8_t tag[(16)], uint8_t *m, const uint8_t *c, size_t c_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ AEAD ChaCha20-Poly1305 decrypt.
If the authentication tag
tag
is valid for the ciphertextc
, the encryption keyk
and the noncen
, the ciphertext is decrypted and put intom
. The decrypted messagem
has the same lengthc_len
as the original ciphertext.- Remark
m
andc
can point to the same address.- Parameters
tag
: Received authentication tag.[out] m
: Decoded message. Same length as received ciphertext.c
: Received ciphertext.c_len
: Length ofc
andm
.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
- Return Value
0
: Iftag
is valid.-1
: Otherwise.
-
int
ocrypto_chacha20_poly1305_decrypt_aad
(const uint8_t tag[(16)], uint8_t *m, const uint8_t *c, size_t c_len, const uint8_t *a, size_t a_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ AEAD ChaCha20-Poly1305 decrypt with AAD.
If the authentication tag
tag
is valid for the ciphertextc
, the additional authenticated dataa
, the encryption keyk
and the noncen
, the ciphertext is decrypted and put intom
. The decrypted messagem
has the same lengthc_len
as the original ciphertext.- Remark
m
andc
can point to the same address.- Parameters
tag
: Received authentication tag.[out] m
: Decoded message. Same length as received ciphertext.c
: Received ciphertext.c_len
: Length ofc
andm
.a
: Received additional authenticated data.a_len
: Length ofa
.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
- Return Value
0
: Iftag
is valid.-1
: Otherwise.
Defines
-
ocrypto_chacha20_poly1305_KEY_BYTES
¶ Length of the encryption key.
-
ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
¶ Maximum length of the nonce.
-
ocrypto_chacha20_poly1305_TAG_BYTES
¶ Length of the authentication tag.
Functions
-
void
ocrypto_chacha20_poly1305_encrypt
(uint8_t tag[(16)], uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ AEAD ChaCha20-Poly1305 encrypt.
The message
m
is encrypted using a ChaCha20 cipher stream derived from the encryption keyk
and the noncen
. The resulting ciphertext has the same lengthm_len
as the input messagem
and is put intoc
.Additionally, the ciphertext
c
is authenticated with a tag that is generated with Poly1305 using a unique subkey derived fromk
andn
, and then put intotag
.- Remark
c
andm
can point to the same address.- Remark
When reusing an encryption key
k
for a different messagem
, a different noncen
must be used.- Parameters
[out] tag
: Generated authentication tag.[out] c
: Generated ciphertext. Same length as input message.m
: Input message.m_len
: Length ofm
andc
.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
-
void
ocrypto_chacha20_poly1305_encrypt_aad
(uint8_t tag[(16)], uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *a, size_t a_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ AEAD ChaCha20-Poly1305 encrypt with AAD.
The message
m
is encrypted using a ChaCha20 cipher stream derived from the encryption keyk
and the noncen
. The resulting ciphertext has the same lengthm_len
as the input messagem
and is put intoc
.Additionally, the ciphertext
c
, as well as the additional authenticated dataa
, is authenticated with a tag that is generated with Poly1305 using a unique subkey derived fromk
andn
, and then put intotag
.- Remark
c
andm
can point to the same address.- Remark
When reusing an encryption key
k
for a different messagem
or different additional authenticated dataa
, a different noncen
must be used.- Parameters
[out] tag
: Generated authentication tag.[out] c
: Generated ciphertext. Same length as input message.m
: Input message.m_len
: Length ofm
andc
.a
: Additional authenticated data.a_len
: Length ofa
.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
-
int
ChaCha20 APIs¶
-
group
nrf_oberon_chacha
Type declaration and APIs for the Chacha20 stream cipher algorithm.
ChaCha20 is a stream cipher developed by Daniel J. Bernstein based on the 20-round cipher Salsa20/20.
A 256-bit key is expanded into 2^64 randomly accessible streams, each containing 2^64 randomly accessible 64-byte (512-bit) blocks.
The changes from Salsa20/20 to ChaCha20 are designed to improve diffusion per round, conjecturally increasing resistance to cryptanalysis, while preserving - and often improving - time per round.
Defines
-
ocrypto_chacha20_KEY_BYTES
¶ Length of the encryption key.
-
ocrypto_chacha20_NONCE_BYTES_MAX
¶ Maximum length of the nonce.
Functions
-
void
ocrypto_chacha20_stream
(uint8_t *c, size_t c_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)], uint32_t count)¶ ChaCha20 cipher stream generator.
The encryption key
k
, the noncen
, and the initial block countercount
are used to generate a pseudo random cipher stream.Possible applications include key generation and random number generation.
- Remark
When reusing an encryption key
k
, a different noncen
or initial block countercount
must be used.- Remark
This function is equivalent to
chacha20_stream_xor
with a messagem
consisting ofc_len
zeroes.- Parameters
[out] c
: Generated cipher stream.c_len
: Length ofc
.n
: Nonce.n_len
: Nonce length. 0 <=n_len
<=ocrypto_chacha20_NONCE_BYTES_MAX
.k
: Encryption key.count
: Initial block counter.
-
void
ocrypto_chacha20_stream_xor
(uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)], uint32_t count)¶ ChaCha20 cipher stream encoder.
The message
m
is encrypted by applying the XOR operation with a pseudo random cipher stream derived from the encryption keyk
, the noncen
, and the initial block countercount
.Calling the function a second time with the generated ciphertext as input message
m
decrypts it back to the original message.- Remark
c
andm
can point to the same address.- Remark
When reusing an encryption key
k
for a different messagem
, a different noncen
or initial block countercount
must be used.- Parameters
[out] c
: Generated ciphertext. Same length as input message.m
: Input message.m_len
: Length ofc
andm
.n
: Nonce.n_len
: Nonce length. 0 <=n_len
<=ocrypto_chacha20_NONCE_BYTES_MAX
.k
: Encryption key.count
: Initial block counter.
-
ChaCha20-Poly1305 incremental APIs¶
-
group
nrf_oberon_chacha_poly_inc
Type declaration and APIs for authenticated encryption and additional data using the ChaCha20-Poly1305 algorithm in incremental steps.
ChaCha20-Poly1305 is an authenticated encryption algorithm with optional additional authenticated data developed by Daniel J.Bernstein.
The ChaCha20 stream cipher is combined with the Poly1305 authenticator.
Incremental ChaCha20-Poly1305 generator.
This group of functions can be used to incrementally encode and decode using the ChaCha20-Poly1305 stream cypher.
Use pattern:
Encoding:
Decoding:ocrypto_chacha20_poly1305_init(ctx, nonce, nonce_len, key); ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key); ... ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key); ocrypto_chacha20_poly1305_update_enc(ctx, ct, pt, pt_len, nonce, nonce_len, key); ... ocrypto_chacha20_poly1305_update_enc(ctx, ct, pt, pt_len, nonce, nonce_len, key); ocrypto_chacha20_poly1305_final_enc(ctx, tag);
ocrypto_chacha20_poly1305_init(ctx, nonce, nonce_len, key); ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key); ... ocrypto_chacha20_poly1305_update_aad(ctx, aad, aad_len, nonce, nonce_len, key); ocrypto_chacha20_poly1305_update_dec(ctx, pt, ct, ct_len, nonce, nonce_len, key); ... ocrypto_chacha20_poly1305_update_dec(ctx, pt, ct, ct_len, nonce, nonce_len, key); res = ocrypto_chacha20_poly1305_final_dec(ctx, tag);
-
void
ocrypto_chacha20_poly1305_init
(ocrypto_chacha20_poly1305_ctx *ctx, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ ChaCha20-Poly1305 initialization.
The generator state
ctx
is initialized by this function.- Parameters
[out] ctx
: Generator state.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
-
void
ocrypto_chacha20_poly1305_update_aad
(ocrypto_chacha20_poly1305_ctx *ctx, const uint8_t *a, size_t a_len)¶ SHA-ChaCha20-Poly1305 incremental aad input.
The generator state
ctx
is updated to include a data chunka
.This function can be called repeatedly until the whole data is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_chacha20_poly1305_init
is required before this function can be called.- Remark
ocrypto_chacha20_poly1305_update_aad
must be called before any call toocrypto_chacha20_poly1305_update_enc
orocrypto_chacha20_poly1305_update_dec
.- Parameters
ctx
: Generator state.a
: Additional authenticated data.a_len
: Length ofa
.
-
void
ocrypto_chacha20_poly1305_update_enc
(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t *c, const uint8_t *m, size_t m_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ SHA-ChaCha20-Poly1305 incremental encoder input.
The generator state
ctx
is updated to include a message chunkm
.This function can be called repeatedly until the whole message is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_chacha20_poly1305_init
is required before this function can be called.- Remark
ocrypto_chacha20_poly1305_update_enc
must be called after any call toocrypto_chacha20_poly1305_update_aad
.- Remark
c
andm
can point to the same address.- Parameters
ctx
: Generator state.[out] c
: Generated ciphertext. Same length as input message.m
: Message chunk.m_len
: Length ofm
.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
-
void
ocrypto_chacha20_poly1305_update_dec
(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t *m, const uint8_t *c, size_t c_len, const uint8_t *n, size_t n_len, const uint8_t k[(32)])¶ SHA-ChaCha20-Poly1305 incremental decoder input.
The generator state
ctx
is updated to include a cyphertext chunkc
.This function can be called repeatedly until the whole cyphertext is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_chacha20_poly1305_init
is required before this function can be called.- Remark
ocrypto_chacha20_poly1305_update_dec
must be called after any call toocrypto_chacha20_poly1305_update_aad
.- Remark
m
andc
can point to the same address.- Parameters
ctx
: Generator state.[out] m
: Decoded message. Same length as received ciphertext.c
: Cyphertext chunk.c_len
: Length ofc
.n
: Nonce.n_len
: Length ofn
. 0 <=n_len
<=ocrypto_chacha20_poly1305_NONCE_BYTES_MAX
.k
: Encryption key.
-
void
ocrypto_chacha20_poly1305_final_enc
(ocrypto_chacha20_poly1305_ctx *ctx, uint8_t tag[(16)])¶ SHA-ChaCha20-Poly1305 final encoder step.
The generator state
ctx
is used to finalize the encryption and generate the tag.- Parameters
ctx
: Generator state.[out] tag
: Generated authentication tag.
-
int
ocrypto_chacha20_poly1305_final_dec
(ocrypto_chacha20_poly1305_ctx *ctx, const uint8_t tag[(16)])¶ SHA-ChaCha20-Poly1305 final decoder step.
The generator state
ctx
is used to finalize the decryption and check the tag.- Parameters
ctx
: Generator state.tag
: Received authentication tag.
- Return Value
0
: Iftag
is valid.-1
: Otherwise.
-
void
Constant time APIs¶
-
group
nrf_oberon_constant_time
Timing-invariant functions to use with cryptography.
Collection of timing-invariant implementations of basic functions.
Functions
-
int
ocrypto_constant_time_equal
(const void *x, const void *y, size_t length)¶ Variable length comparison.
- Parameters
x
: Memory region to compare withy
.y
: Memory region to compare withx
.length
: Number of bytes to compare,length
> 0.
- Return Value
1
: Ifx
andy
point to equal memory regions.0
: Otherwise.
-
int
ocrypto_constant_time_is_zero
(const void *x, size_t length)¶ Variable length compare to zero.
- Parameters
x
: Pointer to memory region that will be compared.length
: Number of bytes to compare,length
> 0.
- Return Value
1
: Ifx
is equal to a zero memory region.0
: Otherwise.
-
void
ocrypto_constant_time_copy
(void *x, const void *y, size_t length)¶ Variable length copy.
- Parameters
x
: Pointer to memory region to copyy
to.y
: Pointer to memory region to copy tox
.length
: Number of bytes to copy,length
> 0.
-
void
ocrypto_constant_time_fill_zero
(void *x, size_t length)¶ Variable length fill with zero.
- Parameters
x
: Pointer to memory region to be filled with zero.length
: Number of bytes to fill,length
> 0.
-
int
ECC secp256r1 low-level APIs¶
-
group
nrf_oberon_p256
Type declarations and APIs for low-level elliptic curve point operations based on the NIST secp256r1 curve.
Functions
-
int
ocrypto_curve_p256_from32bytes
(ocrypto_cp_p256 *r, const uint8_t p[32])¶ Load r.x from bytes, keep r.y.
- Parameters
[out] r
: Point with r.x loaded, r.y kept.p
: x as as array of bytes.
- Return Value
0
: Ifr
is a valid curve point.-1
: Otherwise.
-
int
ocrypto_curve_p256_from64bytes
(ocrypto_cp_p256 *r, const uint8_t p[64])¶ Load point from bytes.
- Parameters
[out] r
: Loaded point.p
: Point as array of bytes.
- Return Value
0
: Ifr
is a valid curve point.-1
: Otherwise.
-
void
ocrypto_curve_p256_to32bytes
(uint8_t r[32], ocrypto_cp_p256 *p)¶ Store p.x to bytes.
- Parameters
[out] r
: x stored as array.p
: Point with x to be stored.
-
void
ocrypto_curve_p256_to64bytes
(uint8_t r[64], ocrypto_cp_p256 *p)¶ Store p.x to bytes.
- Parameters
[out] r
: Point stored as array.p
: Point to be stored.
-
int
ocrypto_curve_p256_scalarmult
(ocrypto_cp_p256 *r, const ocrypto_cp_p256 *p, const ocrypto_sc_p256 *s)¶ P256 scalar multiplication.
r = p * s r = [0,0] if p = [0,0] or s mod q = 0
- Parameters
[out] r
: Output point.p
: Input point.s
: Scalar.
- Return Value
-1
: If r = [0,0].0
: If 0 < s < q.1
: If s > q.
-
int
ocrypto_curve_p256_scalarmult_base
(ocrypto_cp_p256 *r, const ocrypto_sc_p256 *s)¶ P256 scalar base multiplication.
r = basePoint * s r = [0,0] if s mod q = 0
- Parameters
[out] r
: Output point.s
: Scalar.
- Return Value
-1
: If r = [0,0].0
: If 0 < s < q.1
: If s > q.
-
int
ECC Curve25519 low-level APIs¶
-
group
nrf_oberon_curve25519
Type declarations and APIs for low-level elliptic curve point operations based on Curve25519.
Curve25519 is an elliptic curve offering 128 bits of security. It is designed for use in the Elliptic Curve Diffie-Hellman (ECDH) key agreement scheme.
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 intor
.The inverse of this function is difficult to compute.
- Remark
r
andn
can point to the same address.- Parameters
[out] r
: Resulting curve point.[in] n
: Scalar factor.
-
void
ocrypto_curve25519_scalarmult
(uint8_t r[(32)], const uint8_t n[(32)], const uint8_t p[(32)])¶ Curve25519 scalar multiplication
r = n * p
.A shared secret is computed from the local secret key
n
and another party’s public keyp
and put intor
. The same shared secret is generated when the other party combines its private key with the local public key.- Remark
r
andn
can point to the same address.- Parameters
[out] r
: Resulting curve point.[in] n
: Scalar factor.[in] p
: Point factor.
-
ECDH APIs¶
-
group
nrf_oberon_ecdh
APIs to do Elliptic Curve Diffie-Hellman using the NIST secp256r1 curve.
Functions
-
int
ocrypto_ecdh_p256_public_key
(uint8_t r[64], const uint8_t s[32])¶ ECDH P-256 public key generation
r = n * p
.Given a secret key
s
the corresponding public key is computed and put intor
.- Remark
r
may be same ass
.- Parameters
[out] r
: Generated public key.s
: Secret key. Must be pre-filled with random data.
- Return Value
0
: Ifs
is a valid secret key.-1
: Otherwise.
-
int
ocrypto_ecdh_p256_common_secret
(uint8_t r[32], const uint8_t s[32], const uint8_t p[64])¶ ECDH P-256 common secret.
The common secret is computed from both the client’s public key
p
and the server’s secret keys
and put intor
.- Remark
r
may be same ass
orp
.- Parameters
[out] r
: Generated common secret.s
: Server private key.p
: Client public key.
- Return Value
0
: Ifs
is a valid secret key andp
is a valid public key.-1
: Otherwise.
-
int
ECDSA APIs¶
-
group
nrf_oberon_ecdsa
Type declarations and APIs to do Elliptic Curve Digital Signature Algorith using the NIST secp256r1 curve.
Functions
-
int
ocrypto_ecdsa_p256_public_key
(uint8_t pk[64], const uint8_t sk[32])¶ ECDSA P-256 public key generation.
Given a secret key
sk
the corresponding public key is computed and put intopk
.- Parameters
[out] pk
: Generated public key.sk
: Secret key. Must be pre-filled with random data.
- Return Value
0
: Ifsk
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 keysk
and the ephemeral session keyek
. The signature is put intosig
.- Parameters
[out] sig
: Generated signature.m
: Input message.mlen
: Length ofm
.sk
: Secret key.ek
: Ephemeral session key.
- Return Value
0
: Ifek
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 keysk
and the ephemeral session keyek
. The signature is put intosig
.- Parameters
[out] sig
: Generated signature.hash
: Input hash.sk
: Secret key.ek
: Ephemeral session key.
- Return Value
0
: Ifek
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 messagem
is verified using the signer’s public keypk
.- Parameters
sig
: Input signature.m
: Input message.mlen
: Length ofm
.pk
: Signer’s public key.
- Return Value
0
: If the signature is valid.-1
: Otherwise.
-
int
ocrypto_ecdsa_p256_verify_hash
(const uint8_t sig[64], const uint8_t hash[32], const uint8_t pk[64])¶ ECDSA P-256 signature verification from SHA256 hash.
The signature
sig
of the message hashhash
is verified using the signer’s public keypk
.- Parameters
sig
: Input signature.hash
: Input hash.pk
: Signer’s public key.
- Return Value
0
: If the signature is valid.-1
: Otherwise.
-
int
Ed25519 APIs¶
-
group
nrf_oberon_ed25519
Type declarations and APIs for the Ed25519 algorithm.
Ed25519 is a specific implementation of EdDSA, a digital signature scheme. EdDSA is based on Twisted Edwards curves and is designed to be faster than existing digital signature schemes without sacrificing security. It was developed by Daniel J. Bernstein, et al. Ed25519 is intended to provide attack resistance comparable to quality 128-bit symmetric ciphers.
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 intopk
. The key pair can then be used to sign and verify message signatures.- Parameters
[out] pk
: Generated public key.sk
: Secret key. Must be pre-filled with random data.
-
void
ocrypto_ed25519_sign
(uint8_t sig[(64)], const uint8_t *m, size_t m_len, const uint8_t sk[(32)], const uint8_t pk[(32)])¶ Ed25519 signature generate.
The message
m
is signed using the secret keysk
and the corresponding public keypk
. The signature is put intosig
.- Parameters
[out] sig
: Generated signature.m
: Input message.m_len
: Length ofm
.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 messagem
is verified using the signer’s public keypk
.- Parameters
sig
: Input signature.m
: Input message.m_len
: Length ofm
.pk
: Signer’s public key.
- Return Value
0
: If the signature is valid.-1
: Otherwise.
-
HKDF - HMAC based Key Derivation Function¶
-
group
nrf_oberon_hkdf
HKDF is a key derivation function based on HMAC Extract-and-Expand.
HKDF APIs using SHA-256¶
-
group
nrf_oberon_hkdf_256
Type declarations and APIs for the HKDF-SHA256 algorithm.
HKDF-SHA256 is a key derivation function based on HMAC-SHA256.
Defines
-
ocrypto_hkdf_sha256_LENGTH_MAX
¶ Maximum length of a derived key.
-
ocrypto_hkdf_sha256_SALT_LENGTH_MAX
¶ Maximum salt length.
Functions
-
void
ocrypto_hkdf_sha256
(uint8_t *r, size_t r_len, const uint8_t *key, size_t key_len, const uint8_t *salt, size_t salt_len, const uint8_t *info, size_t info_len)¶ HKDF-SHA256 algorithm.
A new pseudo-random key of length
r_len
is derived from an input keykey
, a saltsalt
and additional informationinfo
. The new key is put intor
.- Parameters
[out] r
: Output key.r_len
: Length ofr
, 0 <r_len
<=ocrypto_hkdf_sha256_LENGTH_MAX
.key
: Input key.key_len
: Length ofkey
.salt
: Salt.salt_len
: Length of saltsalt
. 0 <=salt_len
<=ocrypto_hkdf_sha256_SALT_LENGTH_MAX
.info
: Additional information.info_len
: Length ofinfo
.
-
HKDF APIs using SHA-512¶
-
group
nrf_oberon_hkdf_512
Type declaration and APIs for the HKDF-SHA512 algorithm.
HKDF-SHA512 is a key derivation function based on HMAC-SHA512.
Defines
-
ocrypto_hkdf_sha512_LENGTH_MAX
¶ Maximum length of a derived key.
-
ocrypto_hkdf_sha512_SALT_LENGTH_MAX
¶ Maximum salt length.
Functions
-
void
ocrypto_hkdf_sha512
(uint8_t *r, size_t r_len, const uint8_t *key, size_t key_len, const uint8_t *salt, size_t salt_len, const uint8_t *info, size_t info_len)¶ HKDF-SHA512 algorithm.
A new pseudo-random key of length
r_len
is derived from an input keykey
, a saltsalt
and additional informationinfo
. The new key is put intor
.- Parameters
[out] r
: Output key.r_len
: Length ofr
, 0 <r_len
<=ocrypto_hkdf_sha512_LENGTH_MAX
.key
: Input key.key_len
: Length ofkey
.salt
: Salt.salt_len
: Length of saltsalt
. 0 <=salt_len
<=ocrypto_hkdf_sha512_SALT_LENGTH_MAX
.info
: Additional information.info_len
: Length ofinfo
.
-
HMAC - Hash-based Aessage Authentication Code¶
-
group
nrf_oberon_hmac
HMAC is a hash-based Message Authentication Code utilizing a secure hash function.
HMAC APIs using SHA-256¶
-
group
nrf_oberon_hmac_256
Type declarations and APIs for the HMAC-SHA256 algorithm.
HMAC-SHA256 is an algorithm for message authentication using the cryptographic hash function SHA256 and a reusable secret key. Users in possession of the key can verify the integrity and authenticity of the message.
Incremental HMAC-SHA256 generator.
This group of functions can be used to incrementally compute HMAC-SHA256 for a given message.
-
void
ocrypto_hmac_sha256_init
(ocrypto_hmac_sha256_ctx *ctx, const uint8_t *key, size_t key_len)¶ HMAC-SHA256 initialization.
The generator state
ctx
is initialized by this function.- Parameters
[out] ctx
: Generator state.key
: HMAC key.key_len
: Length ofkey
.
-
void
ocrypto_hmac_sha256_update
(ocrypto_hmac_sha256_ctx *ctx, const uint8_t *in, size_t in_len)¶ HMAC-SHA256 incremental data input.
The generator state
ctx
is updated to hash a message chunkin
.This function can be called repeatedly until the whole message is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_hmac_sha256_init
is required before this function can be called.- Parameters
[inout] ctx
: Generator state.in
: Input data.in_len
: Length ofin
.
-
void
ocrypto_hmac_sha256_final
(ocrypto_hmac_sha256_ctx *ctx, uint8_t r[(32)])¶ HMAC-SHA256 output.
The generator state
ctx
is updated to finalize the HMAC calculation. The HMAC digest is put intor
.- Remark
Initialization of the generator state
ctx
throughocrypto_hmac_sha256_init
is required before this function can be called.- Remark
After return, the generator state
ctx
must no longer be used withocrypto_hmac_sha256_update
andocrypto_hmac_sha256_final
unless it is reinitialized usingocrypto_hmac_sha256_init
.- Parameters
[inout] ctx
: Generator state.[out] r
: Generated HMAC digest.
Defines
-
ocrypto_hmac_sha256_KEY_BYTES_MAX
¶ Maximum key length.
-
ocrypto_hmac_sha256_BYTES
¶ Length of the authenticator.
Functions
-
void
ocrypto_hmac_sha256
(uint8_t r[(32)], const uint8_t *key, size_t key_len, const uint8_t *in, size_t in_len)¶ HMAC-SHA256 algorithm.
The input message
in
is authenticated using the keyk
. The computed authenticator is put intor
. To verify the authenticator, the recipient needs to recompute the HMAC authenticator and can then compare it with the received authenticator.- Parameters
[out] r
: HMAC output.key
: HMAC key.key_len
: Length ofkey
. 0 <=key_len
<=ocrypto_hmac_sha256_KEY_BYTES_MAX
.in
: Input data.in_len
: Length ofin
.
-
void
HMAC APIs using SHA-512¶
-
group
nrf_oberon_hmac_512
Type declarations and APIs for the HMAC-SHA512 algorithm.
HMAC-SHA512 is an algorithm for message authentication using the cryptographic hash function SHA512 and a reusable secret key. Users in possession of the key can verify the integrity and authenticity of the message.
Incremental HMAC-SHA512 generator.
This group of functions can be used to incrementally compute HMAC-SHA512 for a given message.
-
void
ocrypto_hmac_sha512_init
(ocrypto_hmac_sha512_ctx *ctx, const uint8_t *key, size_t key_len)¶ HMAC-SHA512 initialization.
The generator state
ctx
is initialized by this function.- Parameters
[out] ctx
: Generator state.key
: HMAC key.key_len
: Length ofkey
.
-
void
ocrypto_hmac_sha512_update
(ocrypto_hmac_sha512_ctx *ctx, const uint8_t *in, size_t in_len)¶ HMAC-SHA512 incremental data input.
The generator state
ctx
is updated to hash a message chunkin
.This function can be called repeatedly until the whole message is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_hmac_sha512_init
is required before this function can be called.- Parameters
[inout] ctx
: Generator state.in
: Input data.in_len
: Length ofin
.
-
void
ocrypto_hmac_sha512_final
(ocrypto_hmac_sha512_ctx *ctx, uint8_t r[(64)])¶ HMAC-SHA512 output.
The generator state
ctx
is updated to finalize the HMAC calculation. The HMAC digest is put intor
.- Remark
Initialization of the generator state
ctx
throughocrypto_hmac_sha512_init
is required before this function can be called.- Remark
After return, the generator state
ctx
must no longer be used withocrypto_hmac_sha512_update
andocrypto_hmac_sha512_final
unless it is reinitialized usingocrypto_hmac_sha512_init
.- Parameters
[inout] ctx
: Generator state.[out] r
: Generated HMAC digest.
Defines
-
ocrypto_hmac_sha512_KEY_BYTES_MAX
¶ Maximum key length.
-
ocrypto_hmac_sha512_BYTES
¶ Length of the authenticator.
Functions
-
void
ocrypto_hmac_sha512
(uint8_t r[(64)], const uint8_t *key, size_t key_len, const uint8_t *in, size_t in_len)¶ HMAC-SHA512 algorithm.
The input message
in
is authenticated using the keyk
. The computed authenticator is put intor
. To verify the authenticator, the recipient needs to recompute the HMAC authenticator and can then compare it with the received authenticator.- Parameters
[out] r
: HMAC output.key
: HMAC key.key_len
: Length ofkey
. 0 <=key_len
<=ocrypto_hmac_sha512_KEY_BYTES_MAX
.in
: Input data.in_len
: Length ofin
.
-
void
RSA - Rivest-Shamir-Adleman algorithm¶
-
group
nrf_oberon_rsa
RSA is a number theoretic public-key encryption and signature algorithm.
RSA APIs¶
-
group
nrf_oberon_rsa_api
APIs to for RSA encryption/decryption and sign/verify using PKCS1 v1.5, OEAP and PSS.
These functions support RSA encryption and signatures with 1024 and 2048-bit modulo and PKCS1 V1.5 padding.
1024-bit RSA Functions.
This group of functions is used for 1024-bit RSA.
-
int
ocrypto_rsa1024_pkcs1_v15_encrypt
(uint8_t c[128], const uint8_t *m, size_t mlen, const uint8_t *seed, size_t slen, const ocrypto_rsa1024_pub_key *pk)¶ 1024 bit RSA PKCS1 V1.5 encryption.
The message
m
is encrypted to a ciphertext returned inc
.- Remark
The key
pk
should be initialized withocrypto_rsa1024_init_pub_key
.- Remark
The
seed
should consist of non-zero random bytes.- Remark
c
andm
can point to the same address.- Parameters
[out] c
: The generated 128-byte ciphertext.m
: The message to be encrypted.mlen
: Length ofm
. 0 <= mlen <= 117.seed
: The random seed to be used for the padding.slen
: Length ofseed
.slen
>= 125 -mlen
.pk
: A valid 1024-bit RSA public key.
- Return Value
-1
: If the message is too long (mlen > 117).-2
: If the seed is too short (slen < 125 - mlen).0
: Otherwise.
-
int
ocrypto_rsa1024_pkcs1_v15_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[128], const ocrypto_rsa1024_key *k)¶ 1024-bit RSA PKCS1 V1.5 decryption.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa1024_init_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 128-byte ciphertext to decrypt.k
: A valid 1024-bit RSA secret key.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa1024_pkcs1_v15_crt_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[128], const ocrypto_rsa1024_crt_key *k)¶ 1024-bit RSA PKCS1 V1.5 decryption with CRT acceleration.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa1024_init_crt_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 128-byte ciphertext to decrypt.k
: A valid 1024-bit RSA secret key with CRT coefficients.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa1024_oaep_sha256_encrypt
(uint8_t c[128], const uint8_t *m, size_t mlen, const uint8_t *label, size_t llen, const uint8_t seed[32], const ocrypto_rsa1024_pub_key *pk)¶ 1024-bit RSA OAEP SHA256 encryption.
The message
m
is encrypted to a ciphertext returned inc
.- Remark
The key
pk
should be initialized withocrypto_rsa1024_init_pub_key
.- Remark
c
andm
can point to the same address.- Parameters
[out] c
: The generated 128-byte ciphertext.m
: The message to be encrypted.mlen
: Length ofm
. 0 <= mlen <= 62.label
: The label associated with the message.llen
: Length oflabel
. May be 0.seed
: 32-byte random seed.pk
: A valid 1024-bit RSA public key.
- Return Value
-1
: If the message is too long (mlen > 62).0
: Otherwise.
-
int
ocrypto_rsa1024_oaep_sha256_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[128], const uint8_t *label, size_t llen, const ocrypto_rsa1024_key *k)¶ 1024-bit RSA OAEP SHA256 decryption.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa1024_init_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 128-byte ciphertext to decrypt.label
: The label associated with the message.llen
: Length oflabel
. May be 0.k
: A valid 1024-bit RSA secret key.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa1024_oaep_sha256_crt_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[128], const uint8_t *label, size_t llen, const ocrypto_rsa1024_crt_key *k)¶ 1024-bit RSA OAEP SHA256 decryption with CRT acceleration.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa1024_init_crt_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 128-byte ciphertext to decrypt.label
: The label associated with the message.llen
: Length oflabel
. May be 0.k
: A valid 1024-bit RSA secret key with CRT coefficients.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa1024_pkcs1_v15_sha256_sign
(uint8_t s[128], const uint8_t *m, size_t mlen, const ocrypto_rsa1024_key *k)¶ 1024-bit RSA PKCS1 V1.5 SHA-256 sign.
The message
m
is signed and the signature returned ins
.- Return
0
- Remark
The key
k
should be initialized withocrypto_rsa1024_init_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 128-byte signature.m
: The message to be signed.mlen
: Length ofm
.k
: A valid 1024-bit RSA secret key.
-
int
ocrypto_rsa1024_pkcs1_v15_sha256_crt_sign
(uint8_t s[128], const uint8_t *m, size_t mlen, const ocrypto_rsa1024_crt_key *k)¶ 1024-bit RSA PKCS1 V1.5 SHA-256 sign with CRT acceleration.
The message
m
is signed and the signature returned ins
.- Return
0
- Remark
The key
k
should be initialized withocrypto_rsa1024_init_crt_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 128-byte signature.m
: The message to be signed.mlen
: Length ofm
.k
: A valid 1024-bit RSA secret key with CRT coefficients.
-
int
ocrypto_rsa1024_pkcs1_v15_sha256_verify
(const uint8_t s[128], const uint8_t *m, size_t mlen, const ocrypto_rsa1024_pub_key *pk)¶ 1024-bit RSA PKCS1 V1.5 SHA-256 signature verify.
The signature
s
is verified for a valid signature of messagem
.- Remark
The key
pk
should be initialized withocrypto_rsa1024_init_pub_key
.- Parameters
s
: The 128-byte signature.m
: The signed message.mlen
: Length ofm
.pk
: A valid 1024-bit RSA public key.
- Return Value
0
: If the signature is valid.-1
: If verification failed.
-
int
ocrypto_rsa1024_pss_sha256_sign
(uint8_t s[128], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa1024_key *k)¶ 1024-bit RSA PSS SHA-256 sign.
The message
m
is signed and the signature returned ins
.- Remark
The key
k
should be initialized withocrypto_rsa1024_init_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 128-byte signature.m
: The message to be signed.mlen
: Length ofm
.salt
: The salt to be used.slen
: Length ofsalt
.k
: A valid 1024-bit RSA secret key.
- Return Value
-2
: If the salt is too long.0
: Otherwise.
-
int
ocrypto_rsa1024_pss_sha256_crt_sign
(uint8_t s[128], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa1024_crt_key *k)¶ 1024-bit RSA PSS SHA-256 sign with CRT acceleration.
The message
m
is signed and the signature returned ins
.- Remark
The key
k
should be initialized withocrypto_rsa1024_init_crt_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 128-byte signature.m
: The message to be signed.mlen
: Length ofm
.salt
: The salt to be used.slen
: Length ofsalt
.k
: A valid 1024-bit RSA secret key with CRT coefficients.
- Return Value
-2
: If the salt is too long.0
: Otherwise.
-
int
ocrypto_rsa1024_pss_sha256_verify
(const uint8_t s[128], const uint8_t *m, size_t mlen, size_t slen, const ocrypto_rsa1024_pub_key *pk)¶ 1024-bit RSA PSS SHA-256 signature verify.
The signature
s
is verified for a valid signature of messagem
.- Remark
The key
pk
should be initialized withocrypto_rsa1024_init_pub_key
.- Parameters
s
: The 128-byte signature.m
: The signed message.mlen
: Length ofm
.slen
: The length of the salt.pk
: A valid 1024-bit RSA public key.
- Return Value
0
: If the signature is valid.-1
: If verification failed.-2
: If the salt is too long.
2048-bit RSA Functions.
This group of functions is used for 2048-bit RSA.
-
int
ocrypto_rsa2048_pkcs1_v15_encrypt
(uint8_t c[256], const uint8_t *m, size_t mlen, const uint8_t *seed, size_t slen, const ocrypto_rsa2048_pub_key *pk)¶ 2048-bit RSA PKCS1 V1.5 encryption.
The message
m
is encrypted to a ciphertext returned inc
.- Remark
The key
pk
should be initialized withocrypto_rsa2048_init_pub_key
.- Remark
The
seed
should consist of non-zero random bytes.- Remark
c
andm
can point to the same address.- Parameters
[out] c
: The generated 256-byte ciphertext.m
: The message to be encrypted.mlen
: Length ofm
. 0 <=mlen
<= 245.seed
: The random seed to be used for the padding.slen
: Length ofseed
.slen
>= 253 -mlen
.pk
: A valid 2048-bit RSA public key.
- Return Value
-1
: If the message is too long (mlen > 245).-2
: If the seed is too short (slen < 253 - mlen).0
: Otherwise.
-
int
ocrypto_rsa2048_pkcs1_v15_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[256], const ocrypto_rsa2048_key *k)¶ 2048-bit RSA PKCS1 V1.5 decryption.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa2048_init_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 256-byte ciphertext to decrypt.k
: A valid 2048-bit RSA secret key.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa2048_pkcs1_v15_crt_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[256], const ocrypto_rsa2048_crt_key *k)¶ 2048-bit RSA PKCS1 V1.5 decryption with CRT acceleration.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa2048_init_crt_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 256-byte ciphertext to decrypt.k
: A valid 2048-bit RSA secret key with CRT coefficients.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa2048_oaep_sha256_encrypt
(uint8_t c[256], const uint8_t *m, size_t mlen, const uint8_t *label, size_t llen, const uint8_t seed[32], const ocrypto_rsa2048_pub_key *pk)¶ 2048-bit RSA OAEP SHA256 encryption.
The message
m
is encrypted to a ciphertext returned inc
.- Remark
The key
pk
should be initialized withocrypto_rsa2048_init_pub_key
.- Remark
c
andm
can point to the same address.- Parameters
[out] c
: The generated 256-byte ciphertext.m
: The message to be encrypted.mlen
: Length ofm
. 0 <= mlen <= 190.label
: The label associated with the message.llen
: Length oflabel
. May be 0.seed
: 32-byte random seed.pk
: A valid 2048-bit RSA public key.
- Return Value
-1
: If the message is too long (mlen > 190).0
: Otherwise.
-
int
ocrypto_rsa2048_oaep_sha256_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[256], const uint8_t *label, size_t llen, const ocrypto_rsa2048_key *k)¶ 2048-bit RSA OAEP SHA256 decryption.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa2048_init_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 256-byte ciphertext to decrypt.label
: The label associated with the message.llen
: Length oflabel
. May be 0.k
: A valid 2048-bit RSA secret key.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa2048_oaep_sha256_crt_decrypt
(uint8_t *m, size_t mlen, const uint8_t c[256], const uint8_t *label, size_t llen, const ocrypto_rsa2048_crt_key *k)¶ 2048-bit RSA OAEP SHA256 decryption with CRT acceleration.
The ciphertext
c
is decrypted to the message returned inm
.- Remark
The key
k
should be initialized withocrypto_rsa2048_init_crt_key
.- Remark
m
andc
can point to the same address.- Parameters
[out] m
: The decrypted message. The buffer must be long enough to hold the message.mlen
: Length ofm
.c
: The 256-byte ciphertext to decrypt.label
: The label associated with the message.llen
: Length oflabel
. May be 0.k
: A valid 2048-bit RSA secret key with CRT coefficients.
- Return Value
-1
: If decryption failed.-2
: If the output buffer is too short (mlen < length of message).n
: If a message of length n was successfully decrypted.
-
int
ocrypto_rsa2048_pkcs1_v15_sha256_sign
(uint8_t s[256], const uint8_t *m, size_t mlen, const ocrypto_rsa2048_key *k)¶ 2048-bit RSA PKCS1 V1.5 SHA-256 sign.
The message
m
is signed and the signature returned ins
.- Return
0
- Remark
The key
k
should be initialized withocrypto_rsa2048_init_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 256-byte signature.m
: The message to be signed.mlen
: Length ofm
.k
: A valid 2048-bit RSA secret key.
-
int
ocrypto_rsa2048_pkcs1_v15_sha256_crt_sign
(uint8_t s[256], const uint8_t *m, size_t mlen, const ocrypto_rsa2048_crt_key *k)¶ 2048-bit RSA PKCS1 V1.5 SHA-256 sign with CRT acceleration.
The message
m
is signed and the signature returned ins
.- Return
0
- Remark
The key
k
should be initialized withocrypto_rsa2048_init_crt_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 256-byte signature.m
: The message to be signed.mlen
: Length ofm
.k
: A valid 2048-bit RSA secret key with CRT coefficients.
-
int
ocrypto_rsa2048_pkcs1_v15_sha256_verify
(const uint8_t s[256], const uint8_t *m, size_t mlen, const ocrypto_rsa2048_pub_key *pk)¶ 2048-bit RSA PKCS1 V1.5 SHA-256 signature verify.
The signature
s
is verified for a correct signature of messagem
.- Remark
The key
pk
should be initialized withocrypto_rsa2048_init_pub_key
.- Parameters
s
: The 256-byte signature.m
: The signed message.mlen
: Length ofm
.pk
: A valid 2048-bit RSA public key.
- Return Value
0
: If the signature is valid.-1
: If verification failed.
-
int
ocrypto_rsa2048_pss_sha256_sign
(uint8_t s[256], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa2048_key *k)¶ 2048-bit RSA PSS SHA-256 sign.
The message
m
is signed and the signature returned ins
.- Remark
The key
k
should be initialized withocrypto_rsa2048_init_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 256-byte signature.m
: The message to be signed.mlen
: Length ofm
.salt
: The salt to be used.slen
: Length ofsalt
.k
: A valid 2048-bit RSA secret key.
- Return Value
-2
: If the salt is too long.0
: Otherwise.
-
int
ocrypto_rsa2048_pss_sha256_crt_sign
(uint8_t s[256], const uint8_t *m, size_t mlen, const uint8_t *salt, size_t slen, const ocrypto_rsa2048_crt_key *k)¶ 2048-bit RSA PSS SHA-256 sign with CRT acceleration.
The message
m
is signed and the signature returned ins
.- Remark
The key
k
should be initialized withocrypto_rsa2048_init_crt_key
.- Remark
s
andm
can point to the same address.- Parameters
[out] s
: The generated 256-byte signature.m
: The message to be signed.mlen
: Length ofm
.salt
: The salt to be used.slen
: Length ofsalt
.k
: A valid 2048-bit RSA secret key with CRT coefficients.
- Return Value
-2
: If the salt is too long.0
: Otherwise.
-
int
ocrypto_rsa2048_pss_sha256_verify
(const uint8_t s[256], const uint8_t *m, size_t mlen, size_t slen, const ocrypto_rsa2048_pub_key *pk)¶ 2048-bit RSA PSS SHA-256 signature verify.
The signature
s
is verified for a valid signature of messagem
.- Remark
The key
pk
should be initialized withocrypto_rsa2048_init_pub_key
.- Parameters
s
: The 256-byte signature.m
: The signed message.mlen
: Length ofm
.slen
: The length of the salt.pk
: A valid 2048-bit RSA public key.
- Return Value
0
: If the signature is valid.-1
: If verification failed.-2
: If the salt is too long.
-
int
RSA key APIs¶
-
group
nrf_oberon_rsa_key
Type declarations for RSA APIs.
RSA is a number theoretic public-key encryption and signature algorithm.
These functions support the setup of 1024 and 2048 RSA secret and public keys.
1024-bit RSA key setup
This group of functions is used for 1024-bit RSA key setup.
-
int
ocrypto_rsa1024_init_pub_key
(ocrypto_rsa1024_pub_key *k, const uint8_t *n, size_t nlen)¶ 1024-bit RSA public key setup.
- Remark
The public exponent is fixed at 65537.
- Parameters
[out] k
: The initialized public key.n
: The RSA modulus. Must be exactly 1024 bits.nlen
: Length ofn
.
- Return Value
-1
: If the input length is invalid.0
: Otherwise.
-
int
ocrypto_rsa1024_init_key
(ocrypto_rsa1024_key *k, const uint8_t *n, size_t nlen, const uint8_t *d, size_t dlen)¶ 1024-bit RSA secret key setup.
- Parameters
[out] k
: The initialized public key.n
: The RSA modulus. Must be exactly 1024 bits.nlen
: Length ofn
.d
: The secret exponent. Must be <= 1024 bits.dlen
: Length ofd
.
- Return Value
-1
: If the input length is invalid.0
: Otherwise.
-
int
ocrypto_rsa1024_init_crt_key
(ocrypto_rsa1024_crt_key *k, const uint8_t *p, size_t plen, const uint8_t *q, size_t qlen, const uint8_t *dp, size_t dplen, const uint8_t *dq, size_t dqlen, const uint8_t *qinv, size_t qilen)¶ 1024-bit RSA secret key setup with CRT coefficients.
- Parameters
[out] k
: The initialized secret key.p
: The 1. RSA prime. Must be exactly 512 bits.plen
: Length ofp
.q
: The 2. RSA prime. Must be exactly 512 bits.qlen
: Length ofq
.dp
: The 1. CRT exponent. dp = d mod (p-1).dplen
: Length ofdp
.dq
: The 2. CRT exponent. dq = d mod (q-1).dqlen
: Length ofdq
.qinv
: The CRT coefficient. qinv = 1/q mod p.qilen
: Length ofqinv
.
- Return Value
-1
: If the input length is invalid.0
: Otherwise.
2048-bit RSA key setup
This group of functions is used for 2048-bit RSA key setup.
-
int
ocrypto_rsa2048_init_pub_key
(ocrypto_rsa2048_pub_key *k, const uint8_t *n, size_t nlen)¶ 2048-bit RSA public key setup.
- Remark
The public exponent is fixed at 65537.
- Parameters
[out] k
: The initialized public key.n
: The RSA modulus. Must be exactly 2048 bits.nlen
: Length ofn
.
- Return Value
-1
: If the input length is invalid.0
: Otherwise.
-
int
ocrypto_rsa2048_init_key
(ocrypto_rsa2048_key *k, const uint8_t *n, size_t nlen, const uint8_t *d, size_t dlen)¶ 2048-bit RSA secret key setup.
- Parameters
[out] k
: The initialized public key.n
: The RSA modulus. Must be exactly 2048 bits.nlen
: Length ofn
.d
: The secret exponent. Must be <= 2048 bits.dlen
: Length ofd
.
- Return Value
-1
: If the input length is invalid.0
: Otherwise.
-
int
ocrypto_rsa2048_init_crt_key
(ocrypto_rsa2048_crt_key *k, const uint8_t *p, size_t plen, const uint8_t *q, size_t qlen, const uint8_t *dp, size_t dplen, const uint8_t *dq, size_t dqlen, const uint8_t *qinv, size_t qilen)¶ 2048-bit RSA secret key setup with CRT coefficients.
- Parameters
[out] k
: The initialized secret key.p
: The 1. RSA prime. Must be exactly 1024 bits.plen
: Length ofp
.q
: The 2. RSA prime. Must be exactly 1024 bits.qlen
: Length ofq
.dp
: The 1. CRT exponent. dp = d mod (p-1).dplen
: Length ofdp
.dq
: The 2. CRT exponent. dq = d mod (q-1).dqlen
: Length ofdq
.qinv
: The CRT coefficient. qinv = 1/q mod p.qilen
: Length ofqinv
.
- Return Value
-1
: If the input length is invalid.0
: Otherwise.
Defines
-
PUB_EXP
¶ The Public RSA Exponent.
-
struct
ocrypto_rsa1024_pub_key
¶ - #include <ocrypto_rsa_key.h>
1024-bit RSA public key.
-
struct
ocrypto_rsa1024_key
¶ - #include <ocrypto_rsa_key.h>
1024 bit RSA secret key.
-
struct
ocrypto_rsa1024_crt_key
¶ - #include <ocrypto_rsa_key.h>
1024-bit RSA secret key with CRT coefficients.
-
struct
ocrypto_rsa2048_pub_key
¶ - #include <ocrypto_rsa_key.h>
2048-bit RSA public key.
-
struct
ocrypto_rsa2048_key
¶ - #include <ocrypto_rsa_key.h>
2048-bit RSA secret key.
-
struct
ocrypto_rsa2048_crt_key
¶ - #include <ocrypto_rsa_key.h>
2048-bit RSA secret key with CRT coefficients.
-
int
SHA-256 APIs¶
-
group
nrf_oberon_sha_256
Type declarations and APIs for the SHA-256 algorithm.
SHA-256 is part of the SHA-2 family that is a set of cryptographic hash functions designed by the NSA. It is the successor of the SHA-1 algorithm.
A fixed-sized message digest is computed from variable length input data. The function is practically impossible to revert, and small changes in the input message lead to major changes in the message digest.
Incremental SHA-256 generator
This group of functions can be used to incrementally compute the SHA-256 hash for a given message.
-
void
ocrypto_sha256_init
(ocrypto_sha256_ctx *ctx)¶ SHA-256 initialization.
The generator state
ctx
is initialized by this function.- Parameters
[out] ctx
: Generator state.
-
void
ocrypto_sha256_update
(ocrypto_sha256_ctx *ctx, const uint8_t *in, size_t in_len)¶ SHA-256 incremental data input.
The generator state
ctx
is updated to hash a message chunkin
.This function can be called repeatedly until the whole message is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_sha256_init
is required before this function can be called.- Parameters
ctx
: Generator state.in
: Input data.in_len
: Length ofin
.
-
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 intor
.- Remark
Initialization of the generator state
ctx
throughocrypto_sha256_init
is required before this function can be called.- Remark
After return, the generator state
ctx
must no longer be used withocrypto_sha256_update
andocrypto_sha256_final
unless it is reinitialized usingocrypto_sha256_init
.- Parameters
ctx
: Generator state.[out] r
: Generated hash value.
Defines
-
ocrypto_sha256_BYTES
¶ Length of SHA-256 hash.
Functions
-
void
ocrypto_sha256
(uint8_t r[(32)], const uint8_t *in, size_t in_len)¶ SHA-256 hash.
The SHA-256 hash of a given input message
in
is computed and put intor
.- Parameters
[out] r
: Generated hash.in
: Input data.in_len
: Length ofin
.
-
void
SHA-512 APIs¶
-
group
nrf_oberon_sha_512
Type declarations and APIs for the SHA-512 algorithm.
SHA-512 is part of the SHA-2 family that is a set of cryptographic hash functions designed by the NSA. It is the successor of the SHA-1 algorithm.
A fixed-sized message digest is computed from variable length input data. The function is practically impossible to revert, and small changes in the input message lead to major changes in the message digest.
Incremental SHA-512 generator
This group of functions can be used to incrementally compute the SHA-512 hash for a given message.
-
void
ocrypto_sha512_init
(ocrypto_sha512_ctx *ctx)¶ SHA-512 initialization.
The generator state
ctx
is initialized by this function.- Parameters
[out] ctx
: Generator state.
-
void
ocrypto_sha512_update
(ocrypto_sha512_ctx *ctx, const uint8_t *in, size_t in_len)¶ SHA-512 incremental data input.
The generator state
ctx
is updated to hash a message chunkin
.This function can be called repeatedly until the whole message is processed.
- Remark
Initialization of the generator state
ctx
throughocrypto_sha512_init
is required before this function can be called.- Parameters
ctx
: Generator state.in
: Input data.in_len
: Length ofin
.
-
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 intor
.- Remark
Initialization of the generator state
ctx
throughocrypto_sha512_init
is required before this function can be called.- Remark
After return, the generator state
ctx
must no longer be used withocrypto_sha512_update
andocrypto_sha512_final
unless it is reinitialized usingocrypto_sha512_init
.- Parameters
ctx
: Generator state.[out] r
: Generated hash value.
Defines
-
ocrypto_sha512_BYTES
¶ Length of SHA-512 hash.
Functions
-
void
ocrypto_sha512
(uint8_t r[(64)], const uint8_t *in, size_t in_len)¶ SHA-512 hash.
The SHA-512 hash of a given input message
in
is computed and put intor
.- Parameters
[out] r
: Generated hash.in
: Input data.in_len
: Length ofin
.
-
void
SRP - Secure Remote Password APIs¶
-
group
nrf_oberon_srp
Type declarations and APIs for the SRP key agreement protocol.
SRP is an augmented password-authenticated key agreement protocol, specifically designed to work around existing patents. SRP allows the use of user names and passwords over unencrypted channels and supplies a shared secret at the end of the authentication sequence that can be used to generate encryption keys.
An eavesdropper or man in the middle cannot obtain enough information to be able to brute force guess a password without further interactions with the parties for each guess.
The server does not store password-equivalent data. This means that an attacker who steals the server data cannot masquerade as the client unless they first perform a brute force search for the password.
The specific variant implemented here is SRP-6 3072 bit SHA-512.
Basic protocol overview
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 passwordpass
and saltsalt
.- Parameters
[out] v
: Generated password verifier, must be 32-bit aligned.salt
: Salt.user
: User name.user_len
: Length ofuser
.pass
: Password.pass_len
: Length ofpass
.
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 verifierv
and put intopub_b
.- Parameters
[out] pub_b
: Generated public key, must be 32-bit aligned.priv_b
: Private key.v
: Password verifier.
SRP-6 Session key generation
A premaster secret can be derived from both the client’s and server’s public keys, the server’s private key and the password verifier. A shared session key can be generated from this premaster secret.
-
void
ocrypto_srp_scrambling_parameter
(uint8_t u[(64)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)])¶ SRP-6 Scrambling Parameter.
The scrambling parameter is computed from both the client’s public key
pub_a
and the server’s public keypub_b
. The scrambling parameter is required to compute the premaster secret.- Parameters
[out] u
: Generated scrambling parameter.pub_a
: Client public key.pub_b
: Server public key.
-
int
ocrypto_srp_premaster_secret
(uint8_t s[(384)], const uint8_t pub_a[(384)], const uint8_t priv_b[(32)], const uint8_t u[(64)], const uint8_t v[(384)])¶ SRP-6 Premaster Secret.
The premaster secret between the client and the server is computed using the client public key
pub_a
, the server private keypriv_b
, the scrambling parameteru
and the password verifierv
. If the client public keypub_a
is valid, the premaster secret is then put intos
. The premaster secret can be used to generate encryption keys.- Parameters
[out] s
: Generated premaster secret, must be 32-bit aligned.pub_a
: Client public key.priv_b
: Server private key.u
: Scrambling parameter; generated withsrp_scrambling_parameter
.v
: Password verifier.
- Return Value
0
: Ifpub_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 intok
.- Parameters
[out] k
: Generated SRP session key.s
: Premaster secret.
SRP-6 Proof exchange
Proofs are exchanged from client to server and vice versa to ensure that both parties computed the same shared session key. The proofs only match if the correct password is used by the client.
-
void
ocrypto_srp_proof_m1
(uint8_t m1[(64)], const uint8_t *user, size_t user_len, const uint8_t salt[(16)], const uint8_t pub_a[(384)], const uint8_t pub_b[(384)], const uint8_t k[(64)])¶ SRP-6 Proof M1 (client to server).
A proof is generated by the client and sent to the server to assert that the client is in possession of the shared session key
k
. The server also generates the proof. Only if the proofs match, the process can continue. The proof is based on the saltsalt
, the client public keypub_a
, the server public keypub_b
and the shared session keyk
.- Parameters
[out] m1
: Generated proof.user
: User name.user_len
: Length ofuser
.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 keyk
. The second proof is based on the client public keypub_a
, the first proofm1
and the session keyk
.- Parameters
[out] m2
: Generated proof.pub_a
: Client public key.m1
: First proof. Generated withsrp_proof_m1
.k
: Session key.
Defines
-
ocrypto_srp_SALT_BYTES
¶ Salt length.
-
ocrypto_srp_VERIFIER_BYTES
¶ Password verifier length.
-
ocrypto_srp_SECRET_KEY_BYTES
¶ Secret key length.
-
ocrypto_srp_PUBLIC_KEY_BYTES
¶ Public key length.
-
ocrypto_srp_SCRAMBLING_PARAMETER_BYTES
¶ Scrambling parameter length.
-
ocrypto_srp_PREMASTER_SECRET_BYTES
¶ Premaster secret length.
-
ocrypto_srp_SESSION_KEY_BYTES
¶ Session key length.
-
ocrypto_srp_PROOF_BYTES
¶ Proof length.
SRPT - Secure Real-Time Transport Protocol APIs¶
-
group
nrf_oberon_srpt
Type declarations and APIs for SRTP - Secure Real-time Transport Protocol.
SRTP is an extension of the RTP protocol with an enhanced security mechanism.
Defines
-
ocrypto_srtp_AuthKeySize
¶ SRTP Authentication Key Size.
-
ocrypto_srtp_SaltSize
¶ SRTP Salt Size.
-
ocrypto_srtp_MaxKeySize
¶ SRTP Maximum Key Size.
Functions
-
void
ocrypto_srtp_setupContext
(ocrypto_srtp_context *srtpContext, ocrypto_srtp_context *srtcpContext, const uint8_t *key, uint32_t keySize, const uint8_t *salt, uint32_t tagSize, uint32_t ssrc)¶ Setup SRTP contexts.
- Parameters
[out] srtpContext
: SRTP context to be setup.[out] srtcpContext
: SRTCP context to be setup.key
: Master key.keySize
: Size of the master key (16, 24, or 32 bytes)salt
: Master salt.tagSize
: Size of the authentication tag.ssrc
: Synchronization source.
-
void
ocrypto_srtp_encrypt
(const ocrypto_srtp_context *srtpContext, uint8_t *packet, const uint8_t *dataBytes, size_t numHeaderBytes, size_t numDataBytes, uint32_t index)¶ Encrypt SRTP packet.
The final packet consists of
numHeaderBytes
encrypted in place, followed bynumDataBytes
copied fromdataBytes
during encryption.- Parameters
srtpContext
: SRTP context.[inout] packet
: Encrypted packet.dataBytes
: Data bytes to be encrypted.numHeaderBytes
: Number of header bytes.numDataBytes
: Number of data bytes.index
: Packet index.
-
void
ocrypto_srtp_decrypt
(const ocrypto_srtp_context *srtpContext, uint8_t *data, const uint8_t *packetBytes, size_t numPacketBytes, uint32_t index)¶ Decrypt SRTP packet.
- Parameters
srtpContext
: SRTP context.[out] data
: Decrypted data.packetBytes
: Packet bytes.numPacketBytes
: Number of packet bytes.index
: Packet index.
-
void
ocrypto_srtp_authenticate
(const ocrypto_srtp_context *context, uint8_t *tag, const uint8_t *bytes, size_t numBytes, uint32_t index)¶ Generate SRTP authentication tag from bytes and index.
- Parameters
context
: SRTP context.[out] tag
: Authentication tag generated.bytes
: Byte buffer.numBytes
: Number of bytes in buffer.index
: Index.
-
int
ocrypto_srtp_verifyAuthentication
(const ocrypto_srtp_context *context, const uint8_t *tag, const uint8_t *bytes, size_t numBytes, uint32_t index)¶ Check SRTP authentication tag against bytes and index.
- Parameters
context
: SRTP context.tag
: Tag.bytes
: Byte buffer.numBytes
: Number of bytes in buffer.index
: Index.
- Return Value
1
: If the tag is valid.0
: Otherwise.
-
struct
ocrypto_srtp_context
¶ - #include <ocrypto_srtp.h>
SRTP Context.
-