ECC key handling functions.

nRF5 SDK v13.1.0
Macros | Functions

Provides functions to allocate, free, generate and convert ECC key types. More...

Macros

#define NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE (type)   ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE_, type))
Internal macro to calculate size required to hold a ECC private key given curve type(domain), according to the used nrf_crypto backend. More...
#define NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE (type)   ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE_, type))
Internal macro to calculate size required to hold a ECC public key given curve type(domain), according to the used nrf_crypto backend. More...
#define NRF_CRYPTO_ECC_PRIVATE_KEY_CREATE (name, type)
Macro to create an instance of an ECC private key given name and type. More...
#define NRF_CRYPTO_ECC_PUBLIC_KEY_CREATE (name, type)
Macro to create an instance of an ECC public key by a given name and type. More...
#define NRF_CRYPTO_ECC_PRIVATE_RAW_KEY_SIZE (type)   ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE_, type))
Internal macro to calculate size required to hold a ECC private key in raw format given curve type(domain), according to the used nrf_crypto backend. More...
#define NRF_CRYPTO_ECC_PUBLIC_RAW_KEY_SIZE (type)   ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE_, type))
Internal macro to calculate size required to hold a ECC public key in raw representatio given curve type(domain), according to the used nrf_crypto backend. More...
#define NRF_CRYPTO_ECC_PRIVATE_KEY_RAW_CREATE (name, type)
Macro to create an instance of a raw representation of an ECC private key given name and type. More...
#define NRF_CRYPTO_ECC_PRIVATE_KEY_RAW_CREATE_FROM_ARRAY (name, type, input)
Macro to create a value length structure to represent a raw ECC private key by a given name, type and an uint8_t array buffer to hold the raw private key. If the input is not of the correct size a static assert will be occur compile-time. More...
#define NRF_CRYPTO_ECC_PUBLIC_KEY_RAW_CREATE (name, type)
Macro to create an instance of a araw representation of an ECC public key given name and type. More...
#define NRF_CRYPTO_ECC_PUBLIC_KEY_RAW_CREATE_FROM_ARRAY (name, type, input)
Macro to create an instance of an ECC public key by a given name, type and array input. If the input is not of the correct size a static assert will be occur compile-time. More...

Functions

uint32_t nrf_crypto_ecc_private_key_size_get ( nrf_ecc_curve_type_t curve_type, uint32_t *p_key_size)
Function to get the private key size given curve_type. More...
uint32_t nrf_crypto_ecc_public_key_size_get ( nrf_ecc_curve_type_t curve_type, uint32_t *p_key_size)
Function to get the public key size given curve_type. More...
uint32_t nrf_crypto_ecc_private_key_allocate ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t *p_private_key, nrf_value_length_t const *p_raw_key)
Function to allocate dynamic memory for holding a ECC private key. More...
uint32_t nrf_crypto_ecc_private_key_free ( nrf_value_length_t *p_private_key)
Function to free allocated memory for ECC private key. More...
uint32_t nrf_crypto_ecc_public_key_allocate ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t *p_public_key, nrf_value_length_t const *p_raw_key)
Function to allocate dynamic memory for holdign a ECC public key. More...
uint32_t nrf_crypto_ecc_public_key_free ( nrf_value_length_t *p_public_key)
Function to free allocated memory for ECC private key. More...
uint32_t nrf_crypto_ecc_key_pair_generate ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t *p_private_key, nrf_value_length_t *p_public_key)
Function to generate ECC private public keypair given curve type. More...
uint32_t nrf_crypto_ecc_public_key_calculate ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t const *p_private_key, nrf_value_length_t *p_public_key)
Function to calculate ECC public key given a ECC private key as input. More...
uint32_t nrf_crypto_ecc_private_key_to_raw ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t const *p_private_key, nrf_value_length_t *p_private_key_raw)
Function to convert ECC private key to a raw representation for use in external APIs. More...
uint32_t nrf_crypto_ecc_public_key_to_raw ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t const *p_public_key, nrf_value_length_t *p_public_key_raw)
Function to convert ECC public key to a raw representation for use in external APIs. More...
uint32_t nrf_crypto_ecc_public_key_from_raw ( nrf_crypto_curve_info_t curve_info, nrf_value_length_t *p_public_key_raw, nrf_value_length_t *p_public_key)
Function to convert ECC public key from a raw representation for use in nrf_crypto API. More...

