OPTIGA UTIL module

nRF5 SDK v15.3.0
Macros | Typedefs | Enumerations | Functions

Macros

#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.

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

optiga_lib_status_t optiga_util_open_application ( optiga_comms_t *p_comms)
Initializes the communication with optiga. More...
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...
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...
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...
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

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

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.

Parameters
[in] p_comms Pointer to the communication parameters initialised before
Return values
OPTIGA_LIB_SUCCESS Successful invocation of optiga cmd module
OPTIGA_LIB_ERROR Error during function execution
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:

API Details:

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

Notes:

  • 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_LIB_SUCCESS Successful invocation of optiga cmd module
OPTIGA_LIB_ERROR Wrong Input arguments provided or error occured
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:

API Details:

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

Notes:

  • 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_LIB_SUCCESS Successful invocation of optiga cmd module
OPTIGA_LIB_ERROR Wrong Input arguments provided or error occured
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:

API Details:

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

Notes:

  • 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_LIB_SUCCESS Successful invocation of optiga cmd module
OPTIGA_LIB_ERROR Wrong Input arguments provided or error occured
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:

API Details:

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

Notes:

  • 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_LIB_SUCCESS Successful invocation of optiga cmd module
OPTIGA_LIB_ERROR Wrong Input arguments provided or error occured