API documentation

API reference for the Mbed TLS glue layer.

Mbed TLS glue layer

group mbedcrypto_glue

nrf_security mbedcrypto glue library containing glue functionality for mbedcrypto APIs when using multiple backends.

mbedcrypto AES glue

group mbedcrypto_glue_aes

Glue layer for mbedcrypto AES APIs, including typedefs for backend API abstraction.

Typedefs

typedef int (*mbedtls_aes_check_fn)(unsigned int keybits, int mode, int xts)

Function pointer that checks if AES is supported by the backend, depending on the given key size in bits, mode, and usage of XTS.

The value returned by the backend implementing this function pointer is dynamically checked. If the return value is 0, then the backend does not support the AES cipher (mode, key size etc). If the value is positive, then the backend with the highest value is selected (priority based).

Parameters

  • keybits – [in] Key size in bits for the AES functionality.

  • mode – [in] AES mode.

  • xts – [in] If 1, XTS mode is used. Otherwise 0.

Returns

0 if the AES functionality is not supported, otherwise a priority where higher is better.

typedef void (*mbedtls_aes_init_fn)(mbedtls_aes_context *ctx)

Function pointer to initialize a glue AES context.

This function pointer has a signature equal to mbedtls_aes_init. This function inits or resets the glue context for an AES operation.

Parameters

  • ctx – [inout] Pointer to the context to initialize.

typedef void (*mbedtls_aes_free_fn)(mbedtls_aes_context *ctx)

Function pointer to free a glue AES context.

This function pointer has a signature equal to mbedtls_aes_free. This function resets the glue context for an AES operation.

Parameters

  • ctx – [inout] Pointer to the context to free.

typedef void (*mbedtls_aes_xts_init_fn)(mbedtls_aes_xts_context *ctx)

Function pointer to initialize a glue AES XTS context.

This function pointer has a signature equal to mbedtls_aes_xts_init. This function initializes or resets the glue context for an AES XTS operation.

Parameters

  • ctx – [inout] Pointer to the context to initialize.

typedef void (*mbedtls_aes_xts_free_fn)(mbedtls_aes_xts_context *ctx)

Function pointer to free a glue AES XTS context.

This function pointer has a signature equal to mbedtls_aes_xts_free. This function frees the glue context for an AES XTS operation.

Parameters

  • ctx – [inout] Pointer to the context to free.

typedef int (*mbedtls_aes_setkey_enc_fn)(mbedtls_aes_context *ctx, const unsigned char *key, unsigned int keybits)

Function pointer to set AES Encryption key in a glue context.

This function pointer has a signature equal to mbedtls_aes_setkey_enc.

Parameters

  • ctx – [inout] Pointer to the context to set the encryption key in.

  • key – [in] Pointer to the array holding the encryption key.

  • keybits – [in] Key size in bits.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_setkey_dec_fn)(mbedtls_aes_context *ctx, const unsigned char *key, unsigned int keybits)

Function pointer to set AES decryption key in a glue context.

This function pointer has a signature equal to mbedtls_aes_setkey_dec.

Parameters

  • ctx – [inout] Pointer to the context to set the decryption key in.

  • key – [in] Pointer to the array holding the decryption key.

  • keybits – [in] Key size in bits.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_xts_setkey_enc_fn)(mbedtls_aes_xts_context *ctx, const unsigned char *key, unsigned int keybits)

Function pointer to set AES XTS encryption key in a glue context.

This function pointer has a signature equal to mbedtls_aes_xts_setkey_enc.

Parameters

  • ctx – [inout] Pointer to the context to set the encryption key in.

  • key – [in] Pointer to the array holding the encryption key.

  • keybits – [in] Key size in bits.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_xts_setkey_dec_fn)(mbedtls_aes_xts_context *ctx, const unsigned char *key, unsigned int keybits)

Function pointer to set AES XTS decryption key in a glue context.

This function pointer has a signature equal to mbedtls_aes_xts_setkey_dec.

Parameters

  • ctx – [inout] Pointer to the context to set the decryption key in.

  • key – [in] Pointer to the array holding the decryption key.

  • keybits – [in] Key size in bits.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_internal_aes_encrypt_fn)(mbedtls_aes_context *ctx, const unsigned char input[16], unsigned char output[16])

Function pointer to perform an AES encryption.

This function pointer has a signature equal to mbedtls_internal_aes_encrypt.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt operation.

  • input – [in] Array of the block to encrypt (16 bytes).

  • output – [out] Array of the buffer to hold the encrypted block (16 bytes).

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_internal_aes_decrypt_fn)(mbedtls_aes_context *ctx, const unsigned char input[16], unsigned char output[16])

Function pointer to perform an AES decryption.

This function pointer has a signature equal to mbedtls_internal_aes_decrypt.

Parameters

  • ctx – [inout] Pointer to the context for the decrypt operation.

  • input – [in] Array of the block to decrypt (16 bytes).

  • output – [out] Array of the buffer to hold the decrypted block (16 bytes).

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_crypt_cbc_fn)(mbedtls_aes_context *ctx, int mode, size_t length, unsigned char iv[16], const unsigned char *input, unsigned char *output)

Function pointer to encrypt/decrypt using AES CBC.

This function pointer has a signature equal to mbedtls_aes_crypt_cbc.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt/decrypt operation.

  • mode – [in] Mode of AES operation (encrypt/decrypt).

  • length – [in] Length of the input/output data.

  • iv – [in] Array with the initialization vector used for the encrypt/decrypt operation.

  • input – [in] Pointer to the buffer holding the input data.

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

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_crypt_xts_fn)(mbedtls_aes_xts_context *ctx, int mode, size_t length, const unsigned char data_unit[16], const unsigned char *input, unsigned char *output)

Function pointer to encrypt/decrypt using AES XTS.

This function pointer has a signature equal to mbedtls_aes_crypt_xts.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt/decrypt operation.

  • mode – [in] Mode of AES operation (encrypt/decrypt).

  • length – [in] Length of the input/output data.

  • data_unit – [in] Array with data_unit used for the encrypt/decrypt operation.

  • input – [in] Pointer to the buffer holding the input data.

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

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_crypt_cfb128_fn)(mbedtls_aes_context *ctx, int mode, size_t length, size_t *iv_off, unsigned char iv[16], const unsigned char *input, unsigned char *output)

Function pointer to encrypt/decrypt using AES CFB128.

This function pointer has a signature equal to mbedtls_aes_crypt_cfb128.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt/decrypt operation.

  • mode – [in] Mode of AES operation (encrypt/decrypt).

  • length – [in] Length of the input/output data.

  • iv_off – [inout] Pointer to the variable holding the initialization vector offset.

  • iv – [in] Array with the initialization vector used for the encrypt/decrypt operation.

  • input – [in] Pointer to the buffer holding the input data.

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

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_crypt_cfb8_fn)(mbedtls_aes_context *ctx, int mode, size_t length, unsigned char iv[16], const unsigned char *input, unsigned char *output)

