optiga_util.h File Reference

This file defines APIs, types and data structures used in the OPTIGA utility module. More...

#include "optiga_cmd.h"

Include dependency graph for optiga_util.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
union	optiga_util_params
	union for OPTIGA util parameters More...
struct	optiga_util
	OPTIGA util instance structure. More...
#define	OPTIGA_UTIL_WRITE_ONLY   (0x00)
	Option to only write the data object. More...
#define	OPTIGA_UTIL_ERASE_AND_WRITE   (0x40)
	Option to erase and write the data object. More...
#define	OPTIGA_UTIL_CONTEXT_NONE   (0x00)
	To Initialize a clean application context. More...
#define	OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL(p_instance, protection_level)
	Enables the protected I2C communication with OPTIGA for UTIL instances. More...
#define	OPTIGA_UTIL_SET_COMMS_PROTOCOL_VERSION(p_instance, version)
	Select the protocol version required for the I2C protected communication for UTIL instances. More...
#define	OPTIGA_UTIL_LOG_MESSAGE(msg)   {}
#define	OPTIGA_UTIL_LOG_HEX_DATA(array, array_len)   {}
#define	OPTIGA_UTIL_LOG_STATUS(return_value)   {}
typedef union optiga_util_params	optiga_util_params_t
	union for OPTIGA util parameters More...
typedef struct optiga_util	optiga_util_t
	OPTIGA util instance structure type. More...
void	optiga_util_set_comms_params (optiga_util_t *me, uint8_t configuration_type, uint8_t value)
	Sets/updates the OPTIGA Comms Shielded connection configuration in the respective (optiga_util) instance. More...
LIBRARY_EXPORTS optiga_util_t *	optiga_util_create (uint8_t optiga_instance_id, callback_handler_t handler, void *caller_context)
	Create an instance of optiga_util_t. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_destroy (optiga_util_t *me)
	De-Initializes the OPTIGA util instance. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_open_application (optiga_util_t *me, bool_t perform_restore)
	Initializes the communication with optiga and open the application on OPTIGA. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_close_application (optiga_util_t *me, bool_t perform_hibernate)
	Closes the application on OPTIGA and closes the communication with optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_read_data (optiga_util_t *me, uint16_t optiga_oid, uint16_t offset, uint8_t *buffer, uint16_t *length)
	Reads data from optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_read_metadata (optiga_util_t *me, uint16_t optiga_oid, uint8_t *buffer, uint16_t *length)
	Reads metadata of the specified data object from optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_write_data (optiga_util_t *me, uint16_t optiga_oid, uint8_t write_type, uint16_t offset, const uint8_t *buffer, uint16_t length)
	Writes data to optiga. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_write_metadata (optiga_util_t *me, uint16_t optiga_oid, const uint8_t *buffer, uint8_t length)
	Writes metadata for the user provided data object. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_protected_update_start (optiga_util_t *me, uint8_t manifest_version, const uint8_t *manifest, uint16_t manifest_length)
	Initiates the start of protected update of object by writing manifest into OPTIGA object. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_protected_update_continue (optiga_util_t *me, const uint8_t *fragment, uint16_t fragment_length)
	Sends fragment(s) of data to be written to OPTIGA. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_protected_update_final (optiga_util_t *me, const uint8_t *fragment, uint16_t fragment_length)
	Sends the last fragment to finalize the protected update of data object. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_util_update_count (optiga_util_t *me, uint16_t optiga_counter_oid, uint8_t count)
	Increments the counter object by a value specified by user. More...

Detailed Description

This file defines APIs, types and data structures used in the OPTIGA utility module.

Copyright

MIT License

Copyright (c) 2019 Infineon Technologies AG

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

\endcopyright

Author

Infineon Technologies AG

Macro Definition Documentation

OPTIGA_UTIL_CONTEXT_NONE

#define OPTIGA_UTIL_CONTEXT_NONE   (0x00)

