optiga_cmd.h File Reference

This file defines APIs, types and data structures used in the Command (cmd) module implementation. More...

#include "optiga_lib_common.h"

Include dependency graph for optiga_cmd.h:

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

Go to the source code of this file.

#define	OPTIGA_CMD_LOG_MESSAGE(msg)   {}
#define	OPTIGA_CMD_LOG_HEX_DATA(array, array_len)   {}
#define	OPTIGA_CMD_LOG_STATUS(return_value)   {}
typedef struct optiga_cmd	optiga_cmd_t
	OPTIGA command instance structure type. More...
typedef struct optiga_context	optiga_context_t
	OPTIGA comms instance structure type. More...
optiga_cmd_t *	optiga_cmd_create (uint8_t optiga_instance_id, callback_handler_t handler, void *caller_context)
	Creates an instance of optiga_cmd_t. More...
optiga_lib_status_t	optiga_cmd_destroy (optiga_cmd_t *me)
	Destroys the instance of optiga_cmd_t. More...
optiga_lib_status_t	optiga_cmd_release_lock (const optiga_cmd_t *me)
	Releases the OPTIGA cmd lock. More...
optiga_lib_status_t	optiga_cmd_open_application (optiga_cmd_t *me, uint8_t cmd_param, void *params)
	Opens the OPTIGA Application. More...
optiga_lib_status_t	optiga_cmd_close_application (optiga_cmd_t *me, uint8_t cmd_param, void *params)
	Closes the OPTIGA Application. More...
optiga_lib_status_t	optiga_cmd_get_data_object (optiga_cmd_t *me, uint8_t cmd_param, optiga_get_data_object_params_t *params)
	Reads data or metadata of the specified data object. More...
optiga_lib_status_t	optiga_cmd_set_data_object (optiga_cmd_t *me, uint8_t cmd_param, optiga_set_data_object_params_t *params)
	Writes data or metadata to the specified data object. More...
optiga_lib_status_t	optiga_cmd_get_random (optiga_cmd_t *me, uint8_t cmd_param, optiga_get_random_params_t *params)
	Generates random data or pre-master secret for RSA key exchange. More...
optiga_lib_status_t	optiga_cmd_calc_hash (optiga_cmd_t *me, uint8_t cmd_param, optiga_calc_hash_params_t *params)
	Generates hash on external data or data in OID. More...
optiga_lib_status_t	optiga_cmd_calc_sign (optiga_cmd_t *me, uint8_t cmd_param, optiga_calc_sign_params_t *params)
	Calculate signature on digest. More...
optiga_lib_status_t	optiga_cmd_verify_sign (optiga_cmd_t *me, uint8_t cmd_param, optiga_verify_sign_params_t *params)
	Verifies the signature over the given digest. More...
optiga_lib_status_t	optiga_cmd_calc_ssec (optiga_cmd_t *me, uint8_t cmd_param, optiga_calc_ssec_params_t *params)
	Calculates shared secret. More...
optiga_lib_status_t	optiga_cmd_derive_key (optiga_cmd_t *me, uint8_t cmd_param, optiga_derive_key_params_t *params)
	Derives a key. More...
optiga_lib_status_t	optiga_cmd_gen_keypair (optiga_cmd_t *me, uint8_t cmd_param, optiga_gen_keypair_params_t *params)
	Generates ECC or RSA key-pair. More...
optiga_lib_status_t	optiga_cmd_encrypt_asym (optiga_cmd_t *me, uint8_t cmd_param, optiga_encrypt_asym_params_t *params)
	Encrypt data using RSA public key. More...
optiga_lib_status_t	optiga_cmd_decrypt_asym (optiga_cmd_t *me, uint8_t cmd_param, optiga_decrypt_asym_params_t *params)
	Decrypts data using OPTIGA RSA private key. More...
optiga_lib_status_t	optiga_cmd_set_object_protected (optiga_cmd_t *me, uint8_t cmd_param, optiga_set_object_protected_params_t *params)
	Writes protected object fragments to OPTIGA. More...

Detailed Description

This file defines APIs, types and data structures used in the Command (cmd) module implementation.

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_CMD_LOG_HEX_DATA

#define OPTIGA_CMD_LOG_HEX_DATA	(		array,
			array_len
	)		{}

OPTIGA_CMD_LOG_MESSAGE

#define OPTIGA_CMD_LOG_MESSAGE

(

msg

)

{}

OPTIGA_CMD_LOG_STATUS