Function pointer to encrypt/decrypt using AES CFB8.

This function pointer has a signature equal to mbedtls_aes_crypt_cfb8.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt/decrypt operation.

  • mode – [in] Mode of AES operation (encrypt/decrypt).

  • length – [in] Length of the input/output data.

  • iv – [in] Array with the initialization vector used for the encrypt/decrypt operation.

  • input – [in] Pointer to the buffer holding the input data.

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

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_crypt_ofb_fn)(mbedtls_aes_context *ctx, size_t length, size_t *iv_off, unsigned char iv[16], const unsigned char *input, unsigned char *output)

Function pointer to encrypt/decrypt using AES OFB.

This function pointer has a signature equal to mbedtls_aes_crypt_ofb.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt/decrypt operation.

  • length – [in] Length of the input/output data.

  • iv_off – [inout] Pointer to the variable holding the initialization vector offset.

  • iv – [in] Array with the initialization vector used for the encrypt/decrypt operation.

  • input – [in] Pointer to the buffer holding the input data.

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

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_aes_crypt_ctr_fn)(mbedtls_aes_context *ctx, size_t length, size_t *nc_off, unsigned char nonce_counter[16], unsigned char stream_block[16], const unsigned char *input, unsigned char *output)

Function pointer to encrypt/decrypt using AES CTR.

This function pointer has a signature equal to mbedtls_aes_crypt_ctr.

Parameters

  • ctx – [inout] Pointer to the context for the encrypt/decrypt operation.

  • length – [in] Length of the input/output data.

  • nc_off – [inout] Pointer to the variable holding the nonce offset.

  • nonce_counter – [in] Array with nonce counter.

  • stream_block – [in] Array with stream block.

  • input – [in] Pointer to the buffer holding the input data.

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

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

struct mbedtls_aes_funcs
#include <backend_aes.h>

Structure type holding the AES calling interface for a backend.

The backend must provide an instance of this structure to enable mbedcrypto glue functionality. Unsupported features can be set to NULL.

Public Members

size_t backend_context_size

Size of the AES context according to the backend.

size_t backend_xts_context_size

Size of the AES XTS context according to the backend.

mbedtls_aes_check_fn check

Check for AES support in the backend.

mbedtls_aes_init_fn init

Initialize the AES context.

mbedtls_aes_free_fn free

Free the AES context.

mbedtls_aes_xts_init_fn xts_init

Initialize the AES XTS context.

mbedtls_aes_xts_free_fn xts_free

Free the AES XTS context.

mbedtls_aes_setkey_enc_fn setkey_enc

Set an AES encryption key.

mbedtls_aes_setkey_dec_fn setkey_dec

Set an AES decryption key.

mbedtls_aes_xts_setkey_enc_fn xts_setkey_enc

Set an AES XTS encryption key.

mbedtls_aes_xts_setkey_dec_fn xts_setkey_dec

Set an AES XTS decryption key.

mbedtls_internal_aes_encrypt_fn internal_encrypt

Perform AES encrypt operation.

mbedtls_internal_aes_decrypt_fn internal_decrypt

Perform AES decrypt operation.

mbedtls_aes_crypt_cbc_fn crypt_cbc

Perform AES CBC encrypt/decrypt operation.

mbedtls_aes_crypt_xts_fn crypt_xts

Perform AES XTS encrypt/decrypt operation.

mbedtls_aes_crypt_cfb128_fn crypt_cfb128

Perform AES CFB128 encrypt/decrypt operation.

mbedtls_aes_crypt_cfb8_fn crypt_cfb8

Perform AES CFB8 encrypt/decrypt operation.

mbedtls_aes_crypt_ofb_fn crypt_ofb

Perform AES OFB encrypt/decrypt operation.

mbedtls_aes_crypt_ctr_fn crypt_ctr

Perform AES CTR encrypt/decrypt operation.

mbedcrypto AES CCM glue

group mbedcrypto_glue_aes_ccm

Glue layer for mbedcrypto AES CCM APIs, including typedefs for backend API abstraction.

Defines

CC3XX_MBEDTLS_CCM_CONTEXT_WORDS

Context size of AES CCM in words in the mbed_cc3xx_mbedcrypto library.

OBERON_MBEDTLS_CCM_CONTEXT_WORDS
VANILLA_MBEDTLS_CCM_CONTEXT_WORDS

Typedefs

typedef int (*mbedtls_ccm_check_fn)(mbedtls_cipher_id_t cipher, unsigned int keybits)

Function pointer to check if the backend supports CCM, depending on the cipher and number of bits in key.

The value returned by the backend implementing this function pointer is dynamically checked. If the return value is 0, then the backend does not support the AES CCM cipher (mode, keysize etc). If the value is positive, then the backend with the highest value is selected (priority based).

Parameters

  • mode – [in] AES CCM mode.

  • keybits – [in] Key size in bits for the AES functionality.

Returns

0 if the AES CCM functionality is not supported, otherwise a priority where higher is better.

typedef void (*mbedtls_ccm_init_fn)(mbedtls_ccm_context *ctx)

Function pointer to initialize a glue AES CCM context.

This function inits or resets the glue context for an AES CCM operation. This function pointer has a signature equal to mbedtls_ccm_init.

Parameters

  • ctx – [inout] Pointer to the context to initialize.

typedef void (*mbedtls_ccm_free_fn)(mbedtls_ccm_context *ctx)

Function pointer to free a glue AES CCM context.

This function frees the glue context for an AES CCM operation. This function pointer has a signature equal to mbedtls_ccm_free.

Parameters

  • ctx – [inout] Pointer to the context to free.

typedef int (*mbedtls_ccm_setkey_fn)(mbedtls_ccm_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits)

Function pointer to set AES CCM key in a glue context.

This function pointer has a signature equal to mbedtls_ccm_setkey.

Parameters

  • ctx – [inout] Pointer to the context to set the encryption key in.

  • cipher – [in] Cipher to set (CCM or CCM*).

  • key – [in] Pointer to the array holding the encryption key.

  • keybits – [in] Key size in bits.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ccm_encrypt_and_tag_fn)(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)

Function pointer to perform an AES CCM encrypt-and-tag operation.

