optiga_cmd.h File Reference

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

#include "optiga/common/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.

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...
optiga_lib_status_t	optiga_cmd_encrypt_sym (optiga_cmd_t *me, uint8_t cmd_param, optiga_encrypt_sym_params_t *params)
	Encrypt data using optiga_symmetric_encryption_mode_t encryption scheme. More...
optiga_lib_status_t	optiga_cmd_decrypt_sym (optiga_cmd_t *me, uint8_t cmd_param, optiga_decrypt_sym_params_t *params)
	Decrypt data using optiga_symmetric_encryption_mode_t encryption scheme. More...
optiga_lib_status_t	optiga_cmd_gen_symkey (optiga_cmd_t *me, uint8_t cmd_param, optiga_gen_symkey_params_t *params)
	Generate symmetric key using OPTIGA. More...

Detailed Description

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

Author

Infineon Technologies AG

Definition in file optiga_cmd.h.

Typedef Documentation

optiga_cmd_t

typedef struct optiga_cmd optiga_cmd_t

OPTIGA command instance structure type.

Definition at line 1 of file optiga_cmd.h.

optiga_context_t

typedef struct optiga_context optiga_context_t

OPTIGA comms instance structure type.

Definition at line 1 of file optiga_cmd.h.

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.

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.

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.

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.

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.

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.

optiga_cmd_decrypt_sym()

optiga_lib_status_t optiga_cmd_decrypt_sym	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_decrypt_sym_params_t *	params
	)

Decrypt data using optiga_symmetric_encryption_mode_t encryption scheme.

Decrypts data using selected encryption scheme by issuing Decrypt Sym command to OPTIGA.

• Acquires the strict sequence.
• Forms the Decrypt Sym command based on inputs.
• Issues the Decrypt Sym command through optiga_comms_transceive.
• Releases the strict sequence in case of an error or after optiga_crypt_symmetric_decrypt_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 Decrypt Sym Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Decrypt Sym Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Encrypt Sym command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_INVALID_INPUT	Continue and final APDU command invoked without strict lock acquired for the instance.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. Length of the buffer to copy the encrypted data is less than buffer to copy it into.

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.

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.

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.

optiga_cmd_encrypt_sym()

optiga_lib_status_t optiga_cmd_encrypt_sym	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_encrypt_sym_params_t *	params
	)

Encrypt data using optiga_symmetric_encryption_mode_t encryption scheme.

Encrypts data using selected encryption scheme by issuing Encrypt Sym command to OPTIGA.

• Acquires the strict sequence.
• Forms the Encrypt Sym command based on inputs.
• Issues the Encrypt Sym command through optiga_comms_transceive.
• Releases the strict sequence in case of an error or after optiga_crypt_symmetric_encrypt_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 Encrypt Sym Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Encrypt Sym Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Encrypt Sym command. Error in the asynchronous state machine.
OPTIGA_CMD_ERROR_INVALID_INPUT	Continue and final APDU command invoked without strict lock acquired for the instance.
OPTIGA_CMD_ERROR_MEMORY_INSUFFICIENT	Error due to insufficient buffer size. Length of the buffer to copy the encrypted data is less than buffer to copy it into.

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.

optiga_cmd_gen_symkey()

optiga_lib_status_t optiga_cmd_gen_symkey	(	optiga_cmd_t *	me,
		uint8_t	cmd_param,
		optiga_gen_symkey_params_t *	params
	)

Generate symmetric key using OPTIGA.

Generate symmetric key by issuing Generate Symmetric Key command to OPTIGA.

• Acquires the OPTIGA lock for optiga_crypt_symmetric_generate_key.
  
• Forms the Generate Symmetric Key command based on inputs.
• Issues the Generate Symmetric Key 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 Gen Sym Key Command APDU. Must be valid argument, otherwise OPTIGA returns an error.
[in]	params	InData of Gen Sym Key Command APDU, must not be NULL.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CMD_ERROR	Error occurred before invoking Gen Sym Key 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.

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.

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.

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.

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.

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.

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.

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.