To Initialize a clean application context.

OPTIGA_UTIL_ERASE_AND_WRITE

#define OPTIGA_UTIL_ERASE_AND_WRITE   (0x40)

Option to erase and write the data object.

OPTIGA_UTIL_LOG_HEX_DATA

#define OPTIGA_UTIL_LOG_HEX_DATA	(		array,
			array_len
	)		{}

OPTIGA_UTIL_LOG_MESSAGE

#define OPTIGA_UTIL_LOG_MESSAGE

(

msg

)

{}

OPTIGA_UTIL_LOG_STATUS

#define OPTIGA_UTIL_LOG_STATUS

(

return_value

)

{}

OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL

#define OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL	(		p_instance,
			protection_level
	)

Value:

{ \
    optiga_util_set_comms_params(p_instance, \
                                        OPTIGA_COMMS_PROTECTION_LEVEL, \
                                        protection_level); \
}

Enables the protected I2C communication with OPTIGA for UTIL instances.

Enables the protected I2C communication with OPTIGA

• Sets the protection mode for the supplied instance.
  
• Call this function before calling the service layer API which requires protection.

Precondition

• OPTIGA_COMMS_SHIELDED_CONNECTION macro must be defined.
  
• OPTIGA_UTIL_SET_COMMS_PROTOCOL_VERSION function must be called once to set the required protocol version
  • Currently only Pre-shared Secret based version is supported.
• The host and OPTIGA must be paired and Pre-Shared secret is available.
  

Note

• The protection mode for the instance is reset to OPTIGA_COMMS_NO_PROTECTION once the service layer API returns synchronously.

Parameters

[in]	p_instance	Valid pointer to an instance
[in]	protection_level	Required protection mode OPTIGA_COMMS_NO_PROTECTION : Command and response is unprotected OPTIGA_COMMS_COMMAND_PROTECTION : Command is protected and response is unprotected OPTIGA_COMMS_RESPONSE_PROTECTION : Command is unprotected and response is protected OPTIGA_COMMS_FULL_PROTECTION : Both command and response is protected To re-establish secure channel, bitwise-OR protection_level with OPTIGA_COMMS_RE_ESTABLISH

OPTIGA_UTIL_SET_COMMS_PROTOCOL_VERSION

#define OPTIGA_UTIL_SET_COMMS_PROTOCOL_VERSION	(		p_instance,
			version
	)

Value:

{ \
    optiga_util_set_comms_params(p_instance, \
                                        OPTIGA_COMMS_PROTOCOL_VERSION, \
                                        version);\
}

Select the protocol version required for the I2C protected communication for UTIL instances.

Select the protocol version required for the I2C protected communication

• Select the protocol version for the supplied instance.
  

Precondition

• OPTIGA_COMMS_SHIELDED_CONNECTION macro must be defined.
  

Note

• None

Parameters

[in]	p_instance	Valid pointer to an instance
[in]	version	Required protocol version OPTIGA_COMMS_PROTOCOL_VERSION_PRE_SHARED_SECRET : Pre-shared Secret based protocol version

OPTIGA_UTIL_WRITE_ONLY

#define OPTIGA_UTIL_WRITE_ONLY   (0x00)

Option to only write the data object.

Typedef Documentation

optiga_util_params_t

typedef union optiga_util_params optiga_util_params_t

union for OPTIGA util parameters

optiga_util_t

typedef struct optiga_util optiga_util_t

OPTIGA util instance structure type.

Function Documentation

optiga_util_close_application()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_close_application	(	optiga_util_t *	me,
		bool_t	perform_hibernate
	)

Closes the application on OPTIGA and closes the communication with optiga.

Closes the communication with OPTIGA for the given instance.

• Initiate close application command to optiga.
• Perform manage context secure session save operations.
• De-Initializes the OPTIGA and closes the communication channel.
• Power downs the OPTIGA after closing the application on optiga.

