optiga_comms.h File Reference

This file implements Optiga comms abstraction layer for IFX I2C Protocol. More...

#include "optiga_lib_types.h"
#include "optiga_lib_return_codes.h"
#include "optiga_lib_common.h"

Include dependency graph for optiga_comms.h:

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

Go to the source code of this file.

Classes
struct	optiga_comms
	Optiga comms structure. More...
#define	OPTIGA_COMMS_DATA_OFFSET   (0x05)
#define	OPTIGA_COMMS_PRL_OVERHEAD   (0x0D)
typedef struct optiga_comms	optiga_comms_t
	Optiga comms structure. More...
optiga_comms_t	optiga_comms
	optiga communication structure More...
optiga_comms_t *	optiga_comms_create (callback_handler_t callback, void *context)
	Provides the singleton OPTIGA instance. More...
void	optiga_comms_destroy (optiga_comms_t *optiga_comms)
	Deinitializes the OPTIGA comms instance. More...
optiga_lib_status_t	optiga_comms_set_callback_context (optiga_comms_t *p_optiga_comms, void *context)
	Sets the callers context to OPTIGA comms instance. More...
optiga_lib_status_t	optiga_comms_set_callback_handler (optiga_comms_t *p_optiga_comms, callback_handler_t handler)
	Sets the callback handler to OPTIGA comms instance. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_comms_open (optiga_comms_t *p_ctx)
	Opens the communication channel with OPTIGA. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_comms_reset (optiga_comms_t *p_ctx, uint8_t reset_type)
	Resets the OPTIGA. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_comms_transceive (optiga_comms_t *p_ctx, const uint8_t *p_tx_data, uint16_t tx_data_length, uint8_t *p_rx_data, uint16_t *p_rx_data_len)
	Sends and receives the APDU. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_comms_close (optiga_comms_t *p_ctx)
	Closes the communication channel with OPTIGA. More...

Detailed Description

This file implements Optiga comms abstraction layer for IFX I2C Protocol.

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_COMMS_DATA_OFFSET

#define OPTIGA_COMMS_DATA_OFFSET   (0x05)

OPTIGA_COMMS_PRL_OVERHEAD

#define OPTIGA_COMMS_PRL_OVERHEAD   (0x0D)

Typedef Documentation

optiga_comms_t

typedef struct optiga_comms optiga_comms_t

Optiga comms structure.

Function Documentation

optiga_comms_close()

LIBRARY_EXPORTS optiga_lib_status_t optiga_comms_close

(

optiga_comms_t *

p_ctx

)

Closes the communication channel with OPTIGA.

Closes the communication with OPTIGA.

• De-Initializes the OPTIGA and closes the communication channel.
• Power downs the OPTIGA.

Precondition

• None

Note

• The optiga_comms_t comms_ctx must be initialized with a valid ifx_i2c_context
  
• manage_contex_operation : Used for managing session context and the values must be as defined below. The value of the parameter is not modified by the IFX-I2C protocol stack.
  • OPTIGA_COMMS_SESSION_CONTEXT_SAVE : save active secure session.
  • OPTIGA_COMMS_SESSION_CONTEXT_NONE : for no manage context operation.

Parameters

[in,out]

p_ctx

Valid instance of optiga_comms_t created using optiga_comms_create

Return values

OPTIGA_COMMS_SUCCESS
OPTIGA_COMMS_ERROR

Here is the call graph for this function:

optiga_comms_create()

optiga_comms_t* optiga_comms_create	(	callback_handler_t	callback,
		void *	context
	)

Provides the singleton OPTIGA instance.

Creates an instance of optiga_comms_t.

• Stores the callers context and callback handler.
• Allocate memory for optiga_comms_t.
• Assigns OPTIGA structure based on the Optiga instance.

Precondition

• None

Note

• None

Parameters

[in]	callback	Pointer to callback function, must not be NULL
[in]	context	Pointer to upper layer context.

Return values

optiga_comms_t	* On successful instance creation
NULL	Memory allocation failure

optiga_comms_destroy()

void optiga_comms_destroy

(

optiga_comms_t *

optiga_comms

)

Deinitializes the OPTIGA comms instance.

