nRF5 SDK v17.0.2
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
Elliptic Curve Cryptography Key Management

Provides elliptic curve cryptography API for public and private key management. More...

Modules

 Definitions specific to secp160r1 (NIST 160-bit)
 
 Definitions specific to secp160r2 (NIST 160-bit)
 
 Definitions specific to secp192r1 (NIST 192-bit)
 
 Definitions specific to secp224r1 (NIST 224-bit)
 
 Definitions specific to secp256r1 (NIST 256-bit)
 
 Definitions specific to secp384r1 (NIST 384-bit)
 
 Definitions specific to secp521r1 (NIST 521-bit)
 
 Definitions specific to secp160k1 (Koblitz 160-bit)
 
 Definitions specific to secp192k1 (Koblitz 192-bit)
 
 Definitions specific to secp224k1 (Koblitz 224-bit)
 
 Definitions specific to secp256k1 (Koblitz 256-bit)
 
 Definitions specific to bp256r1 (Brainpool 256-bit)
 
 Definitions specific to bp384r1 (Brainpool 384-bit)
 
 Definitions specific to bp512r1 (Brainpool 512-bit)
 
 Definitions specific to Curve25519
 
 Definitions specific to Ed25519
 

Data Structures

struct  nrf_crypto_ecc_curve_info_s
 Structure holding information on a specific curve. More...
 
union  nrf_crypto_ecc_key_pair_generate_context_t
 Union holding a context for a key pair generation. More...
 
union  nrf_crypto_ecc_public_key_calculate_context_t
 Union holding a context for a public key calculation. More...
 
union  nrf_crypto_ecc_private_key_t
 Union holding representation of a private key for any curve type. More...
 
union  nrf_crypto_ecc_public_key_t
 Union holding representation of a public key for any curve type. More...
 

Macros

#define NRF_CRYPTO_ECC_RAW_PRIVATE_KEY_MAX_SIZE   NRF_CRYPTO_BACKEND_ECC_RAW_PRIVATE_KEY_MAX_SIZE
 Maximum size of a raw private key for all enabled curves.
 
#define NRF_CRYPTO_ECC_RAW_PUBLIC_KEY_MAX_SIZE   NRF_CRYPTO_BACKEND_ECC_RAW_PUBLIC_KEY_MAX_SIZE
 Maximum size of a raw public key for all enabled curves.
 

Typedefs

typedef struct
nrf_crypto_ecc_curve_info_s 
nrf_crypto_ecc_curve_info_t
 Structure holding information on a specific curve. More...
 
typedef uint8_t nrf_crypto_ecc_raw_private_key_t [NRF_CRYPTO_BACKEND_ECC_RAW_PRIVATE_KEY_MAX_SIZE]
 Type big enough to hold a raw private key for any the enabled curves.
 
typedef uint8_t nrf_crypto_ecc_raw_public_key_t [NRF_CRYPTO_BACKEND_ECC_RAW_PUBLIC_KEY_MAX_SIZE]
 Type big enough to hold a raw public key for any the enabled curves.
 

Enumerations

enum  nrf_crypto_ecc_curve_type_t {
  NRF_CRYPTO_ECC_SECP160R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP160R2_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP192R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP224R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP256R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP384R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP521R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP160K1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP192K1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP224K1_CURVE_TYPE,
  NRF_CRYPTO_ECC_SECP256K1_CURVE_TYPE,
  NRF_CRYPTO_ECC_BP256R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_BP384R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_BP512R1_CURVE_TYPE,
  NRF_CRYPTO_ECC_CURVE25519_CURVE_TYPE,
  NRF_CRYPTO_ECC_ED25519_CURVE_TYPE
}
 Defines type of ECC curve. More...
 

Functions

ret_code_t nrf_crypto_ecc_key_pair_generate (nrf_crypto_ecc_key_pair_generate_context_t *p_context, nrf_crypto_ecc_curve_info_t const *p_curve_info, nrf_crypto_ecc_private_key_t *p_private_key, nrf_crypto_ecc_public_key_t *p_public_key)
 Generate a new pair of a public key and a private key. More...
 