Precondition

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

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layer will be returned as it is.

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	perform_hibernate	Hibernate the application on OPTIGA. The values must be as defined below. TRUE (1) - Performs application hibernate. FALSE (0) - De-Initializes application context.

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Input arguments are NULL
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
main_xmc4800_sample.c

Here is the call graph for this function:

optiga_util_create()

LIBRARY_EXPORTS optiga_util_t* optiga_util_create	(	uint8_t	optiga_instance_id,
		callback_handler_t	handler,
		void *	caller_context
	)

Create an instance of optiga_util_t.

Create an instance of optiga_util_t.

• Stores the callers context and callback handler.
• Allocate memory for optiga_util_t.

Precondition

• None

Note

• This API is implemented in synchronous mode.
• For protected I2C communication,
  • Default protection level for this API is OPTIGA_COMMS_DEFAULT_PROTECTION_LEVEL.
  • Default protocol version for this API is OPTIGA_COMMS_PROTOCOL_VERSION_PRE_SHARED_SECRET.

Parameters

[in]	optiga_instance_id	Indicates the OPTIGA instance to be associated with optiga_util_t. Value should be defined as below OPTIGA_INSTANCE_ID_0 : Indicate created instance will be part of OPTIGA with slave address 0x30.
[in]	handler	Valid pointer to callback function
[in]	caller_context	Pointer to upper layer context, contains user context data

Return values

optiga_util_t	On success function will return pointer of optiga_util_t
NULL	Input arguments are NULL. Low layer function fails. OPTIGA_CMD_MAX_REGISTRATIONS number of instances are already created.

Example
main_xmc4800_sample.c

Here is the call graph for this function:

optiga_util_destroy()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_destroy

(

optiga_util_t *

me

)

De-Initializes the OPTIGA util instance.

De-Initializes the optiga_util_t instance.

• De-allocate the memory of the optiga_util_t instance.

Precondition

• None

Note

• User must take care to nullify the instance pointer.
• Invoke this API only after all the asynchronous process is completed otherwise the behavior of software stack is not defined.

Parameters

[in]

me

Valid instance of optiga_util_t

Return values

OPTIGA_LIB_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete

Example
main_xmc4800_sample.c

Here is the call graph for this function:

optiga_util_open_application()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_open_application	(	optiga_util_t *	me,
		bool_t	perform_restore
	)

Initializes the communication with optiga and open the application on OPTIGA.

Initializes the communication with OPTIGA for the given instance.

• Sets up optiga comms channel.
  
• Initiate open application command to optiga.
  
• Perform manage context , session restore operations and application restore.
  

Precondition

• For restoring OPTIGA application, the application must be in hibernate state using optiga_util_close_application.

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layer will be returned as it is.
• If error in lower layer occurs while restoring OPTIGA application, then initialize a clean OPTIGA application context.

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	perform_restore	Restore application on OPTIGA from a previous hibernate state. The values must be as defined below TRUE (1) - Performs application restore. FALSE (0) - Initialize a clean application context.

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
main_xmc4800_sample.c

Here is the call graph for this function:

optiga_util_protected_update_continue()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_protected_update_continue	(	optiga_util_t *	me,
		const uint8_t *	fragment,
		uint16_t	fragment_length
	)

Sends fragment(s) of data to be written to OPTIGA.

Sends a fragment of data to be written to OPTIGA.

• Invokes optiga_cmd_set_object_protected API, to send the fragment of data to write to OPTIGA.

Precondition

• The application on OPTIGA must be opened using optiga_util_open_application.
• The manifest must be written to OPTIGA using optiga_util_protected_update_start, otherwise lower layer returns an error.

Note

• The protected I2C communication value set in optiga_util_protected_update_start will be used in this API.
  
• Error codes from lower layers will be returned as it is.
  