This function pointer has a signature equal to mbedtls_ccm_encrypt_and_tag.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • length – [in] Length of the operation.

  • iv – [in] Pointer to the array holding the initialization vector.

  • iv_len – [in] Length of the initialization vector.

  • add – [in] Pointer to the array holding optional associated data.

  • add_len – [in] Length of optional associated data.

  • input – [in] Pointer to the array holding the input.

  • output – [out] Pointer to the array to hold the output.

  • tag – [out] Pointer to the array to hold the tag.

  • tag_len – [in] Length of the tag.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ccm_star_encrypt_and_tag_fn)(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)

Function pointer to perform an AES CCM* encrypt-and-tag operation.

This function pointer has a signature equal to mbedtls_ccm_star_encrypt_and_tag.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • length – [in] Length of the operation.

  • iv – [in] Pointer to the array holding the initialization vector.

  • iv_len – [in] Length of the initialization vector.

  • add – [in] Pointer to the array holding optional associated data.

  • add_len – [in] Length of optional associated data.

  • input – [in] Pointer to the array holding the input.

  • output – [out] Pointer to the array to hold the output.

  • tag – [out] Pointer to the array to hold the tag.

  • tag_len – [in] Length of the tag.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ccm_auth_decrypt_fn)(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len)

Function pointer to perform an AES CCM decrypt operation.

This function pointer has a signature equal to mbedtls_ccm_auth_decrypt.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • length – [in] Length of the operation.

  • iv – [in] Pointer to the array holding the initialization vector.

  • iv_len – [in] Length of the initialization vector.

  • add – [in] Pointer to the array holding optional associated data.

  • add_len – [in] Length of optional associated data.

  • input – [in] Pointer to the array holding the input.

  • output – [out] Pointer to the array to hold the output.

  • tag – [in] Pointer to the array holding the tag.

  • tag_len – [in] Length of the tag.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ccm_star_auth_decrypt_fn)(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len)

Function pointer to perform an AES CCM* decrypt operation.

This function pointer has a signature equal to mbedtls_ccm_star_auth_decrypt.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • length – [in] Length of the operation.

  • iv – [in] Pointer to the array holding the initialization vector.

  • iv_len – [in] Length of the initialization vector.

  • add – [in] Pointer to the array holding optional associated data.

  • add_len – [in] Length of optional associated data.

  • input – [in] Pointer to the array holding the input.

  • output – [out] Pointer to the array to hold the output.

  • tag – [in] Pointer to the array holding the tag.

  • tag_len – [in] Length of the tag.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

struct mbedtls_ccm_funcs
#include <backend_ccm.h>

Structure type holding the AES CCM calling interface for a backend.

The backend must provide an instance of this structure to enable mbedcrypto glue functionality.

Public Members

size_t backend_context_size

Size of the AES CCM/CCM* context according to the backend.

mbedtls_ccm_check_fn check

Check for AES CCM/CCM* support.

mbedtls_ccm_init_fn init

Initialize the AES CCM/CCM* context.

mbedtls_ccm_free_fn free

Free the AES CCM/CCM* context.

mbedtls_ccm_setkey_fn setkey

Set an AES CCM/CCM* crypt key.

mbedtls_ccm_encrypt_and_tag_fn encrypt_and_tag

Perform an AES CCM encrypt-and-tag operation.

mbedtls_ccm_star_encrypt_and_tag_fn star_encrypt_and_tag

Perform an AES CCM* encrypt-and-tag operation.

mbedtls_ccm_auth_decrypt_fn auth_decrypt

Perform an AES CCM decrypt operation.

mbedtls_ccm_star_auth_decrypt_fn star_auth_decrypt

Perform an AES CCM* decrypt operation.

struct mbedtls_ccm_context
#include <ccm_alt.h>

The CCM context-type definition. The CCM context is passed to the APIs called.

Context size of AES CCM in words in standard mbed TLS.

mbedcrypto AES CCM glue context.

Public Members

union mbedtls_ccm_context._buffer buffer

Union with size of the largest enabled backend context.

void *handle

Pointer to the function table in an initialized glue context.

union _buffer
#include <ccm_alt.h>

Public Members

uint32_t buffer_vanilla_mbedtls[((sizeof(mbedtls_cipher_context_t) + 3) / 4)]

Array the size of an AES CCM context in standard mbed TLS.

uint32_t dummy

Dummy value in case no backend is enabled.

mbedcrypto DHM glue

group mbedcrypto_glue_dhm

This is a glue layer for mbedcrypto DHM APIs, including typedefs for backend API abstraction.

Typedefs

typedef int (*mbedtls_dhm_check_fn)(unsigned int pbits)

Function pointer to check if the backend supports DHM given size of a private key.

The value returned by the backend implementing this function pointer is dynamically checked. If the return value is 0, then the backend does not support the DHM mode. If the value is positive, then the backend with the highest value is selected (priority based).

Parameters

  • pbits – [in] Private key bit size.

Returns

0 if the DHM functionality is not supported, otherwise a priority where higher is better.

typedef void (*mbedtls_dhm_init_fn)(mbedtls_dhm_context *ctx)

Function pointer to initialize a glue DHM context.

This function inits or resets the glue context for an DHM operation. This function pointer has a signature equal to mbedtls_dhm_init.

Parameters

  • ctx – [inout] Pointer to the context to initialize.

typedef int (*mbedtls_dhm_read_params_fn)(mbedtls_dhm_context *ctx, unsigned char **p, const unsigned char *end)

Function pointer to read DHM parameters from a server exchange.

This function pointer has a signature equal to mbedtls_dhm_read_params.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • p – [inout] Sets pointer to end of data on input, start of the input buffer, and on output.

  • end – [in] Pointer to the end of the input buffer.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_dhm_make_params_fn)(mbedtls_dhm_context *ctx, int x_size, unsigned char *output, size_t *olen, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to generate DHM key pair exported to TLS format.

This function pointer has a signature equal to mbedtls_dhm_make_params.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • x_size – [in] Private key size in bytes.

  • output – [out] Pointer to the destination buffer.

  • olen – [out] Pointer to the variable to write the output length.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_dhm_set_group_fn)(mbedtls_dhm_context *ctx, const mbedtls_mpi *P, const mbedtls_mpi *G)

Function pointer to set prime modulus and generator in a DHM context.

This function pointer has a signature equal to mbedtls_dhm_set_group.

Parameters

  • ctx – [inout] Pointer to the context to set the prime modulus and generator.

  • P – [in] Pointer to the MPI holding an initialized DHM prime modulus.

  • G – [in] Pointer to the MPI holding an initialized DHM generator.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_dhm_read_public_fn)(mbedtls_dhm_context *ctx, const unsigned char *input, size_t ilen)

Function pointer to import raw public value of a peer in DHM context.

This function pointer has a signature equal to mbedtls_dhm_read_public.

Note

The DHM context must already be initialized and have DHM parameters set.