ret_code_t nrf_crypto_ecc_public_key_calculate (nrf_crypto_ecc_public_key_calculate_context_t *p_context, nrf_crypto_ecc_private_key_t const *p_private_key, nrf_crypto_ecc_public_key_t *p_public_key)
 Calculate public key associated with provided private key. More...
 
ret_code_t nrf_crypto_ecc_private_key_from_raw (nrf_crypto_ecc_curve_info_t const *p_curve_info, nrf_crypto_ecc_private_key_t *p_private_key, uint8_t const *p_raw_data, size_t raw_data_size)
 Create a private key from a raw data. More...
 
ret_code_t nrf_crypto_ecc_private_key_to_raw (nrf_crypto_ecc_private_key_t const *p_private_key, uint8_t *p_raw_data, size_t *p_raw_data_size)
 Convert a private key to a raw data. More...
 
ret_code_t nrf_crypto_ecc_public_key_from_raw (nrf_crypto_ecc_curve_info_t const *p_curve_info, nrf_crypto_ecc_public_key_t *p_public_key, uint8_t const *p_raw_data, size_t raw_data_size)
 Create a public key from a raw data. More...
 
ret_code_t nrf_crypto_ecc_public_key_to_raw (nrf_crypto_ecc_public_key_t const *p_public_key, uint8_t *p_raw_data, size_t *p_raw_data_size)
 Convert a public key to a raw data. More...
 
ret_code_t nrf_crypto_ecc_private_key_free (nrf_crypto_ecc_private_key_t *p_private_key)
 Release resources taken by a private key. More...
 
ret_code_t nrf_crypto_ecc_public_key_free (nrf_crypto_ecc_public_key_t *p_public_key)
 Release resources taken by a public key. More...
 
ret_code_t nrf_crypto_ecc_curve_info_get (void const *p_key, nrf_crypto_ecc_curve_info_t const **pp_curve_info)
 Gets curve information structure from provided key (private or public). More...
 
ret_code_t nrf_crypto_ecc_byte_order_invert (nrf_crypto_ecc_curve_info_t const *p_curve_info, uint8_t const *p_raw_input, uint8_t *p_raw_output, size_t raw_data_size)
 Inverts byte order of a big integers contained in a raw data. More...
 

Detailed Description

Provides elliptic curve cryptography API for public and private key management.

Typedef Documentation

Structure holding information on a specific curve.

Note
This structure cannot be used to create a new variable. Only the variables defined by this library can be used, e.g. g_nrf_crypto_ecc_secp256r1_curve_info.

Enumeration Type Documentation

Defines type of ECC curve.

Enumerator
NRF_CRYPTO_ECC_SECP160R1_CURVE_TYPE 

secp160r1 (NIST 160-bit)

NRF_CRYPTO_ECC_SECP160R2_CURVE_TYPE 

secp160r2 (NIST 160-bit)

NRF_CRYPTO_ECC_SECP192R1_CURVE_TYPE 

secp192r1 (NIST 192-bit)

NRF_CRYPTO_ECC_SECP224R1_CURVE_TYPE 

secp224r1 (NIST 224-bit)

NRF_CRYPTO_ECC_SECP256R1_CURVE_TYPE 

secp256r1 (NIST 256-bit)

NRF_CRYPTO_ECC_SECP384R1_CURVE_TYPE 

secp384r1 (NIST 384-bit)

NRF_CRYPTO_ECC_SECP521R1_CURVE_TYPE 

secp521r1 (NIST 521-bit)

NRF_CRYPTO_ECC_SECP160K1_CURVE_TYPE 

secp160k1 (Koblitz 160-bit)

NRF_CRYPTO_ECC_SECP192K1_CURVE_TYPE 

secp192k1 (Koblitz 192-bit)

NRF_CRYPTO_ECC_SECP224K1_CURVE_TYPE 

secp224k1 (Koblitz 224-bit)

NRF_CRYPTO_ECC_SECP256K1_CURVE_TYPE 

secp256k1 (Koblitz 256-bit)

NRF_CRYPTO_ECC_BP256R1_CURVE_TYPE 

bp256r1 (Brainpool 256-bit)

NRF_CRYPTO_ECC_BP384R1_CURVE_TYPE 

bp384r1 (Brainpool 384-bit)

NRF_CRYPTO_ECC_BP512R1_CURVE_TYPE 

bp512r1 (Brainpool 512-bit)

NRF_CRYPTO_ECC_CURVE25519_CURVE_TYPE 

Curve25519

NRF_CRYPTO_ECC_ED25519_CURVE_TYPE 

Ed25519

Function Documentation

ret_code_t nrf_crypto_ecc_byte_order_invert ( nrf_crypto_ecc_curve_info_t const *  p_curve_info,
uint8_t const *  p_raw_input,
uint8_t *  p_raw_output,
size_t  raw_data_size 
)

Inverts byte order of a big integers contained in a raw data.

All the ECC API accepts only data with big endian integers, so this function have to be used if little endian is required. If input is in little endian byte order it will be converted to big endian. If input is in big endian byte order it will be converted to little endian. It works for ECC raw private key, raw public key, signature and shared secret. If raw data contains two big integers (e.g. R, S, or X, Y) each integer is inverted separately. If p_curve_info is NULL then all bytes in buffer will be inverted regardless what is the content of the buffer.

Parameters
[in]p_curve_infoPointer to information on selected curve. Use only global variables defined by nrf_crypto, e.g. g_nrf_crypto_ecc_secp256r1_curve_info.
[in]p_raw_inputPointer to buffer holding source data.
[out]p_raw_outputPointer to buffer that will be filled with inverted byte order. This parameter can be the same as p_raw_input, otherwise the buffers cannot overlap.
[in]raw_data_sizeSize of input and output buffer.
ret_code_t nrf_crypto_ecc_curve_info_get ( void const *  p_key,
nrf_crypto_ecc_curve_info_t const **  pp_curve_info 
)

Gets curve information structure from provided key (private or public).

Parameters
[in]p_keyPointer to structure holding private or public key.
[out]pp_curve_infoPointer to location where put retrieved pointer to curve information structure.
ret_code_t nrf_crypto_ecc_key_pair_generate ( nrf_crypto_ecc_key_pair_generate_context_t p_context,
nrf_crypto_ecc_curve_info_t const *  p_curve_info,
nrf_crypto_ecc_private_key_t p_private_key,
nrf_crypto_ecc_public_key_t p_public_key 
)

Generate a new pair of a public key and a private key.

Generated keys have to deallocated using nrf_crypto_ecc_private_key_free and nrf_crypto_ecc_public_key_free.

Parameters
[in]p_contextPointer to temporary structure holding context information. If it is NULL, necessary data will be allocated with NRF_CRYPTO_ALLOC and freed at the end of the function.
[in]p_curve_infoPointer to information on selected curve. Use only global variables defined by nrf_crypto, e.g. g_nrf_crypto_ecc_secp256r1_curve_info.
[out]p_private_keyPointer to structure where newly generated private key will be put.
[out]p_public_keyPointer to structure where newly generated public key will be put.
ret_code_t nrf_crypto_ecc_private_key_free ( nrf_crypto_ecc_private_key_t p_private_key)

Release resources taken by a private key.

Parameters
[in]p_private_keyPointer to structure holding private key to release.
ret_code_t nrf_crypto_ecc_private_key_from_raw ( nrf_crypto_ecc_curve_info_t const *  p_curve_info,
nrf_crypto_ecc_private_key_t p_private_key,
uint8_t const *  p_raw_data,
size_t  raw_data_size 
)

Create a private key from a raw data.

Generated private key has to be deallocated using nrf_crypto_ecc_private_key_free.

Note
Ed25519 only: Memory is allocated internally using Dynamic memory management module.
Parameters
[in]p_curve_infoPointer to information on selected curve. Use only global variables defined by nrf_crypto, e.g. g_nrf_crypto_ecc_secp256r1_curve_info.
[out]p_private_keyPointer to structure where newly converted private key will be put.
[in]p_raw_dataPointer to buffer containing a big endian raw data.
[in]raw_data_sizeNumber of bytes of a raw data. Correct size for selected curve can be found in p_curve_info and it is also defined by the preprocessor definitions, e.g. NRF_CRYPTO_ECC_SECP256R1_RAW_PRIVATE_KEY_SIZE.
ret_code_t nrf_crypto_ecc_private_key_to_raw ( nrf_crypto_ecc_private_key_t const *  p_private_key,
uint8_t *  p_raw_data,
size_t *  p_raw_data_size 
)

Convert a private key to a raw data.

Parameters
[in]p_private_keyPointer to structure holding private key that will be convert.
[out]p_raw_dataPointer to buffer containing a big endian raw data.
[in,out]p_raw_data_sizeMaximum number of bytes that p_raw_data buffer can hold on input and the actual number of bytes used by the raw data on output. Actual size for selected curve can be found in nrf_crypto_ecc_curve_info_t and it is also defined by the preprocessor definitions, e.g. NRF_CRYPTO_ECC_SECP256R1_RAW_PRIVATE_KEY_SIZE.
ret_code_t nrf_crypto_ecc_public_key_calculate ( nrf_crypto_ecc_public_key_calculate_context_t p_context,
nrf_crypto_ecc_private_key_t const *  p_private_key,
nrf_crypto_ecc_public_key_t p_public_key 
)

Calculate public key associated with provided private key.

Calculated public key has to be deallocated using nrf_crypto_ecc_public_key_free.

Parameters
[in]p_contextPointer to temporary structure holding context information. If it is NULL, necessary data will be allocated with NRF_CRYPTO_ALLOC and freed at the end of the function.
[in]p_private_keyPointer to structure holding a private key that will be used for computation.
[out]p_public_keyPointer to structure where newly generated public key will be put.
ret_code_t nrf_crypto_ecc_public_key_free ( nrf_crypto_ecc_public_key_t p_public_key)

Release resources taken by a public key.

Parameters
[in]p_public_keyPointer to structure holding public key to release.
ret_code_t nrf_crypto_ecc_public_key_from_raw ( nrf_crypto_ecc_curve_info_t const *  p_curve_info,
nrf_crypto_ecc_public_key_t p_public_key,
uint8_t const *  p_raw_data,
size_t  raw_data_size 
)

Create a public key from a raw data.

Generated public key has to be deallocated using nrf_crypto_ecc_public_key_free.

Parameters
[in]p_curve_infoPointer to information on selected curve. Use only global variables defined by nrf_crypto, e.g. g_nrf_crypto_ecc_secp256r1_curve_info.
[out]p_public_keyPointer to structure where newly converted public key will be put.
[in]p_raw_dataPointer to buffer containing a big endian raw data.
[in]raw_data_sizeNumber of bytes of a raw data. Correct size for selected curve can be found in p_curve_info and it is also defined by the preprocessor definitions, e.g. NRF_CRYPTO_ECC_SECP256R1_RAW_PUBLIC_KEY_SIZE.
ret_code_t nrf_crypto_ecc_public_key_to_raw ( nrf_crypto_ecc_public_key_t const *  p_public_key,
uint8_t *  p_raw_data,
size_t *  p_raw_data_size 
)

Convert a public key to a raw data.

Parameters
[in]p_public_keyPointer to structure holding public key that will be convert.
[out]p_raw_dataPointer to buffer containing a big endian raw data.
[in,out]p_raw_data_sizeMaximum number of bytes that p_raw_data buffer can hold on input and the actual number of bytes used by the raw data on output. Actual size for selected curve can be found in nrf_crypto_ecc_curve_info_t and it is also defined by the preprocessor definitions, e.g. NRF_CRYPTO_ECC_SECP256R1_RAW_PUBLIC_KEY_SIZE.

Documentation feedback | Developer Zone | Subscribe | Updated