Destroys the instance of optiga_comms_t.

• Releases any OPTIGA cmd module lock utilized by the instance.
• Releases any OPTIGA session acquired by the instance.
• Deallocates the memory of the optiga_comms_t instance.

Precondition

• None

Note

• None

Parameters

[in]

optiga_comms

Valid instance of optiga_comms_t created using optiga_comms_create

optiga_comms_open()

LIBRARY_EXPORTS optiga_lib_status_t optiga_comms_open

(

optiga_comms_t *

p_ctx

)

Opens the communication channel with OPTIGA.

Initializes the communication with OPTIGA

• Initializes OPTIGA and establishes the communication channel.
• Initializes the IFX I2C protocol stack and registers the event callbacks.
• Negotiates the frame size and bit rate with the OPTIGA.

Precondition

• None

Note

• The following parameters in ifx_i2c_context_t must be initialized with appropriate values
  
  • slave address : Address of I2C slave
  • frame_size : Frame size in bytes. Minimum supported value is 16 bytes.
    
    • It is recommended not to use a value greater than the slave's frame size.
    • The user specified frame size is written to I2C slave's frame size register. The frame size register is read back from I2C slave. This frame value is used by the IFX-I2C protocol even if it is not equal to the user specified value.
  • frequency : Frequency/speed of I2C master in KHz.
    • This must be lowest of the maximum frequency supported by the devices (master/slave) connected on the bus.
    • Initial negotiation starts with a frequency of 100KHz.
    • If the user specified frequency is more than 400 KHz, the I2C slave is configured to operate in "Fm+" mode, otherwise the I2C slave is configured for "SM & Fm" mode.
      
    • If the user specified frequency negotiation fails, the I2C master frequency remains at 100KHz
      
  • upper_layer_event_handler : Upper layer event handler. This is invoked when ifx_i2c_open() is asynchronously completed.
  • upper_layer_ctx : Context of upper layer.
  • p_slave_vdd_pin : GPIO pin for VDD. If not set, cold reset is not done.
  • p_slave_reset_pin : GPIO pin for Reset. If not set, warm reset is not done.
  • manage_contex_operation : Used for managing session context and the values must be as defined below. The value of the parameter is not modified by the IFX-I2C protocol stack.
    • OPTIGA_COMMS_SESSION_CONTEXT_RESTORE : Restore any stored session context.
    • OPTIGA_COMMS_SESSION_CONTEXT_NONE : No manage context operation.
• The values of registers MAX_SCL_FREQU and DATA_REG_LEN, read from slave are not validated.
• At present, only single instance of ifx_i2c_context_t is supported.
• Manage context operations will start in next transceive.

Parameters

[in,out]

p_ctx

Valid instance of optiga_comms_t created using optiga_comms_create

Return values

OPTIGA_COMMS_SUCCESS
OPTIGA_COMMS_ERROR

Here is the call graph for this function:

optiga_comms_reset()

LIBRARY_EXPORTS optiga_lib_status_t optiga_comms_reset	(	optiga_comms_t *	p_ctx,
		uint8_t	reset_type
	)

Resets the OPTIGA.

Resets the communication channel with OPTIGA.

• Resets the OPTIGA device.
• Initializes the IFX I2C protocol stack.
• Re-Initializes and negotiates the frame size and bit rate with the OPTIGA. The values remain same as that in previous optiga_comms_open().

Precondition

• Communication channel must be established with OPTIGA.

Note

• This function clears the saved context.

Parameters

[in,out]	p_ctx	Valid instance of optiga_comms_t created using optiga_comms_create
[in,out]	reset_type	Type of reset For COLD and WARM reset type: If the GPIO(VDD and/or reset) pins are not configured, the API continues without returning error status

Return values

OPTIGA_COMMS_SUCCESS
OPTIGA_COMMS_ERROR

Here is the call graph for this function:

optiga_comms_set_callback_context()

optiga_lib_status_t optiga_comms_set_callback_context	(	optiga_comms_t *	p_optiga_comms,
		void *	context
	)

Sets the callers context to OPTIGA comms instance.

Sets the callers context to optiga_comms_t.

