Infineon OPTIGA(TM) Trust X crypt module APIs. More...

Data Structures
struct	optiga_hash_context
	To specify the hash context information. More...
struct	hash_data_from_host
	To specify the data coming from the host for hashing. More...
struct	hash_data_in_optiga
	To specify the data object for hashing. More...
struct	public_key_from_host
	To specifiy the Public Key details (key, size and algorithm) More...
struct	key_from_opitga
	To specify the OID which holds the shared secret. More...

Macros
#define	OPTIGA_CRYPT_SUCCESS (0x0000)
	OPTIGA crypt API execution is successful. More...
#define	OPTIGA_CRYPT_BUSY (0x0001)
	OPTIGA crypt module in busy state.
#define	OPTIGA_CRYPT_ERROR (0x0402)
	OPTIGA crypt API failed.
#define	OPTIGA_CRYPT_ERROR_INVALID_INPUT (0x0403)
	OPTIGA crypt API called with invalid inputs.
#define	OPTIGA_CRYPT_ERROR_MEMORY_INSUFFICIENT (0x0404)
	OPTIGA crypt API called with insufficient memory buffer.
#define	OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE (0x0405)
	OPTIGA crypt API called when, a request of same instance is already in service.
#define	OPTIGA_CRYPT_HOST_DATA (0x01)
	Data is provided by host.
#define	OPTIGA_CRYPT_OID_DATA (0x00)
	Data in internal to optiga OID.

Typedefs
typedef enum optiga_key_id	optiga_key_id_t
	Typedef for Key IDs The KEY_STORE_ID_xxx holds only private key. More...
typedef enum optiga_rng_types	optiga_rng_types_t
typedef enum optiga_ecc_curve	optiga_ecc_curve_t
typedef enum optiga_key_usage	optiga_key_usage_t
typedef struct optiga_hash_context	optiga_hash_context_t
	To specify the hash context information.
typedef enum optiga_hash_type	optiga_hash_type_t
	Specifies the hashing algorithm type in OPTIGA.
typedef struct hash_data_from_host	hash_data_from_host_t
	To specify the data coming from the host for hashing.
typedef struct hash_data_in_optiga	hash_data_in_optiga_t
	To specify the data object for hashing.
typedef struct public_key_from_host	public_key_from_host_t
	To specifiy the Public Key details (key, size and algorithm)
typedef struct key_from_opitga	optiga_shared_secret_t
	To specify the OID which holds the shared secret.

Enumerations
enum	optiga_key_id { OPTIGA_KEY_STORE_ID_E0F0 = 0xE0F0, OPTIGA_KEY_STORE_ID_E0F1 = 0xE0F1, OPTIGA_KEY_STORE_ID_E0F2 = 0xE0F2, OPTIGA_KEY_STORE_ID_E0F3 = 0xE0F3, OPTIGA_SESSION_ID_E100 = 0xE100, OPTIGA_SESSION_ID_E101 = 0xE101, OPTIGA_SESSION_ID_E102 = 0xE102, OPTIGA_SESSION_ID_E103 = 0xE103 }
	Typedef for Key IDs The KEY_STORE_ID_xxx holds only private key. More...
enum	optiga_rng_types { OPTIGA_RNG_TYPE_TRNG = 0x00, OPTIGA_RNG_TYPE_DRNG = 0x01 }
enum	optiga_ecc_curve { OPTIGA_ECC_NIST_P_256 = 0x03, OPTIGA_ECC_NIST_P_384 = 0x04 }
enum	optiga_key_usage { OPTIGA_KEY_USAGE_AUTHENTICATION = 0x01, OPTIGA_KEY_USAGE_SIGN = 0x10, OPTIGA_KEY_USAGE_KEY_AGREEMENT = 0x20 }
enum	optiga_hash_type { OPTIGA_HASH_TYPE_SHA_256 = 0xE2 }
	Specifies the hashing algorithm type in OPTIGA. More...