#define OPTIGA_CMD_LOG_STATUS

(

return_value

)

{}

Typedef Documentation

optiga_cmd_t

typedef struct optiga_cmd optiga_cmd_t

OPTIGA command instance structure type.

optiga_context_t

typedef struct optiga_context optiga_context_t

OPTIGA comms instance structure type.

Function Documentation

optiga_cmd_calc_hash()

optiga_lib_status_t optiga_cmd_calc_hash	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_calc_hash_params_t *	params
	)

Generates hash on external data or data in OID.

Generates hash on external data or data in OID by issuing Calc Hash command to OPTIGA.

• Acquires the OPTIGA lock for optiga_crypt_hash_start/optiga_crypt_hash_update/optiga_crypt_hash_finalize.
  
• Forms the CalcHash command based on inputs.
  
• Issues the CalcHash command through optiga_comms_transceive.
  
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.

Note

• Error codes from lower layers will be returned as it is.

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of CalcHash Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of CalcHash Command APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking CalcHash command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE. Data received from OPTIGA is greater than the buffer size provided by user.

Here is the call graph for this function:

optiga_cmd_calc_sign()

optiga_lib_status_t optiga_cmd_calc_sign	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_calc_sign_params_t *	params
	)

Calculate signature on digest.

Calculate signature on digest by issuing Calc Sign command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_ecdsa_sign/optiga_crypt_rsa_sign.
  
• Forms the Generate KeyPair command based on inputs.
  
• Issues the Generate KeyPair command through optiga_comms_transceive.
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.

Note

• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Calc Sign Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Calc Sign Command APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Calc Sign command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_INVALID_INPUT	Instance invoked for session oid, without acquiring the session (from optiga_cmd_gen_keypair).
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE. Length of the buffer to copy the signature is less than actual length of signature.

Here is the call graph for this function:

optiga_cmd_calc_ssec()

optiga_lib_status_t optiga_cmd_calc_ssec	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_calc_ssec_params_t *	params
	)

Calculates shared secret.

Calculates shared secret by issuing CalcSSec command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_ecdh.
  
• Forms the command apdu based on inputs.
  
• Issues the command through optiga_comms_transceive.
  
• If the private key is session based or shared secret is to be stored in OPTIGA, it acquires a session if not already available.
  
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application.
• A key pair must be generated/available in the given private key ID.

Note

• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Calc SSec Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	Pointer to input parameters, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation of optiga_comms module.
OPTIGA_CMD_ERROR	Error occurred before invoking CalcSSec command optiga_comms_transceive returned a failure Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_INVALID_INPUT	Instance invoked for session oid, without acquiring the session (from optiga_cmd_gen_keypair).
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function:

optiga_cmd_close_application()

optiga_lib_status_t optiga_cmd_close_application	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		void *	params
	)

Closes the OPTIGA Application.

Closes the OPTIGA Application by issuing the CloseApplication command.

• Acquires the OPTIGA lock for optiga_util_close_application.
  
• Forms the CloseApplication commands based on inputs.
  
• Issues the CloseApplication command through optiga_comms_transceive.
  
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
  

Note

• This function must be mandatorily invoked before issuing a reset to OPTIGA, in case the context needs to be saved.
• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	Secure connection related information, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking CloseApplication command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function:

optiga_cmd_create()

optiga_cmd_t* optiga_cmd_create	(	uint8_t	optiga_instance_id,
		callback_handler_t	handler,
		void *	caller_context
	)

Creates an instance of optiga_cmd_t.

Creates an instance of optiga_cmd_t.

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

Precondition

• None

Note

• None

Parameters

[in]	optiga_instance_id	Indicates the OPTIGA configuration to associate with instance.
[in]	handler	Pointer to callback function, must not be NULL.
[in]	caller_context	Pointer to upper layer context.

Return values

optiga_cmd_t	* On successful instance creation.
NULL	Memory allocation failure. Already, OPTIGA_CMD_MAX_REGISTRATIONS number of instances is created.

Here is the call graph for this function:

optiga_cmd_decrypt_asym()

optiga_lib_status_t optiga_cmd_decrypt_asym	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_decrypt_asym_params_t *	params
	)

Decrypts data using OPTIGA RSA private key.

Decrypts data using OPTIGA RSA private key by issuing Decrypt Asym command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_rsa_decrypt_and_export/optiga_crypt_rsa_decrypt_and_store.
  
• Forms the Decrypt Asym command based on inputs.
• Issues the Decrypt Asym command through optiga_comms_transceive.
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.

Note

• Error codes from lower layers will be returned as it is.

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Decrypt Asym Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Decrypt Asym Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Decrypt Asym command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE. Length of the buffer to copy the decrypted data is less than buffer to copy it into.

Here is the call graph for this function:

optiga_cmd_derive_key()

optiga_lib_status_t optiga_cmd_derive_key	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_derive_key_params_t *	params
	)

Derives a key.

Derives a key by issuing DeriveKey command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_ecdh.
  
• Issues the calculate shared secret command through optiga_comms_transceive.
• Based on the shared secret location in OPTIGA and target storage, it requests to acquire a session.
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
• A key pair should be generated for the input object ID.

Note

• Error codes from lower layers will be returned as it is.

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Derive Key Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of derive key Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking derive key command optiga comms transceive returned a failure Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_INVALID_INPUT	Instance invoked for session oid, without acquiring the session(from optiga_cmd_calc_ssec).
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function:

optiga_cmd_destroy()

optiga_lib_status_t optiga_cmd_destroy

(

optiga_cmd_t *

me

)

Destroys the instance of optiga_cmd_t.

Destroys the instance of optiga_cmd_t.

• Releases any OPTIGA cmd module lock utilized by the instance.
  
• Releases any OPTIGA session acquired by the instance.
  
• De-allocate the memory of the optiga_cmd_t instance.
  

Precondition

• None

Note

• None

Parameters

[in]

me

Valid instance of optiga_cmd_t created using optiga_cmd_create.

Return values

OPTIGA_LIB_SUCCESS

Successful destruction of instance.

Here is the call graph for this function:

optiga_cmd_encrypt_asym()

optiga_lib_status_t optiga_cmd_encrypt_asym	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_encrypt_asym_params_t *	params
	)

Encrypt data using RSA public key.

Encrypts data using RSA public key by issuing Encrypt Asym command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_rsa_encrypt_message/optiga_crypt_rsa_encrypt_session.
  
• Forms the Encrypt Asym command based on inputs.
• Issues the Encrypt Asym command through optiga_comms_transceive.
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.

Note

• Error codes from lower layers will be returned as it is.

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Encrypt Asym Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Encrypt Asym Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Encrypt Asym command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_INVALID_INPUT	Instance invoked for encrypting session, without acquiring the session
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE. Length of the buffer to copy the encrypted data is less than buffer to copy it into.

Here is the call graph for this function:

optiga_cmd_gen_keypair()

optiga_lib_status_t optiga_cmd_gen_keypair	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_gen_keypair_params_t *	params
	)

Generates ECC or RSA key-pair.

Generate ECC/RSA key-pair by issuing Generate KeyPair command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_ecc_generate_keypair/optiga_crypt_rsa_generate_keypair.
  
• Forms the Generate KeyPair command based on inputs.
• Issues the Generate KeyPair command through optiga_comms_transceive.
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.

Note

• Error codes from lower layers will be returned as it is.

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Generate KeyPair Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Generate KeyPair Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Generate KeyPair command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE. Length of the buffer to copy the key is less than actual length of key.

Here is the call graph for this function:

optiga_cmd_get_data_object()

optiga_lib_status_t optiga_cmd_get_data_object	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_get_data_object_params_t *	params
	)

Reads data or metadata of the specified data object.

Reads data or metadata of the specified data object, by issuing the GetDataObject command, based on input parameters.

• Acquires the OPTIGA lock for optiga_util_read_data/optiga_util_read_metadata.
  
• Forms the ReadData/ReadMetaData commands based on inputs.
  
• Issues the ReadData/ReadMetaData command through optiga_comms_transceive.
  
• In case the data to be read by the user is greater than the OPTIGA_MAX_COMMS_BUFFER_SIZE, the data is retrieved by internal chaining (by calling GetDataObject command multiple times).
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
  

Note

• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Get Data Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Get Data Command APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking GetDataObject command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE. Data received from OPTIGA is greater than the buffer size provided by user.

Here is the call graph for this function:

optiga_cmd_get_random()

optiga_lib_status_t optiga_cmd_get_random	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_get_random_params_t *	params
	)

Generates random data or pre-master secret for RSA key exchange.

Generates random data or pre-master secret for RSA key exchange, by issuing the GetRandom command to OPTIGA.

• Acquires the OPTIGA session/lock for optiga_crypt_rsa_generate_pre_master_secret/optiga_crypt_random.
  
• For pre-master secret, it acquires a session, else acquires the lock.
• Forms the GetRandom command based on inputs.
  
• Issues the GetRandom command through optiga_comms_transceive.
  
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
  

Note

• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Get Random Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Get Random Command APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking GetRandom command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function:

optiga_cmd_open_application()

optiga_lib_status_t optiga_cmd_open_application	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		void *	params
	)

Opens the OPTIGA Application.

Opens the OPTIGA Application by issuing the OpenApplication command.

• Acquires the OPTIGA lock for optiga_util_open_application.
  
• Invokes optiga_comms_open API to initialize OPTIGA and to establish the communication channel.
  
• Forms the OpenApplication commands based on inputs.
  
• Issues the OpenApplication command using optiga_comms_transceive.
  
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• None

Note

• This function must be mandatorily invoked before starting any interactions with OPTIGA after the reset.
• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	Secure connection related information, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking OpenApplication command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function:

optiga_cmd_release_lock()

optiga_lib_status_t optiga_cmd_release_lock

(

const optiga_cmd_t *

me

)

Releases the OPTIGA cmd lock.

Releases the OPTIGA cmd lock.

• Release the OPTIGA lock acquired by the instance.
  
• If OPTIGA cmd lock request register in not empty, invoke the next registered caller handler with corresponding context.
  

Precondition

• None

Note

• None

Parameters

[in]

me

Valid instance of optiga_cmd_t created using optiga_cmd_create.

Return values

OPTIGA_CMD_SUCCESS

Successful release of the access layer lock.

Here is the call graph for this function:

optiga_cmd_set_data_object()

optiga_lib_status_t optiga_cmd_set_data_object	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_set_data_object_params_t *	params
	)

Writes data or metadata to the specified data object.

Writes data or metadata to the specified data object, by issuing the SetDataObject command, based on input parameters.

• Acquires the OPTIGA lock for optiga_util_write_data/optiga_util_write_metadata.
  
• Forms the SetData/SetMetaData commands based on inputs.
  
• Issues the SetData/SetMetaData command through optiga_comms_transceive.
  
• In case the data to be written by the user is greater than the OPTIGA_MAX_COMMS_BUFFER_SIZE, the data is written to the OPTIGA by internal chaining (by calling SetDataObject command multiple times).
  
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
  

Note

• In case of failure, it is possible that partial data is written into the data object.
  In such a case, the user should decide if the data has to be re-written.
• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Set Data Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Set Data Command APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking SetDataObject command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function:

optiga_cmd_set_object_protected()

optiga_lib_status_t optiga_cmd_set_object_protected	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_set_object_protected_params_t *	params
	)

Writes protected object fragments to OPTIGA.

Writes manifest or data fragement(s) to the specified data object, by issuing the SetObjectProtected command, in a securely.

• Acquires the strict sequence for optiga_util_protected_update_start.
  
• Forms the SetObjectProtected commands based on inputs.
  
• Issues the SetObjectProtected command through optiga_comms_transceive.
  
• Releases the strict sequence in case of an error or after optiga_util_protected_update_final is successfully completed.

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
  

Note

• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of Set Object Protected APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Set Object Protected APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking SetObjectProtected command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.
OPTIGA_CMD_ERROR_INVALID_INPUT	Continue and final APDU command invoked without strict lock acquired for the instance.

Release the strict sequence

Here is the call graph for this function:

optiga_cmd_verify_sign()

optiga_lib_status_t optiga_cmd_verify_sign	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_verify_sign_params_t *	params
	)

Verifies the signature over the given digest.

Verifies the signature over the given digest by issuing VerifySign command.

• Acquires the OPTIGA lock for optiga_crypt_ecdsa_verify/optiga_crypt_rsa_verify.
  
• Forms the VerifySign command based on inputs and invokes the optiga_comms_transceive to send the same to OPTIGA.
• Releases the OPTIGA lock on successful completion of asynchronous operation.
  

Precondition

• Application on OPTIGA must be opened using optiga_cmd_open_application before using this API.
  

Note

• Error codes from lower layers will be returned as it is.
  

Parameters

[in]	me	Valid instance of optiga_cmd_t created using optiga_cmd_create.
[in]	cmd_param	Param of VerifySign Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	Parameters for InData of VerifySign Command APDU, must not be NULL.

Return values

OPTIGA_CMD_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking VerifySign command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	APDU length formed is greater than OPTIGA_MAX_COMMS_BUFFER_SIZE.

Here is the call graph for this function: