Infineon OPTIGA(TM) Trust X util module APIs

nRF5 SDK v17.1.0
Macros | Typedefs | Enumerations | Functions

Infineon OPTIGA(TM) Trust X util module APIs. More...

Macros

#define ECDSA_RS_MAX_ASN1_OVERHEAD ((2 + 1) * 2)
Maximum overhead of the ASN.1 encoding for the R and S components as concatenated DER INTEGERs.
#define ECDSA_SIGNATURE_MAX_ASN1_OVERHEAD ( ECDSA_RS_MAX_ASN1_OVERHEAD + 2)
Maximum overhead of the ASN.1 encoding for the R and S components as SEQUENCE of INTEGERs.
#define INT_LIB_OK 0x75AB1C02
Requested operation completed without any error.
#define INT_LIB_NULL_PARAM 0x80002001
Null parameter(s)
#define INT_LIB_INVALID_RESPONSE ( INT_LIB_NULL_PARAM + 1)
Invalid data in response.
#define INT_LIB_INVALID_AC ( INT_LIB_NULL_PARAM + 2)
Invalid access condition.
#define INT_LIB_ZEROLEN_ERROR ( INT_LIB_NULL_PARAM + 3)
Length of input is zero.
#define INT_LIB_INVALID_PARAM ( INT_LIB_NULL_PARAM + 4)
Invalid or unsupported parameter(s)
#define INT_LIB_INVALID_LENGTH ( INT_LIB_NULL_PARAM + 5)
Invalid Length.
#define INT_LIB_MALLOC_FAILURE ( INT_LIB_NULL_PARAM + 6)
Malloc Failures.
#define INT_LIB_ERROR 0xFE5A5502
General error.
#define OPTIGA_UTIL_WRITE_ONLY (0x00)
Option to only write the data object.
#define OPTIGA_UTIL_ERASE_AND_WRITE (0x40)
Option to erase and write the data object.
#define OPTIGA_UTIL_SUCCESS (0x0000)
OPTIGA util API execution is successful. More...
#define OPTIGA_UTIL_BUSY (0x0001)
OPTIGA util module in busy state.
#define OPTIGA_UTIL_ERROR (0x0302)
OPTIGA util API failed.
#define OPTIGA_UTIL_ERROR_INVALID_INPUT (0x0303)
OPTIGA util API called with invalid inputs.
#define OPTIGA_UTIL_ERROR_MEMORY_INSUFFICIENT (0x0304)
OPTIGA util API called with insufficient memory buffer.
#define OPTIGA_UTIL_ERROR_INSTANCE_IN_USE (0x0305)
OPTIGA util API called when, a request of same instance is already in service.

Typedefs

typedef enum eOID_d eOID_d
Typedef for OIDs.

Enumerations

enum eOID_d {
eLCS_G = 0xE0C0,
eSECURITY_STATUS_G = 0xE0C1,
eCOPROCESSOR_UID = 0xE0C2,
eSLEEP_MODE_ACTIVATION_DELAY = 0xE0C3,
eCURRENT_LIMITATION = 0xE0C4,
eSECURITY_EVENT_COUNTER = 0xE0C5,
eDEVICE_PUBKEY_CERT_IFX = 0xE0E0,
eDEVICE_PUBKEY_CERT_PRJSPC_1 = 0xE0E1,
eDEVICE_PUBKEY_CERT_PRJSPC_2 = 0xE0E2,
eDEVICE_PUBKEY_CERT_PRJSPC_3 = 0xE0E3,
eFIRST_DEVICE_PRIKEY_1 = 0xE0F0,
eFIRST_DEVICE_PRIKEY_2 = 0xE0F1,
eFIRST_DEVICE_PRIKEY_3 = 0xE0F2,
eFIRST_DEVICE_PRIKEY_4 = 0xE0F3,
eLCS_A = 0xF1C0,
eSECURITY_STATUS_A = 0xF1C1,
eERROR_CODES = 0xF1C2
}
Typedef for OIDs. More...

Functions