Functions
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_random ( optiga_rng_types_t rng_type, uint8_t *random_data, uint16_t random_data_length)
	Generates a random number. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hash_start ( optiga_hash_context_t *hash_ctx)
	Initializes a hash context. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hash_update ( optiga_hash_context_t *hash_ctx, uint8_t source_of_data_to_hash, void *data_to_hash)
	Updates a hash context with the input data. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hash_finalize ( optiga_hash_context_t *hash_ctx, uint8_t *hash_output)
	Finalizes and exports the hash output. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_ecc_generate_keypair (optiga_ecc_curve_t curve_id, uint8_t key_usage, bool_t export_private_key, void *private_key, uint8_t *public_key, uint16_t *public_key_length)
	Generates an key pair based on ECC curves. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_ecdsa_sign (uint8_t *digest, uint8_t digest_length, optiga_key_id_t private_key, uint8_t *signature, uint16_t *signature_length)
	Generates a signature for the given digest. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_ecdsa_verify (uint8_t *digest, uint8_t digest_length, uint8_t *signature, uint16_t signature_length, uint8_t public_key_source_type, void *public_key)
	Verifies the signature over the given digest. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_ecdh ( optiga_key_id_t private_key, public_key_from_host_t *public_key, bool_t export_to_host, uint8_t *shared_secret)
	Calculates the shared secret using ECDH algorithm. More...
LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_tls_prf_sha256 (uint16_t secret, uint8_t *label, uint16_t label_length, uint8_t *seed, uint16_t seed_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t *derived_key)
	Derives a key. More...

Detailed Description

Infineon OPTIGA(TM) Trust X crypt module APIs.

Macro Definition Documentation

#define OPTIGA_CRYPT_SUCCESS   (0x0000)

OPTIGA crypt API execution is successful.

OPTIGA crypt module return values

Typedef Documentation

typedef enum optiga_key_id optiga_key_id_t

Typedef for Key IDs The KEY_STORE_ID_xxx holds only private key.

The SESSION_ID_xxx can hold private key, premaster secret(ECDH) and master secret(PRF). But only one at a time.

typedef enum optiga_rng_types optiga_rng_types_t

OPTIGA Random Generation types

Enumeration Type Documentation

enum optiga_hash_type

Specifies the hashing algorithm type in OPTIGA.

Enumerator
OPTIGA_HASH_TYPE_SHA_256	Hash algorithm type SHA256.

enum optiga_key_id

Typedef for Key IDs The KEY_STORE_ID_xxx holds only private key.

The SESSION_ID_xxx can hold private key, premaster secret(ECDH) and master secret(PRF). But only one at a time.

Enumerator
OPTIGA_KEY_STORE_ID_E0F0	Key from key store (non-volatile)
OPTIGA_KEY_STORE_ID_E0F1	Key from key store (non-volatile)
OPTIGA_KEY_STORE_ID_E0F2	Key from key store (non-volatile)
OPTIGA_KEY_STORE_ID_E0F3	Key from key store (non-volatile)
OPTIGA_SESSION_ID_E100	Key from Session context id 1 (volatile)
OPTIGA_SESSION_ID_E101	Key from Session context id 2 (volatile)
OPTIGA_SESSION_ID_E102	Key from Session context id 3 (volatile)
OPTIGA_SESSION_ID_E103	Key from Session context id 4 (volatile)

enum optiga_key_usage

Enumerator
OPTIGA_KEY_USAGE_AUTHENTICATION	This enables the private key for the signature generation as part of authentication commands.
OPTIGA_KEY_USAGE_SIGN	This enables the private key for the signature generation.
OPTIGA_KEY_USAGE_KEY_AGREEMENT	This enables the private key for key agreement (e.g. ecdh operations)

enum optiga_rng_types

OPTIGA Random Generation types

Enumerator
OPTIGA_RNG_TYPE_TRNG	Generate Random data using TRNG.
OPTIGA_RNG_TYPE_DRNG	Generate Random data using DRNG.

Function Documentation

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecc_generate_keypair	(	optiga_ecc_curve_t	curve_id ,
		uint8_t	key_usage ,
		bool_t	export_private_key ,
		void *	private_key ,
		uint8_t *	public_key ,
		uint16_t *	public_key_length
	)

Generates an key pair based on ECC curves.

Generates an ECC key-pair based on the type of the key.

Pre Conditions:

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

API Details:

• Generate an ECC key pair using OPTIGA.
  
• If export is requested, Exports the private key else stores it in the input private key OID.
  
• Exports the public key always.
  
  

Notes:

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

Parameters

[in]	curve_id	ECC curve id.
[in]	key_usage	Key usage defined by optiga_key_usage_t. Values from optiga_key_usage can be logically ORed and passed. It is ignored if export_private_key is FALSE (0).
[in]	export_private_key	TRUE (1) - Exports both private key and public key to the host. FALSE (0) - Exports only public key to the host. The input key_usage is ignored.
[in]	private_key	Buffer to store private key or private key OID of OPTIGA, must not be NULL. If export_private_key is TRUE, assign pointer to a buffer to store private key. The size of the buffer must be sufficient enough to accommodate the key type and additional DER encoding formats. If export_private_key is FALSE, assign pointer to variable of type optiga_key_id_t.
[in,out]	public_key	Buffer to store public key, must not be NULL.
[in]	public_key_length	Initially set as length of public_key, later updated as actual length of public_key.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdh	(	optiga_key_id_t	private_key ,
		public_key_from_host_t *	public_key ,
		bool_t	export_to_host ,
		uint8_t *	shared_secret
	)