Parameters

  • ctx – [inout] Pointer to the context to set the public value.

  • input – [in] Pointer to the input buffer containing the G^Y value of the peer.

  • ilen – [in] Size of the input buffer in bytes.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_dhm_make_public_fn)(mbedtls_dhm_context *ctx, int x_size, unsigned char *output, size_t olen, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to create a DHM key pair and export the raw public key in big-endian format.

This function pointer has a signature equal to mbedtls_dhm_make_public.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • x_size – [in] Private key in bytes.

  • output – [out] Pointer to the array to hold the output.

  • olen – [out] Pointer to a variable to write the output length.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_dhm_calc_secret_fn)(mbedtls_dhm_context *ctx, unsigned char *output, size_t output_size, size_t *olen, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to derive and export the shared secret.

This function pointer has a signature equal to mbedtls_dhm_calc_secret.

Parameters

  • ctx – [inout] Pointer to an initialized context with private key generated and public key imported.

  • output – [out] Pointer to the array to hold the output.

  • output_size – [in] Size of the destination buffer.

  • olen – [out] Pointer to the variable to write the output length.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef void (*mbedtls_dhm_free_fn)(mbedtls_dhm_context *ctx)

Function pointer to free a glue DHM context.

This function frees the glue context for a DHM operation. This function pointer has a signature equal to mbedtls_dhm_free.

Parameters

  • ctx – [inout] DHM context to free.

typedef int (*mbedtls_dhm_parse_dhm_fn)(mbedtls_dhm_context *dhm, const unsigned char *dhmin, size_t dhminlen)

Function pointer to parse DHM parameters in PEM or DER format.

This function pointer has a signature equal to mbedtls_dhm_parse_dhm.

Parameters

  • ctx – [inout] Pointer to the context for the operation.

  • dhmin – [in] Pointer to the array holding the input.

  • dhminlen – [in] Size of the input buffer including null termination.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_dhm_parse_dhmfile_fn)(mbedtls_dhm_context *dhm, const char *path)

Function pointer to parse DHM parameters from a file.

This function pointer has a signature equal to mbedtls_dhm_parse_dhmfile.

Parameters

  • ctx – [inout] Pointer to the context for the operation. param[in] path Path of the file to read DHM parameters from.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

struct mbedtls_dhm_funcs
#include <backend_dhm.h>

Structure type holding the CMAC calling interface for a backend.

The backend must provide an instance of this structure to enable mbedcrypto glue functionality.

Public Members

mbedtls_dhm_check_fn check

Check for DHM support in the backend.

mbedtls_dhm_init_fn init

Initialize the DHM context.

mbedtls_dhm_read_params_fn read_params

Read DHM parameters.

mbedtls_dhm_make_params_fn make_params

Make DHM parameters.

mbedtls_dhm_set_group_fn set_group

Set DHM group.

mbedtls_dhm_read_public_fn read_public

Read DHM public key.

mbedtls_dhm_make_public_fn make_public

Make DHM public key.

mbedtls_dhm_calc_secret_fn calc_secret

Calculate a shared secret.

mbedtls_dhm_free_fn free

Free DHM context.

mbedtls_dhm_parse_dhm_fn parse_dhm

Parse DHM parameters from PEM/DER.

struct mbedtls_dhm_context
#include <dhm_alt.h>

mbedcrypto DHM glue context.

Note

The context must be compatible with the original mbed TLS context, because other mbed TLS APIs are using internal fields of this context. Additional types in this context is added at the end.

Public Members

size_t len

Size of P in bytes.

mbedtls_mpi P

The prime modulus.

mbedtls_mpi G

The generator.

mbedtls_mpi X

The local secret value.

mbedtls_mpi GX

The X component of the remote public key.

mbedtls_mpi GY

The Y component of the remote public key.

mbedtls_mpi K

The shared secret.

mbedtls_mpi RP

The cached value of R^2 mod P.

mbedtls_mpi Vi

The blinding value.

mbedtls_mpi Vf

The unblinding value.

mbedtls_mpi pX

The previous X.

void *handle

Pointer to the function table in an initialized glue context.

mbedcrypto ECDH glue

group mbedcrypto_glue_ecdh

Glue layer for mbedcrypto ECDH APIs, including typedefs for backend API abstraction.

Defines

MBEDTLS_ECDH_GEN_PUBLIC_FUNCTION

Macro definition to identify an ECDH generate public functionality.

MBEDTLS_ECDH_COMPUTE_SHARED_FUNCTION

Macro definition to identify an ECDH compute shared secret functionality.

Typedefs

typedef int (*mbedtls_ecdh_check_fn)(mbedtls_ecp_group *grp, int function)

Function pointer to check if the backend supports ECDH, depending on the given ECP group.

The value returned by the backend implementing this function pointer is dynamically checked. If the return value is 0, then the backend does not support the ECC curve. If the value is positive, then the backend with the highest value is selected (priority based).

Parameters

  • grp – [in] ECP group.

  • function – [in] Reserved type, currently not in use.

Returns

0 if the ECDH functionality is not supported, otherwise a priority where higher is better.

typedef int (*mbedtls_ecdh_gen_public_fn)(mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to generate an ECDH key pair.

This function pointer has a signature equal to mbedtls_ecdh_gen_public.

Parameters

  • grp – [in] Pointer to the MPI of the ECP group.

  • d – [out] Pointer to the destination MPI for private key. Must be initialized.

  • Q – [out] Pointer to the destination public key. Must be initialized.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ecdh_compute_shared_fn)(mbedtls_ecp_group *grp, mbedtls_mpi *z, const mbedtls_ecp_point *Q, const mbedtls_mpi *d, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to generate an ECDH shared secret.

This function pointer has a signature equal to mbedtls_ecdh_compute_shared.

Note

Note that f_rng may be NULL if randomization of intermediate result is not needed.

Parameters

  • grp – [in] Pointer to the MPI of the ECP group.

  • z – [out] Pointer to the destination MPI for shared secret. Must be initialized.

  • Q – [in] Pointer to a public key from another party. Must be initialized.

  • d – [in] Pointer to a local private key. Must be initialized.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

struct mbedtls_ecdh_funcs
#include <backend_ecdh.h>

Structure type holding the ECDH calling interface for a backend.

The backend must provide an instance of this structure to enable mbedcrypto glue functionality.

Public Members

mbedtls_ecdh_check_fn check

Check for ECDH support in the backend.

mbedtls_ecdh_gen_public_fn gen_public

Generate ECDH key pair.

mbedtls_ecdh_compute_shared_fn compute_shared

Calculate ECDH shared secret.

mbedcrypto ECDSA glue

group mbedcrypto_glue_ecdsa

Glue layer for mbedcrypto ECDSA APIs, including typedefs for backend API abstraction.

Defines

MBEDTLS_ECDSA_SIGN_FUNCTION

Macro definition to identify an ECDSA sign function.

MBEDTLS_ECDSA_VERIFY_FUNCTION

Macro definition to identify an ECDSA verify function.

MBEDTLS_ECDSA_GENKEY_FUNCTION

Macro definition to identify an ECDSA generate key pair function.

Typedefs

typedef int (*mbedtls_ecdsa_check_fn)(mbedtls_ecp_group *grp, mbedtls_ecp_group_id gid, int function)

Function pointer to check if the backend supports ECDSA, depending on the given group and curve type.

The value returned by the backend implementing this function pointer is dynamically checked. If the return value is 0, then the backend does not support the ECC curve. If the value is positive, then the backend with the highest value is selected (priority based).

Parameters

  • grp – [in] ECP group. If NULL, gid is used instead.

  • gid – [in] Curve type, might be overridden by grp.

  • function – [in] Reserved type, currently not in use.

Returns

0 if the ECDSA functionality is not supported, otherwise a priority where higher is better.

typedef int (*mbedtls_ecdsa_sign_fn)(mbedtls_ecp_group *grp, mbedtls_mpi *r, mbedtls_mpi *s, const mbedtls_mpi *d, const unsigned char *buf, size_t blen, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to sign a hash using ECDSA.

This function pointer has a signature equal to mbedtls_ecdsa_sign.

Parameters

  • grp – [in] Pointer to an ECP group.

  • r – [out] Pointer to the MPI context to store the first part of the signature. Must be initialized.

  • s – [out] Pointer to the MPI context to store the second part of the signature. Must be initialized.

  • buf – [in] Pointer to the buffer holding the hash to be signed.

  • blen – [in] Length of the buffer to sign.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ecdsa_verify_fn)(mbedtls_ecp_group *grp, const unsigned char *buf, size_t blen, const mbedtls_ecp_point *Q, const mbedtls_mpi *r, const mbedtls_mpi *s)

Function pointer to verify a hash using ECDSA.

This function pointer has a signature equal to mbedtls_ecdsa_verify.

Parameters

  • grp – [in] Pointer to an ECP group.

  • buf – [in] Pointer to the buffer holding the hash to be verified.

  • blen – [in] Length of the buffer to verify.

  • Q – [in] Pointer to the ECP point used for verification (the public key).

  • r – [in] Pointer to the MPI holding the first part of the signature. Must be initialized.

  • s – [in] Pointer to the MPI holding the second part of the signature. Must be initialized.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_ecdsa_genkey_fn)(mbedtls_ecdsa_context *ctx, mbedtls_ecp_group_id gid, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, )

Function pointer to generate an ECDSA key pair.

This function pointer has a signature equal to mbedtls_ecdsa_genkey.

Parameters

  • ctx – [inout] Pointer to the ECDSA context to store the keypair in. Must be initialized.

  • gid – [in] Curve type.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

struct mbedtls_ecdsa_funcs
#include <backend_ecdsa.h>

Typedef for structure type holding the ECDSA calling interface for a backend.

The backend must provide an instance of this structure to enable mbedcrypto glue functionality.

Public Members

mbedtls_ecdsa_check_fn check

Check for ECDSA support in the backend.

mbedtls_ecdsa_sign_fn sign

Create a signature using ECDSA.

mbedtls_ecdsa_verify_fn verify

Verify a signature using ECDSA.

mbedtls_ecdsa_genkey_fn genkey

Generate ECDSA key pair.

mbedcrypto RSA glue

group mbedcrypto_glue_rsa

Glue layer for mbedcrypto RSA APIs, including typedefs for backend API abstraction.

Defines

CC3XX_MBEDTLS_RSA_CONTEXT_WORDS

Context size in words in nrf_cc3xx_mbedcrypto library in words.

VANILLA_MBEDTLS_RSA_CONTEXT_WORDS

Context size in words in standard mbed TLS in words.

Typedefs

typedef int (*mbedtls_rsa_check_fn)(int padding, int hash_id, unsigned int nbits)

Function pointer to check if the backend support RSA given padding type, hash-id and modulus bit size.

The value returned by the backend implementing this function pointer is dynamically checked. If the return value is 0, then the backend does not support the RSA cipher. If the value is positive, then the backend with the highest value is selected (priority based).

Parameters

  • padding – [in] Reserved type, currently not in use.

  • hash_id – [in] Reserved type, currently not in use.

  • nbits – [in] Modulus bit size.

Returns

0 if the RSA functionality is not supported, otherwise a priority where higher is better.

typedef void (*mbedtls_rsa_init_fn)(mbedtls_rsa_context *ctx, int padding, int hash_id)

Function pointer to initialize an mbedcrypto glue RSA context.

This function inits or resets the glue context for an RSA operation. This function pointer has a signature equal to mbedtls_rsa_init.

Parameters

  • ctx – [inout] Pointer to the context to initialize.

  • padding – [in] Either MBEDTLS_RSA_PKCS_V21 or MBEDTLS_RSA_PKCS_V15.

  • hash_id – [in] Hash identifier.

typedef int (*mbedtls_rsa_import_fn)(mbedtls_rsa_context *ctx, const mbedtls_mpi *N, const mbedtls_mpi *P, const mbedtls_mpi *Q, const mbedtls_mpi *D, const mbedtls_mpi *E)

Function pointer to import core RSA parameters into a glue RSA context.

This function pointer has a signature equal to mbedtls_rsa_import.

Parameters

  • ctx – [inout] Pointer to the context. Must be initialized.

  • N – [in] Pointer to the RSA modulus. May be NULL.

  • P – [in] Pointer to the first RSA prime factor. May be NULL.

  • Q – [in] Pointer to the second RSA prime factor. May be NULL.

  • D – [in] Pointer to the private exponent. May be NULL.

  • E – [in] Pointer to the public exponent. May be NULL.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_import_raw_fn)(mbedtls_rsa_context *ctx, unsigned char const *N, size_t N_len, unsigned char const *P, size_t P_len, unsigned char const *Q, size_t Q_len, unsigned char const *D, size_t D_len, unsigned char const *E, size_t E_len)

Function pointer to import core RSA parameters into a glue RSA context.

This function pointer has a signature equal to mbedtls_rsa_import_raw.

Note

The raw input is expected to be in big-endian format.