Detailed Description

Provides functions to allocate, free, generate and convert ECC key types.

Macro Definition Documentation

#define NRF_CRYPTO_ECC_PRIVATE_KEY_CREATE ( name,
type
)
Value:
__ALIGN(4) static uint8_t \
name ## _buffer[NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE(type)]; \
nrf_value_length_t name = \
{ \
.p_value = name ## _buffer, \
.length = NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE(type) \
}

Macro to create an instance of an ECC private key given name and type.

Note
This creates the value length structure used for Nordic APIs with a buffer to hold the actual ECC private key data. The ECC private key type is opaque and the size and format of the data is dependant on the nrf_crypto backend.
To convert this key to a raw representation required for external APIS, please use the function nrf_crypto_ecc_public_key_to_raw . This may not be supported by all nrf_crypto backends.
Parameters
[in] name Name of the ECC private key instance.
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PRIVATE_KEY_RAW_CREATE ( name,
type
)
Value:
__ALIGN(4) static uint8_t \
name ## _buffer[NRF_CRYPTO_ECC_PRIVATE_RAW_KEY_SIZE(type)]; \
nrf_value_length_t name = \
{ \
.p_value = name ## _buffer, \
.length = NRF_CRYPTO_ECC_PRIVATE_RAW_KEY_SIZE(type) \
}

Macro to create an instance of a raw representation of an ECC private key given name and type.

Note
This creates the value length structure used for external APIs that require an aligned version of a private key where curve-domain and endianness is described elsewhere.
Warning
The raw private key can not be used directly in the nrf_crypto APIs.
The output of this macro is subject to change.
Parameters
[in] name Name of the ECC private key instance.
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PRIVATE_KEY_RAW_CREATE_FROM_ARRAY ( name,
type,
input
)
Value:
STATIC_ASSERT ( sizeof (input) == NRF_CRYPTO_ECC_PRIVATE_RAW_KEY_SIZE (type)) \
static nrf_value_length_t name = \
{ \
.p_value = (uint8_t*)input, \
.length = NRF_CRYPTO_ECC_PRIVATE_RAW_KEY_SIZE (type) \
}

Macro to create a value length structure to represent a raw ECC private key by a given name, type and an uint8_t array buffer to hold the raw private key. If the input is not of the correct size a static assert will be occur compile-time.

Note
This creates the value length structure used for external APIs that require an aligned version of a private key where curve-domain and endianness is described elsewhere.
The value length pair generated by running this macro can be used as input in the function nrf_crypto_ecc_private_key_to_raw to hold a raw private key type.
Warning
There is no API function to convert private key from a raw representation in the nrf_crypto CryptoCell (cc310) backend. Running this macro while nrf_crypto CryptoCell backend is enabled will cause a static assertion.
Parameters
[in] name Name of the ECC private key instance.
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
[in] input Array holding the private key.
#define NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE ( type ) ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE_, type))

Internal macro to calculate size required to hold a ECC private key given curve type(domain), according to the used nrf_crypto backend.

Warning
The size representation by running this macro is described by the memory requirements of the nrf_crypto backend. This size does not correspond to the size required to hold a raw key.
Parameters
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PRIVATE_RAW_KEY_SIZE ( type ) ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PRIVATE_KEY_SIZE_, type))

Internal macro to calculate size required to hold a ECC private key in raw format given curve type(domain), according to the used nrf_crypto backend.

Warning
The size representation by running this macro is described by the memory requirements of the nrf_crypto backend. This size does not correspond to the size required to hold a raw key.
Parameters
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PUBLIC_KEY_CREATE ( name,
type
)
Value:
__ALIGN(4) static uint8_t \
name ## _buffer[NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE(type)]; \
nrf_value_length_t name = \
{ \
.p_value = name ## _buffer, \
.length = NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE(type) \
}

Macro to create an instance of an ECC public key by a given name and type.