• For writing 'n' fragment (s) ,
  • if n > 1 : Send 1 to 'n - 1' fragments using optiga_util_protected_update_continue and and the final fragment using optiga_util_protected_update_final.
    
  • if n == 1 : Send the fragment using optiga_util_protected_update_final.
    
• Chaining of fragments and the sequence of sending fragments must be handled externally to this API.
  
• The strict sequence is terminated in case of an error from lower layer
  

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	fragment	Valid pointer to the buffer which contains fragment It must be a valid fragment, otherwise OPTIGA returns an error.
[in]	fragment_length	Length of fragment to be written

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_protected_update.c

Here is the call graph for this function:

optiga_util_protected_update_final()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_protected_update_final	(	optiga_util_t *	me,
		const uint8_t *	fragment,
		uint16_t	fragment_length
	)

Sends the last fragment to finalize the protected update of data object.

Sends the last fragment to finalize the protected update of data object.

• Invokes optiga_cmd_set_object_protected API, based on the input arguments to write the final fragment to data object.
• It terminates the strict sequence.

Precondition

• The application on OPTIGA must be opened using optiga_util_open_application.
• The manifest must be written to OPTIGA using optiga_util_protected_update_start, otherwise lower layer returns an error.

Note

• The protected I2C communication value set in optiga_util_protected_update_start will be used in this API.
  
• Error codes from lower layers will be returned as it is.
  
• The strict sequence is terminated in case of an error from lower layer.
  

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	fragment	Valid pointer to the buffer which contains the last fragment. If NULL, only strict sequence is released and no APDU is sent to OPTIGA
[in]	fragment_length	Length of fragment to be written

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_protected_update.c

Here is the call graph for this function:

optiga_util_protected_update_start()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_protected_update_start	(	optiga_util_t *	me,
		uint8_t	manifest_version,
		const uint8_t *	manifest,
		uint16_t	manifest_length
	)

Initiates the start of protected update of object by writing manifest into OPTIGA object.

Initiates the start of protected update of object.

• It marks the beginning of a strict sequence. None of the service layer API will be processed until the strict sequence is terminated.
• Invokes optiga_cmd_set_object_protected API, based on the input arguments to send manifest to OPTIGA.

Precondition

• The application on OPTIGA must be opened using optiga_util_open_application.

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
  • The protection level set in this API will be used for optiga_util_protected_update_continue and optiga_util_protected_update_final.
    
• Error codes from lower layers will be returned as it is.
  
• The strict sequence is terminated
  • In case of an error from lower layer.
    
  • Same instance is used for other service layer APIs (except optiga_util_protected_update_continue).
    
• Any subsequent call to this API with same instance is accepted, provided the previous once is asynchronously completed.
  

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	manifest_version	Version of manifest to be written
[in]	manifest	Valid pointer to the buffer which contains manifest It should be a valid manifest, otherwise OPTIGA returns an error.
[in]	manifest_length	Length of manifest to be written

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_protected_update.c

Here is the call graph for this function:

optiga_util_read_data()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_read_data	(	optiga_util_t *	me,
		uint16_t	optiga_oid,
		uint16_t	offset,
		uint8_t *	buffer,
		uint16_t *	length
	)

Reads data from optiga.

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

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

Precondition

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

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layers will be returned as it is.
• The maximum value of the *length parameter must be the size of buffer buffer. In case the value is greater than buffer size, memory corruption can occur.
  
• If any errors occur while retrieving the data, *length parameter is set to 0.

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[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]	length	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
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_read_data.c

Here is the call graph for this function:

optiga_util_read_metadata()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_read_metadata	(	optiga_util_t *	me,
		uint16_t	optiga_oid,
		uint8_t *	buffer,
		uint16_t *	length
	)

Reads metadata of the specified data object from optiga.

Reads the metadata of the user provided data object.

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

Precondition

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

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layers will be returned as it is.
• The metadata returned will be in TLV format.
• The maximum value of the *length parameter must be the size of buffer. In case the value is greater than buffer size, memory corruption can occur.
  