Precondition

• None

Note

• None

Parameters

[in]	p_optiga_comms	Valid instance of optiga_comms_t created using optiga_comms_create
[in]	context	Pointer to callers context

optiga_comms_set_callback_handler()

optiga_lib_status_t optiga_comms_set_callback_handler	(	optiga_comms_t *	p_optiga_comms,
		callback_handler_t	handler
	)

Sets the callback handler to OPTIGA comms instance.

Sets the callback handler to optiga_comms_t instance.

Precondition

• None

Note

• None

Parameters

[in]	p_optiga_comms	Valid instance of optiga_comms_t created using optiga_comms_create
[in]	handler	Pointer to callback handler

optiga_comms_transceive()

LIBRARY_EXPORTS optiga_lib_status_t optiga_comms_transceive	(	optiga_comms_t *	p_ctx,
		const uint8_t *	p_tx_data,
		uint16_t	tx_data_length,
		uint8_t *	p_rx_data,
		uint16_t *	p_rx_data_len
	)

Sends and receives the APDU.

Sends a command to OPTIGA and receives a response.

• Transmit data(Command) to OPTIGA.
• Receive data(Response) from OPTIGA.

Precondition

• Communication channel must be established with OPTIGA

Note

• The following parameters in optiga_comms_t must be initialized with appropriate values
  
  • The comms_ctx must be initialized with a valid ifx_i2c_context_t
    
  • The upper_layer_event_handler parameter must be properly initialized, if it is different from that in optiga_comms_open(). This is invoked when optiga_comms_transceive is asynchronously completed.
    
  • The upper_layer_ctx must be properly initialized, if it is different from that in optiga_comms_open().
  • protection_level : Used for secure communication.The value of the parameter is not modified by the IFX-I2C protocol stack.
  • The values for protection_level must be one of the below
    • 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

• If Presentation Layer is enabled,
  • Additional buffer size is required to handle encryption and decryption functionality.
• The total buffer size with the additional presentation layer overhead is explained in the figure below. Please provide the lengths and data buffers as specified below.
  • The transmit and receive data buffers need additional overhead of OPTIGA_COMMS_PRL_OVERHEAD bytes along with Tx/Rx data(payload) size.
  • Provide the command data, starting from the OPTIGA_COMMS_DATA_OFFSET location in the transmit buffer.
  • In the receive buffer, the response (received data) from the OPTIGA will be stored from the OPTIGA_COMMS_DATA_OFFSET location. Read the response from this offset.
  • Provide the length of command data (tx_data_length) with the payload length excluding the additional overhead.
  • Provide the length of response data (p_rx_data_length) in order to copy the response to the buffer provided.

optiga_comms_transceive()

• The actual number of bytes received is stored in p_rx_buffer_len. In case of error,p_rx_buffer_len is set to 0.
  
• If the size of p_rx_data is zero or insufficient to copy the response bytes, OPTIGA_COMMS_ERROR_STACK_MEMORY error is returned.
• If establishing a secure channel fails, OPTIGA_COMMS_ERROR_HANDSHAKE is returned.
• If OPTIGA_COMMS_ERROR_SESSION is returned, a new session must be established.
• If presentation layer is enabled and the command data protection is selected, the input data provided will be modified because the data will be encrypted in the same input buffer. Therefore, if required by the user a copy of the input data must be preserved by the caller of this API.

Parameters

[in,out]	p_ctx	Valid instance of optiga_comms_t created using optiga_comms_create
[in]	p_tx_data	Pointer to the transmit data buffer
[in]	tx_data_length	Length of the transmit data buffer
[in,out]	p_rx_data	Pointer to the receive data buffer
[in,out]	p_rx_data_len	Pointer to the length of the receive data buffer

Return values

OPTIGA_COMMS_SUCCESS
OPTIGA_COMMS_ERROR
OPTIGA_COMMS_ERROR_STACK_MEMORY
OPTIGA_COMMS_ERROR_HANDSHAKE
OPTIGA_COMMS_ERROR_SESSION

Here is the call graph for this function:

Variable Documentation

optiga_comms

optiga_comms_t optiga_comms

optiga communication structure