bool ecdsa_rs_to_asn1_integers (const uint8_t *r, const uint8_t *s, size_t rs_len, uint8_t *asn_sig, size_t *asn_sig_len)
Encodes the ECDSA signature components (r, s) as two concatenated ASN.1 INTEGERs. This is the format the OPTIGA hostcode expects. More...
bool ecdsa_rs_to_asn1_signature (const uint8_t *r, const uint8_t *s, size_t rs_len, uint8_t *asn_sig, size_t *asn_sig_len)
Encodes the ECDSA signature components (r, s) as ASN.1 SEQUENCE of two INTEGERs. This is the format mbedTLS and OpenSSL use. More...
bool asn1_to_ecdsa_rs (const uint8_t *asn1, size_t asn1_len, uint8_t *rs, size_t rs_len)
decodes two concatenated ASN.1 integers to the R and S components of an ECDSA signature More...
bool asn1_to_ecdsa_rs_sep (const uint8_t *asn1, size_t asn1_len, uint8_t *r, size_t *r_len, uint8_t *s, size_t *s_len)
decodes two concatenated ASN.1 integers to the R and S components of an ECDSA signature with separate buffers for R and S More...
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_open_application ( optiga_comms_t *p_comms)
Initializes the communication with optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_read_data (uint16_t optiga_oid, uint16_t offset, uint8_t *buffer, uint16_t *bytes_to_read)
Reads data from optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_read_metadata (uint16_t optiga_oid, uint8_t *buffer, uint16_t *bytes_to_read)
Reads metadata of a data object from optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_write_data (uint16_t optiga_oid, uint8_t write_type, uint16_t offset, uint8_t *buffer, uint16_t bytes_to_write)
Writes data to optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_write_metadata (uint16_t optiga_oid, uint8_t *buffer, uint8_t bytes_to_write)
Writes metadata for the user provided data object. More...

Detailed Description

Infineon OPTIGA(TM) Trust X util module APIs.

Macro Definition Documentation

#define OPTIGA_UTIL_SUCCESS   (0x0000)

OPTIGA util API execution is successful.

OPTIGA util module return values

Enumeration Type Documentation

enum eOID_d

Typedef for OIDs.

Enumerator
eLCS_G

Global Life Cycle State.

eSECURITY_STATUS_G

Global Security Status.

eCOPROCESSOR_UID

Coprocessor UID.

eSLEEP_MODE_ACTIVATION_DELAY

Global Life Cycle State.

eCURRENT_LIMITATION

Current limitation.

eSECURITY_EVENT_COUNTER

Security Event Counter.

eDEVICE_PUBKEY_CERT_IFX

Device Public Key Certificate issued by IFX.

eDEVICE_PUBKEY_CERT_PRJSPC_1

Project-Specific device Public Key Certificate.

eDEVICE_PUBKEY_CERT_PRJSPC_2

Project-Specific device Public Key Certificate.

eDEVICE_PUBKEY_CERT_PRJSPC_3

Project-Specific device Public Key Certificate.

eFIRST_DEVICE_PRIKEY_1

First Device Private Key.

eFIRST_DEVICE_PRIKEY_2

First Device Private Key.

eFIRST_DEVICE_PRIKEY_3

First Device Private Key.

eFIRST_DEVICE_PRIKEY_4

First Device Private Key.

eLCS_A

Application Life Cycle Status.

eSECURITY_STATUS_A

Application Security Status.

eERROR_CODES

Error codes.

Function Documentation

bool asn1_to_ecdsa_rs ( const uint8_t * asn1 ,
size_t asn1_len ,
uint8_t * rs ,
size_t rs_len
)

decodes two concatenated ASN.1 integers to the R and S components of an ECDSA signature

Parameters
[in] asn1 Buffer containing the ASN.1 encoded R and S values as two concatenated DER INTEGERs
[in] asn1_len Length of the asn1 buffer
[out] rs Output buffer for the concatenated R and S values
[in] rs_len Length of the rs buffer
Returns
true on success, false else
Note
The R and S components will be padded with zeros in the output buffer and each component will take rs_len/2 bytes. e.g.: [ (0x00) R | S ], where '|' denotes the border for half the rs buffer, 'R' and 'S' the bytes of the R and S components and '(0x00)' one or multiple padding bytes needed to completely fill the buffer. If you need to know the exact length of R and S use asn1_to_ecdsa_rs_sep(...)
If the function returns false, all output values are invalid.
bool asn1_to_ecdsa_rs_sep ( const uint8_t * asn1 ,
size_t asn1_len ,
uint8_t * r ,
size_t * r_len ,
uint8_t * s ,
size_t * s_len
)

decodes two concatenated ASN.1 integers to the R and S components of an ECDSA signature with separate buffers for R and S