Parameters

  • ctx – [inout] Pointer to the context. Must be initialized.

  • N – [in] Pointer to the array holding the RSA modulus. May be NULL.

  • N_len – [in] The length of N. Ignored if N is NULL.

  • P – [in] Pointer to the array holding the first RSA prime factor. May be NULL.

  • P_len – [in] The length of P. Ignored if P is NULL.

  • Q – [in] Pointer to the array holding the second RSA prime factor. May be NULL.

  • Q_len – [in] The length of Q. Ignored if Q is NULL.

  • D – [in] Pointer to the array holding the private exponent. May be NULL.

  • D_len – [in] The length of D. Ignored if D is NULL.

  • E – [in] Pointer to the array holding the public exponent. May be NULL.

  • E_len – [in] The length of E. Ignored if E is NULL.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_complete_fn)(mbedtls_rsa_context *ctx)

Function pointer to complete an RSA context from a set of imported core parameters.

This function pointer has a signature equal to mbedtls_rsa_complete.

Parameters

  • ctx – [inout] The RSA context that is initialized and holds the imported parameters.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_export_fn)(const mbedtls_rsa_context *ctx, mbedtls_mpi *N, mbedtls_mpi *P, mbedtls_mpi *Q, mbedtls_mpi *D, mbedtls_mpi *E)

Function pointer to export an RSA context.

This function pointer has a signature equal to mbedtls_rsa_export.

Parameters

  • ctx – [in] Pointer to the context that is initialized and holds the core parameters.

  • N – [out] Pointer to an MPI to hold the RSA modulus, or NULL if not to export.

  • P – [out] Pointer to an MPI to hold the first prime factor, or NULL if not to export.

  • Q – [out] Pointer to an MPI to hold the second prime factor, or NULL if not to export.

  • D – [out] Pointer to an MPI to hold the private exponent, or NULL if not to export.

  • Q – [out] Pointer to an MPI to hold the public exponent, or NULL if not to export.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_export_raw_fn)(const mbedtls_rsa_context *ctx, unsigned char *N, size_t N_len, unsigned char *P, size_t P_len, unsigned char *Q, size_t Q_len, unsigned char *D, size_t D_len, unsigned char *E, size_t E_len)

Function pointer to export an RSA context to raw form.

This function pointer has a signature equal to mbedtls_rsa_export_raw.

Note

The raw output is in big-endian format.

Parameters

  • ctx – [in] Pointer to the context that is initialized and holds the core parameters.

  • N – [out] Pointer to an array to hold the RSA modulus, or NULL if not to export.

  • N_len – [out] The length of N. Ignored if N is NULL.

  • P – [out] Pointer to an array to hold the first prime factor, or NULL if not to export.

  • P_len – [out] The length of P. Ignored if P is NULL.

  • Q – [out] Pointer to an array to hold the second prime factor, or NULL if not to export.

  • Q_len – [out] The length of Q. Ignored if Q is NULL.

  • D – [out] Pointer to an array to hold the private exponent, or NULL if not to export.

  • D_len – [out] The length of D. Ignored if D is NULL.

  • E – [out] Pointer to an array to hold the public exponent, or NULL if not to export.

  • E_len – [out] The length of E. Ignored if E is NULL.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_export_crt_fn)(const mbedtls_rsa_context *ctx, mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP)

Function pointer to export RSA CRT parameters of a private RSA key.

This function pointer has a signature equal to mbedtls_rsa_export_crt.

Parameters

  • ctx – [in] Pointer to the context that is initialized and holds the core parameters.

  • DP – [out] Pointer to an MPI to hold D modulo P-1, or NULL if not to export.

  • DQ – [out] Pointer to an MPI to hold D modulo Q-1, or NULL if not to export.

  • QP – [out] Pointer to an MPI to hold modular inverse of Q modulo P, or NULL if not to export.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef void (*mbedtls_rsa_set_padding_fn)(mbedtls_rsa_context *ctx, int padding, int hash_id)

Function pointer to set RSA padding and hash type.

This function pointer has a signature equal to mbedtls_rsa_set_padding.

Parameters

  • ctx – [inout] Pointer to the context to update.

  • padding – [in] Either MBEDTLS_RSA_PKCS_V21 or MBEDTLS_RSA_PKCS_V15.

  • hash_id – [in] Hash identifier.

typedef size_t (*mbedtls_rsa_get_len_fn)(const mbedtls_rsa_context *ctx)

Function pointer to get the length of the RSA modulus in bytes.

This function pointer has a signature equal to mbedtls_rsa_get_len.

Parameters

  • ctx – [in] Pointer to the context. Must be initialized and configured.

Returns

Length of the RSA modulus in bytes.

typedef int (*mbedtls_rsa_gen_key_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, unsigned int nbits, int exponent, )

Function pointer to generate an RSA key.

This function pointer has a signature equal to mbedtls_rsa_gen_key.

Parameters

  • ctx – [inout] Pointer to an initialized context used to hold the private key after the call.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • nbits – [in] The size of the public key in bits.

  • exponent – [in] The public exponent for use (for example, 65537).

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_check_pubkey_fn)(const mbedtls_rsa_context *ctx)

Function pointer to check if an RSA context contains a public key.

A successful check of this function means that the context can be used for RSA public key operations.

This function pointer has a signature equal to mbedtls_rsa_check_pubkey.

Parameters

  • ctx – [in] Pointer to an initialized context to check.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_check_privkey_fn)(const mbedtls_rsa_context *ctx)

Function pointer to check if an RSA context contains a private key.

This function pointer has a signature equal to mbedtls_rsa_check_privkey.

Parameters

  • ctx – [in] Pointer to an initialized context to check.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_check_pub_priv_fn)(const mbedtls_rsa_context *pub, const mbedtls_rsa_context *prv)

Function pointer to check an RSA public/private key pair.

This function pointer has a signature equal to mbedtls_rsa_check_pub_priv.

Parameters

  • pub – [in] Pointer to a context holding an RSA public key.

  • priv – [in] Pointer to a context holding an RSA private key.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_public_fn)(mbedtls_rsa_context *ctx, const unsigned char *input, unsigned char *output)

Function pointer to perform an RSA public key operation.

This function pointer has a signature equal to mbedtls_rsa_public.

Note

The size of the input and output buffer must correspond to ctx->len bytes. For 2048-bit RSA, this means 256 bytes.

Parameters

  • ctx – [in] Pointer to an initialized context.

  • input – [in] Pointer to the buffer holding the input.

  • output – [out] Pointer to the buffer to hold the output.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_private_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, const unsigned char *input, unsigned char *output, )

Function pointer to perform an RSA private key operation.

This function pointer has a signature equal to mbedtls_rsa_private.

Note

The size of the input and output buffers must correspond to ctx->len bytes. For 2048-bit RSA, this means 256 bytes.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • input – [in] Pointer to the buffer holding the input.

  • output – [out] Pointer to the buffer to hold the output.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_pkcs1_encrypt_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, size_t ilen, const unsigned char *input, unsigned char *output, )

Function pointer to perform PKCS#1 encryption.

This function pointer has a signature equal to mbedtls_rsa_pkcs1_encrypt.

Note

The size of the input and output buffers must correspond to ctx->len bytes. For 2048-bit RSA, this means 256 bytes.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • input – [in] Pointer to the buffer holding the input.

  • output – [out] Pointer to the buffer to hold the output.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsaes_pkcs1_v15_encrypt_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, size_t ilen, const unsigned char *input, unsigned char *output, )

Function pointer to perform PKCS#1 v1.5 encryption.

This function pointer has a signature equal to mbedtls_rsa_rsaes_pkcs1_v15_encrypt.

Note

The size of the output buffer must correspond to ctx->len bytes. For 2048-bit RSA, this means 256 bytes.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • ilen – [in] Length of the plain text in bytes.

  • input – [in] Pointer to the buffer holding the input in plain text.

  • output – [out] Pointer to the buffer to hold the encrypted output.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsaes_oaep_encrypt_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, const unsigned char *label, size_t label_len, size_t ilen, const unsigned char *input, unsigned char *output, )

Function pointer to perform PKCS1 v2.1 encryption (RSAES OAEP).

This function pointer has a signature equal to mbedtls_rsa_rsaes_oaep_encrypt.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • label – [in] Buffer holding the custom label to use, or NULL if not used.

  • label_len – [in] Length of the label. Skipped if label is NULL.

  • ilen – [in] Length of the plain text in bytes.

  • input – [in] Pointer to the buffer holding the input in plain text.

  • output – [out] Pointer to the buffer to hold the encrypted output.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_pkcs1_decrypt_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len, )

Function pointer to perform PKCS#1 decryption.

This function pointer has a signature equal to mbedtls_rsa_pkcs1_decrypt.

Note

This function removes message padding. The output buffer should be ctx->len in size (for example, 256 bytes for 2048-bit RSA).

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • olen – [out] Pointer to the variable to hold the length of the decrypted plain text in bytes.

  • input – [in] Pointer to the buffer holding the input in encrypted form.

  • output – [out] Pointer to the buffer to hold the output in plain text.

  • output_max_len – [in] Max length available to hold the decrypted plain text.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsaes_pkcs1_v15_decrypt_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len, )

Function pointer to perform PKCS#1 v1.5 decryption.

This function pointer has a signature equal to mbedtls_rsa_rsaes_pkcs1_v15_decrypt.

Note

The output buffer should be ctx->len in size (for example, 256 bytes for 2048-bit RSA).

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • olen – [out] Pointer to the variable to hold the length of the decrypted plain text in bytes.

  • input – [in] Pointer to the buffer holding the input in encrypted form.

  • output – [out] Pointer to the buffer to hold the output in plain text.

  • output_max_len – [in] Max length available to hold the decrypted plain text.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsaes_oaep_decrypt_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, const unsigned char *label, size_t label_len, size_t *olen, const unsigned char *input, unsigned char *output, size_t output_max_len, )

Function pointer to perform PKCS#1 v2.1 decryption (RSAES OAEP).

This function pointer has a signature equal to mbedtls_rsa_rsaes_oaep_decrypt.

Note

The output buffer should be ctx->len in size (for example, 256 bytes for 2048-bit RSA).

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • label – [in] Buffer holding the custom label to use, or NULL if not used.

  • label_len – [in] Length of the label. Set to 0 if custom label is not used.

  • olen – [in] Pointer to the variable holding the length of the decrypted plain text in bytes.

  • input – [in] Pointer to the buffer holding the input in encrypted form.

  • output – [out] Pointer to the buffer to hold the output in plain text.

  • output_max_len – [in] Max length available to hold the decrypted plain text.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_pkcs1_sign_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig, )

Function pointer to perform PKCS#1 signature generation.

This function pointer has a signature equal to mbedtls_rsa_pkcs1_sign.

Note

The signature buffer should be ctx->len in size (for example, 256 bytes for 2048-bit RSA).

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • sig – [out] Pointer to the buffer to hold the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsassa_pkcs1_v15_sign_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig, )

Function pointer to perform PKCS#1 v1.5 signature generation.

This function pointer has a signature equal to mbedtls_rsa_rsaassa_pkcs1_v15_sign.

Note

The signature buffer should be ctx->len in size (for example, 256 bytes for 2048-bit RSA)

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • sig – [out] Pointer to the buffer to hold the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsassa_pss_sign_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, unsigned char *sig, )

Function pointer to perform PKCS#1 v2.1 signature generation (RSA-PSS).

This function pointer has a signature equal to mbedtls_rsa_rsassa_pss_sign.

Note

The signature buffer should be ctx->len in size (for example, 256 bytes for 2048-bit RSA).

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • sig – [out] Pointer to the buffer to hold the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_pkcs1_verify_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, const unsigned char *sig, )

Function pointer to perform PKCS#1 signature verification.

This function pointer has a signature equal to mbedtls_rsa_pkcs1_verify.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • sig – [in] Pointer to the buffer holding the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsassa_pkcs1_v15_verify_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, const unsigned char *sig, )

Function pointer to perform PKCS#1 v1.5 signature verification.

This function pointer has a signature equal to mbedtls_rsa_rsassa_pkcs1_v15_verify.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • sig – [in] Pointer to the buffer holding the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsassa_pss_verify_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, const unsigned char *sig, )

Function pointer to perform PKCS#1 v2.1 signature verification (RSA-PSS).

This function pointer has a signature equal to mbedtls_rsa_rsassa_pss_verify.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • sig – [in] Pointer to the buffer holding the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_rsassa_pss_verify_ext_fn)(mbedtls_rsa_context *ctx, int (*f_rng)(void*, unsigned char*, size_t), void *p_rng, int mode, mbedtls_md_type_t md_alg, unsigned int hashlen, const unsigned char *hash, mbedtls_md_type_t mgf1_hash_id, int expected_salt_len, const unsigned char *sig, )

Function pointer to perform PKCS#1 v2.1 signature verification (RSA-PSS extended features).

This function pointer has a signature equal to mbedtls_rsa_rsassa_pss_verify.

Parameters

  • ctx – [in] Pointer to an initialized RSA context.

  • f_rng – [in] RNG function.

  • p_rng – [inout] RNG context.

  • mode – [in] Mode of operation.

  • md_alg – [in] Message digest algorithm used to hash the data.

  • hashlen – [in] Length of the message digest.

  • hash – [in] Pointer to the buffer holding the digest or raw data (if MBEDTLS_MD_NONE is used).

  • mgf1_hash_id – [in] Message digest used for mask generation.

  • expected_salt_len – [in] Length of the salt used in padding or MBEDTLS_RSA_SALT_LEN_ANY to accept all lengths.

  • sig – [out] Pointer to the buffer holding the signature.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef int (*mbedtls_rsa_copy_fn)(mbedtls_rsa_context *dst, const mbedtls_rsa_context *src)