Note
This creates the value length structure used for Nordic APIs with a buffer to hold the actual ECC public key data. The ECC public key type is opaque and the size and format of the data is dependant on the nrf_crypto backend.
To convert this key to a raw representation required for external APIS, please use the function nrf_crypto_ecc_public_key_to_raw . This may not be supported by all nrf_crypto backends.
Parameters
[in] name Name of the ECC PUBLIC key instance.
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PUBLIC_KEY_RAW_CREATE ( name,
type
)
Value:
__ALIGN(4) static uint8_t \
name ## _buffer[NRF_CRYPTO_ECC_PUBLIC_RAW_KEY_SIZE(type)]; \
nrf_value_length_t name = \
{ \
.p_value = name ## _buffer, \
.length = NRF_CRYPTO_ECC_PUBLIC_RAW_KEY_SIZE(type) \
}

Macro to create an instance of a araw representation of an ECC public key given name and type.

Note
This creates the value length structure used for external APIs that require an aligned version of a public key where curve-domain and endianness is described elsewhere.

�*

Note
The value length pair generated by running this macro can be used as input in the function nrf_crypto_ecc_public_key_to_raw to hold a raw private key type.
Parameters
[in] name Name of the ECC PUBLIC key instance.
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PUBLIC_KEY_RAW_CREATE_FROM_ARRAY ( name,
type,
input
)
Value:
STATIC_ASSERT ( sizeof (input) == NRF_CRYPTO_ECC_PUBLIC_RAW_KEY_SIZE (type)); \
static nrf_value_length_t name = \
{ \
.p_value = (uint8_t*)input, \
.length = NRF_CRYPTO_ECC_PUBLIC_RAW_KEY_SIZE (type) \
}

Macro to create an instance of an ECC public key by a given name, type and array input. If the input is not of the correct size a static assert will be occur compile-time.

Note
This creates the value length structure used for external APIs that require an aligned version of a private key where curve-domain and endianness is described elsewhere.
The value length pair generated by running this macro can be used as input in the function nrf_crypto_ecc_private_key_to_raw to hold a raw public key type.
Parameters
[in] name Name of the ECC PUBLIC key instance.
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
[in] input Array of data used as the buffer.
#define NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE ( type ) ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE_, type))

Internal macro to calculate size required to hold a ECC public key given curve type(domain), according to the used nrf_crypto backend.

Warning
The size representation by running this macro is described by the memory requirements of the nrf_crypto backend. This size does not correspond to the size required to hold a raw key.
Parameters
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.
#define NRF_CRYPTO_ECC_PUBLIC_RAW_KEY_SIZE ( type ) ( STRING_CONCATENATE (NRF_CRYPTO_ECC_PUBLIC_KEY_SIZE_, type))

Internal macro to calculate size required to hold a ECC public key in raw representatio given curve type(domain), according to the used nrf_crypto backend.

Warning
The size representation by running this macro is described by the memory requirements of the nrf_crypto backend. This size does not correspond to the size required to hold a raw key.
Parameters
[in] type Curve type. Either SECP192R1, SECP224R1, SECP256R1, SECP384R1, SECP521R1, SECP192K1, SECP224K1, or SECP256K1.

Function Documentation

uint32_t nrf_crypto_ecc_key_pair_generate ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t * p_private_key ,
nrf_value_length_t * p_public_key
)

Function to generate ECC private public keypair given curve type.

Note
This function will not allocate any memory. Private and public keys given as input must be pointing to previously allocated memory.
This function needs RNG functionality. See NRF_CRYPTO_SUPPORTS_RNG for the nrf_crypto backends that require external source of RNG data.
Parameters
[in] curve_info Curve type used for key pair generation.
[in,out] p_private_key Pointer to a value length structure to hold a private key.
[in,out] p_public_key Pointer to a value length structure to hold a public key.
Return values
NRF_SUCCESS The ECC key pair was generated successfully.
NRF_ERROR_INVALID_STATE If the function was called when nrf_crypto was uninitialized.
NRF_ERROR_NULL If the any of the parameters was NULL.
NRF_ERROR_INVALID_ADDR If any of the provided pointers are invalid.
NRF_ERROR_INVALID_LENGTH If the key pair size is different to the provided buffers.
NRF_ERROR_NOT_SUPPORTED If the key pair generation is not supported for the given curve type.
NRF_ERROR_INTERNAL Unexpected error. Possibly because NRF_CRYPTO_SUPPORTS_RNG is 0.
uint32_t nrf_crypto_ecc_private_key_allocate ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t * p_private_key ,
nrf_value_length_t const * p_raw_key
)