Parameters
[in] asn1 Buffer containing the ASN.1 encoded R and S values as two concatenated DER INTEGERs
[in] asn1_len Length of the asn1 buffer
[out] r Output buffer for the R value
[in,out] r_len Length of the r buffer, contains the number of non padding bytes afterwards
[out] s Output buffer for the S value
[in,out] s_len Length of the s buffer, contains the number of non padding bytes afterwards
Returns
true on success, false else
Note
The r and s buffers will be padded at the least significant byte with zeros to the length of the buffer.
If the function returns false, all output values are invalid.
bool ecdsa_rs_to_asn1_integers ( const uint8_t * r ,
const uint8_t * s ,
size_t rs_len ,
uint8_t * asn_sig ,
size_t * asn_sig_len
)

Encodes the ECDSA signature components (r, s) as two concatenated ASN.1 INTEGERs. This is the format the OPTIGA hostcode expects.

Parameters
[in] r Component R of the ECDSA signature
[in] s Component S of the ECDSA signature
[in] rs_len Length of each buffer for the R and S components of the ECDSA signature, must be smaller than 127
[out] asn_sig Buffer where the ASN.1 encoded result will be stored
[out] asn_sig_len Length of the ASN.1 encoded data that was copied into the output buffer
Returns
true on success, false on error
Note
The output buffer must be at least 2*rs_len + ECDSA_SIGNATURE_MAX_ASN1_OVERHEAD to fit the result in all cases.
If the function returns false, all output values are invalid.
bool ecdsa_rs_to_asn1_signature ( const uint8_t * r ,
const uint8_t * s ,
size_t rs_len ,
uint8_t * asn_sig ,
size_t * asn_sig_len
)

Encodes the ECDSA signature components (r, s) as ASN.1 SEQUENCE of two INTEGERs. This is the format mbedTLS and OpenSSL use.

Parameters
[in] r Component R of the ECDSA signature
[in] s Component S of the ECDSA signature
[in] rs_len Length of each buffer for the R and S components of the ECDSA signature, must be smaller than 127
[out] asn_sig Buffer where the ASN.1-encoded ECDSA signature will be stored
[out] asn_sig_len Length of the actual data that was copied into the output buffer
Returns
true on success, false on error
Note
The output buffer must be at least 2*rs_len + ECDSA_RS_MAX_ASN1_OVERHEAD to fit the result in all cases
If the function returns false, all output values are invalid.
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_open_application ( optiga_comms_t * p_comms )

Initializes the communication with optiga.

Initializes the communication with OPTIGA for the given instance.

Pre Conditions:

API Details:

  • Initiate open application command to optiga.

Notes:
Initialisation flow example: 

optiga_comms_t optiga_comms = {(void*)&ifx_i2c_context_0, NULL, NULL, 0};

static int32_t optiga_init(void)