Function pointer to copy between two RSA contexts (clone).

This function pointer has a signature equal to mbedtls_rsa_copy.

Parameters

  • dst – [out] Initialized destination context.

  • src – [in] Initialized source context to clone.

Returns

0 if operation was successful, otherwise a negative value corresponding to the error.

typedef void (*mbedtls_rsa_free_fn)(mbedtls_rsa_context *ctx)

Function pointer to free an RSA context.

This function pointer has a signature equal to mbedtls_rsa_free.

param[in,out] ctx Pointer to the context to free.

struct mbedtls_rsa_funcs
#include <backend_rsa.h>

Structure type holding the RSA calling interface for a backend.

The backend must provide an instance of this structure to enable mbedcrypto glue functionality.

Public Members

size_t backend_context_size

Size of the context according to the backend.

mbedtls_rsa_check_fn check

Check for RSA support in the backend.

mbedtls_rsa_init_fn init

Initialize an RSA context.

mbedtls_rsa_import_fn import

Import core RSA parameters.

mbedtls_rsa_import_raw_fn import_raw

Import raw core RSA parameters.

mbedtls_rsa_complete_fn complete

Complete an RSA context from imported parameters.

mbedtls_rsa_export_fn export_fn

Export RSA context parameters.

mbedtls_rsa_export_raw_fn export_raw

Export RSA context parameters into raw buffers.

mbedtls_rsa_export_crt_fn export_crt

Export RSA context CRT parameters.

mbedtls_rsa_set_padding_fn set_padding

Set RSA padding and hash type.

mbedtls_rsa_get_len_fn get_len

Get the length of the RSA modulus in bytes.

mbedtls_rsa_gen_key_fn gen_key

Generate an RSA key.

mbedtls_rsa_check_pubkey_fn check_pubkey

Check if RSA context contains a public key.

mbedtls_rsa_check_privkey_fn check_privkey

Check if the RSA context contains a private key.

mbedtls_rsa_check_pub_priv_fn check_pub_priv

Check an RSA private/public key pair.

mbedtls_rsa_public_fn do_public

Perform an RSA public key operation.

mbedtls_rsa_private_fn do_private

Perform an RSA private key operation.

mbedtls_rsa_pkcs1_encrypt_fn pkcs1_encrypt

Perform PKCS#1 encryption.

mbedtls_rsa_rsaes_pkcs1_v15_encrypt_fn rsaes_pkcs1_v15_encrypt

Perform PKCS#1 v1.5 encryption.

mbedtls_rsa_rsaes_oaep_encrypt_fn rsaes_oaep_encrypt

Perform PKCS#1 v2.1 encryption (RSAES OEAP).

mbedtls_rsa_pkcs1_decrypt_fn pkcs1_decrypt

Perform PKCS#1 decryption.

mbedtls_rsa_rsaes_pkcs1_v15_decrypt_fn rsaes_pkcs1_v15_decrypt

Perform PKCS#1 v1.5 decryption.

mbedtls_rsa_rsaes_oaep_decrypt_fn rsaes_oaep_decrypt

Perform PKCS#1 v2.1 decryption (RSAES OAEP).

mbedtls_rsa_pkcs1_sign_fn pkcs1_sign

Perform PKCS#1 signature generation.

mbedtls_rsa_rsassa_pkcs1_v15_sign_fn rsassa_pkcs1_v15_sign

Perform PKCS#1 v1.5 signature generation.

mbedtls_rsa_rsassa_pss_sign_fn rsassa_pss_sign

Perform PKCS#1 v2.1 signature generation (RSASSA PSS).

mbedtls_rsa_pkcs1_verify_fn pkcs1_verify

Perform a PKCS#1 verify operation.

mbedtls_rsa_rsassa_pkcs1_v15_verify_fn rsassa_pkcs1_v15_verify

Perform a PKCS#1 v1.5 verify operation.

mbedtls_rsa_rsassa_pss_verify_fn rsassa_pss_verify

Perform a PKCS#1 v2.1 verify operation (RSASSA PSS).

mbedtls_rsa_rsassa_pss_verify_ext_fn rsassa_pss_verify_ext

Perform PKCS#1 v2.1 verify operation (RSASSA PSS, extended functionality).

mbedtls_rsa_copy_fn copy

Copy an RSA context (clone).

mbedtls_rsa_free_fn free

Free an RSA context.

struct mbedtls_rsa_context
#include <rsa_alt.h>

The RSA context structure.

Typedef for the mbed TLS RSA glue context.

Note

Direct manipulation of the members of this structure is deprecated. All manipulation should instead be done through the public interface functions.

Public Members

int ver

always 0

size_t len

size(N) in chars

mbedtls_mpi N

public modulus

mbedtls_mpi E

public exponent

mbedtls_mpi D

private exponent

mbedtls_mpi P

1st prime factor

mbedtls_mpi Q

2nd prime factor

mbedtls_mpi DP

D % (P - 1)

mbedtls_mpi DQ

D % (Q - 1)

mbedtls_mpi QP

1 / (Q % P)

mbedtls_mpi RN

cached R^2 mod N

mbedtls_mpi RP

cached R^2 mod P

mbedtls_mpi RQ

cached R^2 mod Q

mbedtls_mpi Vi

cached blinding value

mbedtls_mpi Vf

cached un-blinding value

int padding

The padding mode for the RSA operations.

MBEDTLS_RSA_PKCS_V15 for 1.5 padding and MBEDTLS_RSA_PKCS_v21 for OAEP/PSS

int hash_id

The hash digest algorithm used for RSA operations.

Hash identifier of mbedtls_md_type_t as specified in the mbedtls_md.h header file for the EME-OAEP and EMSA-PSS encoding

mbedtls_threading_mutex_t mutex

Thread-safety mutex

mbedtls_mpi NP

Barrett mod N tag NP for N-modulus

mbedtls_mpi BQP

Barrett mod Q tag QP for Q-factor

mbedtls_mpi BPP

Barrett mod P tag PP for P-factor

void *handle

Pointer to the function table in an initialized glue context.

union mbedtls_rsa_context._buffer buffer

Union with size of the largest enabled backend context.

union _buffer
#include <rsa_alt.h>

Public Members

uint32_t buffer_vanilla_mbedtls[(43)]

Array the size of an RSA context in standard mbed TLS.

uint32_t dummy

Dummy value in case no backend is enabled.