Function to allocate dynamic memory for holding a ECC private key.

Note
Memory dynamically allocated by calling this function will be aligned to a uint32_t address.
Parameters
[in] curve_info Curve type used for ECC private key.
[in,out] p_private_key Pointer to a value length structure to hold a private key.
[in] p_raw_key Pointer to value length structure holding raw representation of a private key taken as input. If this is set to NULL, no initialization will take place.
Return values
NRF_SUCCESS If memory for the private key was successfully allocated.
NRF_ERROR_NULL If p_private_key was NULL.
Any other error code reported by the memory manager.
uint32_t nrf_crypto_ecc_private_key_free ( nrf_value_length_t * p_private_key )

Function to free allocated memory for ECC private key.

Note
Memory dynamically allocated by calling this function will be aligned to a uint32_t address.
Parameters
[in] p_private_key Pointer to structure holdign
Return values
NRF_SUCCESS if memory for the private key was successfully freed.
NRF_ERROR_NULL If p_private_key was NULL.
Any other error code reported by the memory manager.
uint32_t nrf_crypto_ecc_private_key_size_get ( nrf_ecc_curve_type_t curve_type ,
uint32_t * p_key_size
)

Function to get the private key size given curve_type.

Parameters
[in] curve_type Curve type to get private key size for.
[in,out] p_key_size Pointer to variable to hold the private key size.
Return values
NRF_SUCCESS If the private key size was successfully found.
NRF_ERROR_NULL If the p_key_size was NULL.
NRF_ERROR_NOT_SUPPORTED If the curve type was not supported.
uint32_t nrf_crypto_ecc_private_key_to_raw ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t const * p_private_key ,
nrf_value_length_t * p_private_key_raw
)

Function to convert ECC private key to a raw representation for use in external APIs.

Note
This function will not allocate any memory. The raw public key given as output parameter must be pointing to previously allocated memory.
The format of the data for the converted ECC public key must be aligned and will use the least amount of space required to represent the key.
Warning
The nrf_crypto backend may not support converting a private key to a raw representation. This is subject to change.
Parameters
[in] curve_info Info of the curve type (domain) and the endianness of the resulting raw key.
[in] p_private_key Value length structure holding a private key to be converted to a raw representation.
[in,out] p_private_key_raw Value length structure to hold the converted private key.
Return values
NRF_SUCCESS If the private key was converted to raw representation.
NRF_ERROR_INVALID_STATE If the function was called when nrf_crypto was uninitialized.
NRF_ERROR_NULL If the any of the parameters was NULL.
NRF_ERROR_INVALID_ADDR If any of the provided pointers are invalid.
NRF_ERROR_INVALID_LENGTH If the size of the public key and result is invalid.
NRF_ERROR_NOT_SUPPORTED If the selected curve is not supported.
NRF_ERROR_INVALID_DATA If the private key was deemed invalid by the nrf_crypto backend.
NRF_ERROR_INTERNAL If an internal error occured in the nrf_crypto backend.
uint32_t nrf_crypto_ecc_public_key_allocate ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t * p_public_key ,
nrf_value_length_t const * p_raw_key
)

Function to allocate dynamic memory for holdign a ECC public key.

Parameters
[in] curve_info Curve type used for ECC public key.
[in,out] p_public_key Pointer to a value length structure to hold a public key.
[in] p_raw_key Pointer to value length structure holding raw representation of a public key taken as input. If this is set to NULL, no initialization will take place.
Return values
NRF_SUCCESS If memory for the public key was successfully allocated.
NRF_ERROR_NULL If p_public_key was NULL.
Any other error code reported by the memory manager.
uint32_t nrf_crypto_ecc_public_key_calculate ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t const * p_private_key ,
nrf_value_length_t * p_public_key
)

Function to calculate ECC public key given a ECC private key as input.

Note
This function will not allocate any memory. The public key given as input must be pointing to previously allocated memory.
Parameters
[in] curve_info Curve type used for public key.
[in] p_private_key Pointer to a value length structure holding a private key.
[in,out] p_public_key Pointer to a value length structure to hold the calculated key.
Return values
NRF_SUCCESS If the public key was calculated successfully.
NRF_ERROR_INVALID_STATE If the function was called when nrf_crypto was uninitialized.
NRF_ERROR_NULL If the any of the parameters was NULL.
NRF_ERROR_INVALID_ADDR If any of the provided pointers are invalid.
NRF_ERROR_INVALID_LENGTH If the key pair size is different to the provided buffers.
NRF_ERROR_NOT_SUPPORTED If the public key calculation is not supported.
uint32_t nrf_crypto_ecc_public_key_free ( nrf_value_length_t * p_public_key )

Function to free allocated memory for ECC private key.

Parameters
[in] p_public_key Pointer to value length structure holding public key to free.
Return values
NRF_SUCCESS If memory for the public key was successfully freed.
NRF_ERROR_NULL If p_public_key was NULL.
Any other error code reported by the memory manager.
uint32_t nrf_crypto_ecc_public_key_from_raw ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t * p_public_key_raw ,
nrf_value_length_t * p_public_key
)

Function to convert ECC public key from a raw representation for use in nrf_crypto API.

Note
This function will not allocate any memory. The public key given as output parameter must be pointing to previously allocated memory. The format of the data for the converted ECC public key must be aligned and will use the least amount of space required to represent the key.
Parameters
[in] curve_info Info of the curve type (domain) and the endianness of the raw public key given as input.
[in] p_public_key_raw Value length structure to hold the converted public key.
[in,out] p_public_key Value length structure holding a private key to be converted to a raw representation.
Return values
NRF_SUCCESS If the public key was converted fron raw representation.
NRF_ERROR_INVALID_STATE If the function was called when nrf_crypto was uninitialized.
NRF_ERROR_NULL If the any of the parameters was NULL.
NRF_ERROR_INVALID_ADDR If any of the provided pointers are invalid.
NRF_ERROR_NOT_SUPPORTED If the selected curve is not supported.
NRF_ERROR_INVALID_LENGTH If the size of the public key and result is invalid.
NRF_ERROR_INVALID_DATA If the public key was deemed invalid by the nrf_crypto backend.
NRF_ERROR_INTERNAL If an internal error occured in the nrf_crypto backend.
uint32_t nrf_crypto_ecc_public_key_size_get ( nrf_ecc_curve_type_t curve_type ,
uint32_t * p_key_size
)

Function to get the public key size given curve_type.

Parameters
[in] curve_type Curve type to get public key size for.
[in,out] p_key_size Pointer to variable to hold the public key size.
Return values
NRF_SUCCESS If the public key size was successfully found.
NRF_ERROR_NULL If the p_key_size was NULL.
NRF_ERROR_NOT_SUPPORTED If the curve type was not supported.
uint32_t nrf_crypto_ecc_public_key_to_raw ( nrf_crypto_curve_info_t curve_info ,
nrf_value_length_t const * p_public_key ,
nrf_value_length_t * p_public_key_raw
)

Function to convert ECC public key to a raw representation for use in external APIs.

Note
This function will not allocate any memory. The raw public key given as output parameter must be pointing to previously allocated memory. The format of the data for the converted ECC public key must be aligned and will use the least amount of space required to represent the key.
Parameters
[in] curve_info Info of the curve type (domain) and the endianness of the resulting raw key.
[in] p_public_key Value length structure holding a public key to be converted to a raw representation.
[in,out] p_public_key_raw Value length structure to hold the converted public key.
Return values
NRF_SUCCESS If the public key was converted to raw representation.
NRF_ERROR_INVALID_STATE If the function was called when nrf_crypto was uninitialized.
NRF_ERROR_NULL If the any of the parameters was NULL.
NRF_ERROR_INVALID_ADDR If any of the provided pointers are invalid.
NRF_ERROR_INVALID_LENGTH If the size of the public key and result is invalid.
NRF_ERROR_NOT_SUPPORTED If the selected curve is not supported.
NRF_ERROR_INVALID_DATA If the public key was deemed invalid by the nrf_crypto backend.
NRF_ERROR_INTERNAL If an internal error occured in the nrf_crypto backend.