{ int32_t status = (int32_t) OPTIGA_LIB_ERROR;

do { status = optiga_util_open_application(&optiga_comms); if(OPTIGA_LIB_SUCCESS != status) { // optiga_util_open_application() failed break; }

status = OPTIGA_LIB_SUCCESS; } while(0);

return status; }

Parameters
[in] p_comms Pointer to the communication parameters initialised before
  • Error codes from lower layer will be returned as it is.
Return values
OPTIGA_LIB_SUCCESS Successful invocation of optiga cmd module
OPTIGA_LIB_ERROR Error during function execurition
OPTIGA_DEVICE_ERROR Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_read_data ( uint16_t optiga_oid ,
uint16_t offset ,
uint8_t * buffer ,
uint16_t * bytes_to_read
)

Reads data from optiga.

Retrieves the requested data that is stored from the user provided data object.

Pre Conditions:

  • The application on OPTIGA must be opened using optiga_util_open_application before using this API.

API Details:

  • Invokes optiga_cmd_get_data_object API, based on the input arguments to read the data from the data object.

Notes:

  • Error codes from lower layers will be returned as it is.
  • The maximum value of the *bytes_to_read parameter is size of buffer p_buffer . In case the value is greater than buffer size, memory corruption can occur.
  • *bytes_to_read parameter is set to 0, in case any errors occurs while retrieving the data. initially contains the value of the user provided data length to be read. When the data is successfully retrieved, this value is updated with actual data length retrieved.
    In case of any errors, the value is set to 0.
Parameters
[in] optiga_oid OID of data object
  • It should be a valid data object, otherwise OPTIGA returns an error.
[in] offset Offset from within data object
  • It must be valid offset from within data object, otherwise OPTIGA returns an error.
[in,out] buffer Valid pointer to the buffer to which data is read
[in,out] bytes_to_read Valid pointer to the length of data to be read from data object
  • When the data is successfully retrieved, it is updated with actual data length retrieved
Return values
OPTIGA_UTIL_SUCCESS Successful invocation of optiga cmd module
OPTIGA_UTIL_ERROR_INVALID_INPUT Wrong Input arguments provided
OPTIGA_DEVICE_ERROR Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_read_metadata ( uint16_t optiga_oid ,
uint8_t * buffer ,
uint16_t * bytes_to_read
)

Reads metadata of a data object from optiga.

Reads the metadata of the user provided data object.

Pre Conditions:

  • The application on OPTIGA must be opened using optiga_util_open_application before using this API.

API Details:

  • Invokes optiga_cmd_get_data_object API, based on the input arguments to read the metadata from the data object.

Notes:

  • Error codes from lower layers will be returned as it is.
  • The metadata returned will be in TLV format.
  • The maximum value of the *bytes_to_read parameter is size of buffer p_buffer . In case the value is greater than buffer size, memory corruption can occur.
Parameters
[in] optiga_oid OID of data object
  • It should be a valid data object, otherwise OPTIGA returns an error.
[in,out] buffer Valid pointer to the buffer to which metadata is read
[in,out] bytes_to_read Valid pointer to the length of metadata to be read from data object
  • When the metadata is successfully retrieved, it is updated with actual metadata length retrieved
Return values
OPTIGA_UTIL_SUCCESS Successful invocation of optiga cmd module
OPTIGA_UTIL_ERROR_INVALID_INPUT Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE Same instance with ongoing request servicing used
OPTIGA_DEVICE_ERROR Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_write_data ( uint16_t optiga_oid ,
uint8_t write_type ,
uint16_t offset ,
uint8_t * buffer ,
uint16_t bytes_to_write
)

Writes data to optiga.

Writes the data provided by the user into the specified data object.

Pre Conditions:

  • The application on OPTIGA must be opened using optiga_util_open_application before using this API.

API Details:

  • Invokes optiga_cmd_set_data_object API, based on the input arguments to write the data to the data object.

Notes:

  • Error codes from lower layers will be returned as it is.
  • The maximum value of the bytes_to_write parameter is size of buffer p_buffer . In case the value is greater than buffer size, incorrect values can get written into the data object in OPTIGA.
  • In case the write_type provided is other than erase and write(0x00) or write only(0x40) , the function returns OPTIGA_UTIL_ERROR.
Parameters
[in] optiga_oid OID of data object
  • It should be a valid data object, otherwise OPTIGA returns an error.
[in] write_type Type of the write operation. Can be OPTIGA_UTIL_ERASE_AND_WRITE or OPTIGA_UTIL_WRITE_ONLY
[in] offset Offset from within data object
  • It must be valid offset from within data object, otherwise OPTIGA returns an error.
[in,out] buffer Valid pointer to the buffer with user data to write
[in] bytes_to_write Length of data to be written
Return values
OPTIGA_UTIL_SUCCESS Successful invocation of optiga cmd module
OPTIGA_UTIL_ERROR_INVALID_INPUT Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE Same instance with ongoing request servicing used
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT Length of the buffer to copy the metadata is less than actual length of metadata
OPTIGA_DEVICE_ERROR Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_util_write_metadata ( uint16_t optiga_oid ,
uint8_t * buffer ,
uint8_t bytes_to_write
)

Writes metadata for the user provided data object.

Writes metadata for the user provided data object.

Pre Conditions:

  • The application on OPTIGA must be opened using optiga_util_open_application before using this API.

API Details:

  • Invokes optiga_cmd_set_data_object API, based on the input arguments to write metadata to the data object.

Notes:

  • Error codes from lower layers will be returned as it is.
  • The maximum value of the bytes_to_write parameter is size of buffer p_buffer . In case the value is greater than buffer size, incorrect values can get written into the meta data of the data object in OPTIGA.
  • The metadata to be written must be in TLV format
Parameters
[in] optiga_oid OID of data object
  • It should be a valid data object, otherwise OPTIGA returns an error.
[in,out] buffer Valid pointer to the buffer with metadata to write
[in] bytes_to_write Length of metadata to be written
Return values
OPTIGA_UTIL_SUCCESS Successful invocation of optiga cmd module
OPTIGA_UTIL_ERROR_INVALID_INPUT Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE Same instance with ongoing request servicing used
OPTIGA_DEVICE_ERROR Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)