Calculates the shared secret using ECDH algorithm.

Calculates the shared secret using ECDH algorithm.

Pre Conditions:

• The application on OPTIGA must be opened using optiga_util_open_application.
  
• There must be a secret available in the "session context / data object OID" provided as input parameter.
  

API Details:

• Calculates the shared secret based on input private key object ID and public key.
  
• Based on user request(export_to_host), the shared secret can either be exported to the host or be stored in the acquired session object ID.
  
  

Notes:

• Error codes from lower layers will be returned as it is.
  
• The buffer size for shared secret should be appropriately provided by the user
• If the user provides private_key as session based and export_to_host as FALSE,
  then the shared secret generated will overwrite the private key stored in the session object ID

Parameters

[in]	private_key	Object ID of the private key stored in OPTIGA. Possible values are from the optiga_key_id_t Argument check for private_key is not done since OPTIGA will provide an error for invalid private_key.
[in]	public_key	Pointer to the public key structure for shared secret generation with its properties, must not be NULL. Provide the inputs according to the structure type public_key_from_host_t
[in]	export_to_host	TRUE (1) - Exports the generated shared secret to Host. FALSE (0) - Stores the generated shared secret into the session object ID acquired by the instance.
[in,out]	shared_secret	Pointer to the shared secret buffer, only if export_to_host is TRUE. Otherwise supply NULL as input.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdsa_sign	(	uint8_t *	digest ,
		uint8_t	digest_length ,
		optiga_key_id_t	private_key ,
		uint8_t *	signature ,
		uint16_t *	signature_length
	)

Generates a signature for the given digest.

Generates a signature for the given digest using private key stored in OPTIGA.

Pre Conditions:

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

API Details:

• Generated signature for the input digest.
  
• Exports the generated signature.
  
  

Notes:

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

Parameters

[in]	digest	Digest on which signature is generated.
[in]	digest_length	Length of the input digest.
[in]	private_key	Private key OID to generate signature.
[in,out]	signature	Generated signature, must not be NULL. The size of the buffer must be sufficient enough to accommodate the additional DER encoding formatting for R and S components of signature.
[in]	signature_length	Length of signature.Intial value set as length of buffer, later updated as the actual length of generated signature.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdsa_verify	(	uint8_t *	digest ,
		uint8_t	digest_length ,
		uint8_t *	signature ,
		uint16_t	signature_length ,
		uint8_t	public_key_source_type ,
		void *	public_key
	)

Verifies the signature over the given digest.

Verifies the signature over a given digest provided with the input data.

Pre Conditions:

• The application on OPTIGA must be opened using optiga_util_open_application.
  

API Details:

• Verifies the signature over the given provided with the input data using public key.

Notes:

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

Parameters

[in]	digest	Pointer to a given digest buffer, must not be NULL.
[in]	digest_length	Length of digest
[in]	signature	Pointer to a given signature buffer, must not be NULL.
[in]	signature_length	Length of signature
[in]	public_key_source_type	Public key from host / public key of certificate OID from OPTIGA. Value must be one of the below OPTIGA_CRYPT_OID_DATA, if the public key is to used from the certificate data object from OPTIGA. OPTIGA_CRYPT_HOST_DATA, if the public key is provided by host.
[in]	public_key	Public key from host / public key of certificate OID. Value must be one of the below For certificate OID, pointer OID value must be passed. For Public key from host, pointer to public_key_from_host_t instance.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_finalize	(	optiga_hash_context_t *	hash_ctx ,
		uint8_t *	hash_output
	)

Finalizes and exports the hash output.

Finalizes the hash context and returns hash as output.

Pre Conditions:

• The application on OPTIGA must be opened using optiga_util_open_application before using this API.
  
• optiga_hash_context_t from optiga_crypt_hash_start or optiga_crypt_hash_update must be available.

API Details:

• Finalize the hash from the input hash context
• Exports the finalized hash.

Notes:

• Error codes from lower layer will be returned as it is.
  
• hash context is not updated by this API. This can be used later to fulfill intermediate hash use-cases
  
• User must save the output hash context for further usage as OPTIGA does not store it internally.
  

Parameters

[in]	hash_ctx	Pointer to optiga_hash_context_t containing hash context from OPTIGA, must not be NULL
[in,out]	hash_output	Output Hash

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_start

(

optiga_hash_context_t *

hash_ctx

)

Initializes a hash context.

Sets up a hash context and exports it.

Pre Conditions:

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

API Details:

• Initializes a new hash context.
  
• Exports the hash context to caller.
  

Notes:

• Error codes from lower layer will be returned as it is.
  
• User must save the output hash context for further usage as OPTIGA does not store it internally.
  

Parameters

[in,out]

hash_ctx

Pointer to optiga_hash_context_t to store the hash context from OPTIGA The input hash_algo in hash_ctx must be from optiga_hash_type.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_update	(	optiga_hash_context_t *	hash_ctx ,
		uint8_t	source_of_data_to_hash ,
		void *	data_to_hash
	)

Updates a hash context with the input data.

Updates hashing for the given data and hash context then export the updated hash context.

Pre Conditions:

• The application on OPTIGA must be opened using optiga_util_open_application before using this API.
  
• optiga_hash_context_t from optiga_crypt_hash_start or optiga_crypt_hash_update must be available.

API Details:

• Update the input hash context.
  
• Exports the hash context to caller.
  

Notes:

• Error codes from lower layer will be returned as it is.
  
• User must save the output hash context for further usage as OPTIGA does not store it internally.
  

Parameters

[in]	hash_ctx	Pointer to optiga_hash_context_t containing hash context from OPTIGA, must not be NULL
[in]	source_of_data_to_hash	Data from host / Data in optiga. Must be one of the below OPTIGA_CRYPT_HOST_DATA,if source of data is from Host. OPTIGA_CRYPT_OID_DATA,if the source of data is from OPITGA.
[in]	data_to_hash	Data for hashing either in hash_data_from_host or in hash_data_in_optiga

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_random	(	optiga_rng_types_t	rng_type ,
		uint8_t *	random_data ,
		uint16_t	random_data_length
	)

Generates a random number.

Generates the requested random stream of data for the user provided length.

Pre Conditions:

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

API Details:

• Invokes optiga_cmd_get_random API, based on the input arguments to retrieve random data .
  
  

Notes:

• Error codes from lower layers will be returned as it is.
  
• The maximum value of the random_data_length parameter is size of buffer random_data . In case the value is greater than buffer size, memory corruption can occur.
  

Parameters

[in]	rng_type	Type of random data generator. The input must be from optiga_rng_type. Argument check for rng_type is not done since OPTIGA will provide an error for invalid rng_type.
[in,out]	random_data	Pointer to the buffer into which random data is stored, must not be NULL.
[in]	random_data_length	Length of random data to be generated. Range should be 8 - 256 bytes. Length validation is not done, since OPTIGA will provide an error for invalid random_data_length.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_tls_prf_sha256	(	uint16_t	secret ,
		uint8_t *	label ,
		uint16_t	label_length ,
		uint8_t *	seed ,
		uint16_t	seed_length ,
		uint16_t	derived_key_length ,
		bool_t	export_to_host ,
		uint8_t *	derived_key
	)

Derives a key.

Derives a key using the secret stored in OPTIGA.

Pre Conditions:

• The application on OPTIGA must be opened using optiga_util_open_application.
  
• There must be a secret available in the "session context / data object OID" provided as input parameter.
  
• An instance of optiga_crypt_t must be created using the optiga_crypt_create API.

API Details:

• Derives a key using the secret stored in OPTIGA.
• Provides the options to store the derived key into OPTIGA session context or export to the host.
• It invokes the callback handler of the instance, when it is asynchronously completed.

Notes:

• At present, the minimum length of the output derived key is 16.
• Error codes from lower layers will be returned as it is to the application.
  

Parameters

[in]	secret	Object ID of the secret stored in OPTIGA. OPTIGA_KEY_ID_SESSION_BASED from optiga_key_id_t, indicates the secret is available. in the session context acquired by the instance. or any OPTIGA data object ID(16 bit OID) which holds the secret.
[in]	label	Pointer to the label, can be NULL if not applicable.
[in]	label_length	Length of the label.
[in]	seed	Valid pointer to the seed, must not be NULL.
[in]	seed_length	Length of the seed.
[in]	derived_key_length	Length of derived key.
[in]	export_to_host	TRUE (1) - Exports the derived key to Host. FALSE (0) - Stores the derived key into the session object ID acquired by the instance.
[in,out]	derived_key	Pointer to the valid buffer with a minimum size of derived_key_length, in case of exporting the key to host( export_to_host= TRUE ). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	Same instance with ongoing request servicing is used
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)