• If any errors occur while retrieving the data, *length parameter is set to 0.

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[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]	length	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
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_read_data.c

Here is the call graph for this function:

optiga_util_set_comms_params()

void optiga_util_set_comms_params	(	optiga_util_t *	me,
		uint8_t	configuration_type,
		uint8_t	value
	)

Sets/updates the OPTIGA Comms Shielded connection configuration in the respective (optiga_util) instance.

Sets/updates the OPTIGA Comms Shielded connection configuration in the respective (optiga_util) instance.

• The OPTIGA_COMMS_PROTECTION_LEVEL configuration settings using this API, will be used in the next immediate usage of the instance.
• Once the API is invoked, this level gets reset to the default protection level OPTIGA_COMMS_DEFAULT_PROTECTION_LEVEL

Precondition

• None

Note

• None

Parameters

[in,out]	me	Valid instance of optiga_util_t
[in]	configuration_type	Configuration Type Possible Types are OPTIGA_COMMS_PROTECTION_LEVEL OPTIGA_COMMS_PROTOCOL_VERSION
[in]	value	Value part for the respective configuration

Example

optiga_util_update_count()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_update_count	(	optiga_util_t *	me,
		uint16_t	optiga_counter_oid,
		uint8_t	count
	)

Increments the counter object by a value specified by user.

Increments the counter object by a value specified by user.

• Invokes optiga_cmd_set_data_object API, based on the input arguments to update the count to the specified data object.
  

Precondition

• The application on OPTIGA must be opened using optiga_util_open_application before using this API.
  
• Initial count and threshold value must be set using optiga_util_write_data.
  

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	optiga_counter_oid	OID of counter data object It should be a valid data object, otherwise OPTIGA returns an error.
[in]	count	Counter value to be updated

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_update_count.c

Here is the call graph for this function:

optiga_util_write_data()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_write_data	(	optiga_util_t *	me,
		uint16_t	optiga_oid,
		uint8_t	write_type,
		uint16_t	offset,
		const uint8_t *	buffer,
		uint16_t	length
	)

Writes data to optiga.

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

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

Precondition

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

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layers will be returned as it is.
  
• The maximum value of the length parameter is size of 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_INVALID_INPUT.
  

Parameters

[in]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	optiga_oid	OID of data object It should be a valid data object, otherwise OPTIGA returns an error.
[in]	write_type	Type of write must be either OPTIGA_UTIL_WRITE_ONLY or OPTIGA_UTIL_ERASE_AND_WRITE.
[in]	offset	Offset from within data object It must be valid offset from within data object, otherwise OPTIGA returns an error.
[in]	buffer	Valid pointer to the buffer with user data to write
[in]	length	Length of data to be written

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_util_write_data.c

Here is the call graph for this function:

optiga_util_write_metadata()

LIBRARY_EXPORTS optiga_lib_status_t optiga_util_write_metadata	(	optiga_util_t *	me,
		uint16_t	optiga_oid,
		const uint8_t *	buffer,
		uint8_t	length
	)

Writes metadata for the user provided data object.

Writes metadata for the specified data object.

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

Precondition

• The application on OPTIGA must be opened using optiga_util_open_application.

Note

• For protected I2C communication, Refer OPTIGA_UTIL_SET_COMMS_PROTECTION_LEVEL
• Error codes from lower layers will be returned as it is.
  
• The maximum value of the length parameter is size of 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]	me	Valid instance of optiga_util_t created using optiga_util_create.
[in]	optiga_oid	OID of data object It should be a valid data object, otherwise OPTIGA returns an error.
[in]	buffer	Valid pointer to the buffer with metadata to write
[in]	length	Length of metadata to be written

Return values

OPTIGA_UTIL_SUCCESS	Successful invocation
OPTIGA_UTIL_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_UTIL_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.

Example
example_optiga_util_write_data.c

Here is the call graph for this function: