This file implements the prototype declarations of OPTIGA Crypt module. More...

#include "optiga/cmd/optiga_cmd.h"

Include dependency graph for optiga_crypt.h:

Data Structures
union	optiga_crypt_params
	union for OPTIGA crypt parameters More...

struct	optiga_crypt
	OPTIGA crypt instance structure. More...

#define	OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL(p_instance, protection_level) {}
	Enables the protected I2C communication with OPTIGA for CRYPT instances. More...

#define	OPTIGA_CRYPT_SET_COMMS_PROTOCOL_VERSION(p_instance, version) {}
	Select the protocol version required for the I2C protected communication for CRYPT instances. More...

typedef union optiga_crypt_params	optiga_crypt_params_t
	union for OPTIGA crypt parameters More...

typedef struct optiga_crypt	optiga_crypt_t
	OPTIGA crypt instance structure type. More...

LIBRARY_EXPORTS optiga_crypt_t *	optiga_crypt_create (uint8_t optiga_instance_id, callback_handler_t handler, void *caller_context)
	Create an instance of optiga_crypt_t. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_destroy (optiga_crypt_t *me)
	Destroys an instance of optiga_crypt_t. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_random (optiga_crypt_t me, optiga_rng_type_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 (optiga_crypt_t me, optiga_hash_type_t hash_algorithm, uint8_t source_of_data_to_hash, const void data_to_hash, uint8_t *hash_output)
	Updates a hashing for input data and returns digest. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hash_start (optiga_crypt_t me, optiga_hash_context_t hash_ctx)
	Initializes a hash context. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hash_update (optiga_crypt_t me, optiga_hash_context_t hash_ctx, uint8_t source_of_data_to_hash, const void *data_to_hash)
	Updates a hash context with the input data. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hash_finalize (optiga_crypt_t me, 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_crypt_t me, 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 a key pair based on ECC curves. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_ecdsa_sign (optiga_crypt_t me, const 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 (optiga_crypt_t me, const uint8_t digest, uint8_t digest_length, const uint8_t signature, uint16_t signature_length, uint8_t public_key_source_type, const void public_key)
	Verifies the signature over the given digest. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_ecdh (optiga_crypt_t me, 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 (optiga_crypt_t me, optiga_tls_prf_type_t type, uint16_t secret, const uint8_t label, uint16_t label_length, const 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...

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_tls_prf_sha256 (optiga_crypt_t me, uint16_t secret, const uint8_t label, uint16_t label_length, const uint8_t seed, uint16_t seed_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key using TLS PRF SHA256. More...

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_tls_prf_sha384 (optiga_crypt_t me, uint16_t secret, const uint8_t label, uint16_t label_length, const uint8_t seed, uint16_t seed_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key using TLS PRF SHA384. More...

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_tls_prf_sha512 (optiga_crypt_t me, uint16_t secret, const uint8_t label, uint16_t label_length, const uint8_t seed, uint16_t seed_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key using TLS PRF SHA512. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_generate_keypair (optiga_crypt_t me, optiga_rsa_key_type_t key_type, uint8_t key_usage, bool_t export_private_key, void private_key, uint8_t public_key, uint16_t public_key_length)
	Generates a key pair based on RSA key type. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_sign (optiga_crypt_t me, optiga_rsa_signature_scheme_t signature_scheme, const uint8_t digest, uint8_t digest_length, optiga_key_id_t private_key, uint8_t signature, uint16_t signature_length, uint16_t salt_length)
	Generates a RSA signature for the given digest based on the input signature scheme. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_verify (optiga_crypt_t me, optiga_rsa_signature_scheme_t signature_scheme, const uint8_t digest, uint8_t digest_length, const uint8_t signature, uint16_t signature_length, uint8_t public_key_source_type, const void public_key, uint16_t salt_length)
	Verifies the RSA signature over the given digest. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_generate_pre_master_secret (optiga_crypt_t me, const uint8_t optional_data, uint16_t optional_data_length, uint16_t pre_master_secret_length)
	Generates a pre-master secret. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_encrypt_message (optiga_crypt_t me, optiga_rsa_encryption_scheme_t encryption_scheme, const uint8_t message, uint16_t message_length, const uint8_t label, uint16_t label_length, uint8_t public_key_source_type, const void public_key, uint8_t encrypted_message, uint16_t encrypted_message_length)
	Encrypts message using RSA public key. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_encrypt_session (optiga_crypt_t me, optiga_rsa_encryption_scheme_t encryption_scheme, const uint8_t label, uint16_t label_length, uint8_t public_key_source_type, const void public_key, uint8_t encrypted_message, uint16_t *encrypted_message_length)
	Encrypts session data using RSA public key. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_decrypt_and_export (optiga_crypt_t me, optiga_rsa_encryption_scheme_t encryption_scheme, const uint8_t encrypted_message, uint16_t encrypted_message_length, const uint8_t label, uint16_t label_length, optiga_key_id_t private_key, uint8_t message, uint16_t *message_length)
	Decrypts input data using OPTIGA private key and export it to the host. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_rsa_decrypt_and_store (optiga_crypt_t me, optiga_rsa_encryption_scheme_t encryption_scheme, const uint8_t encrypted_message, uint16_t encrypted_message_length, const uint8_t *label, uint16_t label_length, optiga_key_id_t private_key)
	Decrypts input data using OPTIGA private key and stores it in a OPTIGA session. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_encrypt (optiga_crypt_t me, optiga_symmetric_encryption_mode_t encryption_mode, optiga_key_id_t symmetric_key_oid, const uint8_t plain_data, uint32_t plain_data_length, const uint8_t iv, uint16_t iv_length, const uint8_t associated_data, uint16_t associated_data_length, uint8_t encrypted_data, uint32_t encrypted_data_length)
	Encrypt the data using symmetric encryption mode and export encrypted message to host. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_encrypt_ecb (optiga_crypt_t me, optiga_key_id_t symmetric_key_oid, const uint8_t plain_data, uint32_t plain_data_length, uint8_t encrypted_data, uint32_t encrypted_data_length)
	Encrypt the data using symmetric encryption scheme using ECB mode of operation. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_encrypt_start (optiga_crypt_t me, optiga_symmetric_encryption_mode_t encryption_mode, optiga_key_id_t symmetric_key_oid, const uint8_t plain_data, uint32_t plain_data_length, const uint8_t iv, uint16_t iv_length, const uint8_t associated_data, uint16_t associated_data_length, uint16_t total_plain_data_length, uint8_t encrypted_data, uint32_t encrypted_data_length)
	Initiates a symmetric encryption sequence for input data using symmetric key from OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_encrypt_continue (optiga_crypt_t me, const uint8_t plain_data, uint32_t plain_data_length, uint8_t encrypted_data, uint32_t encrypted_data_length)
	Encrypts input data using symmetric key from OPTIGA and exports block aligned encrypted data. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_encrypt_final (optiga_crypt_t me, const uint8_t plain_data, uint32_t plain_data_length, uint8_t encrypted_data, uint32_t encrypted_data_length)
	Encrypts input data using symmetric key from OPTIGA, exports block aligned encrypted data and completes the encryption sequence. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_decrypt (optiga_crypt_t me, optiga_symmetric_encryption_mode_t encryption_mode, optiga_key_id_t symmetric_key_oid, const uint8_t encrypted_data, uint32_t encrypted_data_length, const uint8_t iv, uint16_t iv_length, const uint8_t associated_data, uint16_t associated_data_length, uint8_t plain_data, uint32_t plain_data_length)
	Decrypt the encrypted data using symmetric encryption mode and export plain message to host. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_decrypt_ecb (optiga_crypt_t me, optiga_key_id_t symmetric_key_oid, const uint8_t encrypted_data, uint32_t encrypted_data_length, uint8_t plain_data, uint32_t plain_data_length)
	Decrypt the data using symmetric encryption scheme using ECB mode of operation. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_decrypt_start (optiga_crypt_t me, optiga_symmetric_encryption_mode_t encryption_mode, optiga_key_id_t symmetric_key_oid, const uint8_t encrypted_data, uint32_t encrypted_data_length, const uint8_t iv, uint16_t iv_length, const uint8_t associated_data, uint16_t associated_data_length, uint16_t total_encrypted_data_length, uint8_t plain_data, uint32_t plain_data_length)
	Initiate symmetric decryption sequence for input data using symmetric key from OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_decrypt_continue (optiga_crypt_t me, const uint8_t encrypted_data, uint32_t encrypted_data_length, uint8_t plain_data, uint32_t plain_data_length)
	Decrypts input encrypted data using symmetric key from OPTIGA and exports block aligned plain data. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_decrypt_final (optiga_crypt_t me, const uint8_t encrypted_data, uint32_t encrypted_data_length, uint8_t plain_data, uint32_t plain_data_length)
	Decrypts input data using symmetric key from OPTIGA, exports block aligned plain data and completes the decryption sequence. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hmac (optiga_crypt_t me, optiga_hmac_type_t type, uint16_t secret, const uint8_t input_data, uint32_t input_data_length, uint8_t mac, uint32_t mac_length)
	Generates HMAC on the input message using input secret from OPTIGA and exports the generated HMAC to the host. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hmac_start (optiga_crypt_t me, optiga_hmac_type_t type, uint16_t secret, const uint8_t input_data, uint32_t input_data_length)
	Initiates a HMAC generation sequence for the input data using input secret from OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hmac_update (optiga_crypt_t me, const uint8_t input_data, uint32_t input_data_length)
	Generates HMAC on the input message using input secret from OPTIGA, update the previously generated HMAC value internally. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hmac_finalize (optiga_crypt_t me, const uint8_t input_data, uint32_t input_data_length, uint8_t mac, uint32_t mac_length)
	Generates HMAC on the input message using input secret from OPTIGA and exports the finalized HMAC to host. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hkdf (optiga_crypt_t me, optiga_hkdf_type_t type, uint16_t secret, const uint8_t salt, uint16_t salt_length, const uint8_t info, uint16_t info_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key or shared secret using HKDF operation from the secret stored in OPTIGA. More...

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hkdf_sha256 (optiga_crypt_t me, uint16_t secret, const uint8_t salt, uint16_t salt_length, const uint8_t info, uint16_t info_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key or shared secret using HKDF-SHA256 operation from the secret stored in OPTIGA. More...

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hkdf_sha384 (optiga_crypt_t me, uint16_t secret, const uint8_t salt, uint16_t salt_length, const uint8_t info, uint16_t info_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key or shared secret using HKDF-SHA384 operation from the secret stored in OPTIGA. More...

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hkdf_sha512 (optiga_crypt_t me, uint16_t secret, const uint8_t salt, uint16_t salt_length, const uint8_t info, uint16_t info_length, uint16_t derived_key_length, bool_t export_to_host, uint8_t derived_key)
	Derives a key or shared secret using HKDF-SHA512 operation from the secret stored in OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_symmetric_generate_key (optiga_crypt_t me, optiga_symmetric_key_type_t key_type, uint8_t key_usage, bool_t export_symmetric_key, void symmetric_key)
	Generates a symmetric key using OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_generate_auth_code (optiga_crypt_t me, optiga_rng_type_t rng_type, const uint8_t optional_data, uint16_t optional_data_length, uint8_t *random_data, uint16_t random_data_length)
	Generates a random number using OPTIGA and stores the same in acquired session context at OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_hmac_verify (optiga_crypt_t me, optiga_hmac_type_t type, uint16_t secret, const uint8_t input_data, uint32_t input_data_length, const uint8_t *hmac, uint32_t hmac_length)
	Performs the HMAC verification for the provided authorization value using OPTIGA. More...

LIBRARY_EXPORTS optiga_lib_status_t	optiga_crypt_clear_auto_state (optiga_crypt_t *me, uint16_t secret)
	This operation clears the AUTO state at OPTIGA for input secret OID. More...

Detailed Description

This file implements the prototype declarations of OPTIGA Crypt module.

Author: Infineon Technologies AG

Definition in file optiga_crypt.h.

Macro Definition Documentation

◆ OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL

#define OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL	(	p_instance,
		protection_level
	)	{}

Enables the protected I2C communication with OPTIGA for CRYPT instances.

Enables the protected I2C communication with OPTIGA

Sets the protection mode for the supplied instance.
Call this function before calling the service layer API which requires protection.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

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

Parameters

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

Definition at line 2527 of file optiga_crypt.h.

◆ OPTIGA_CRYPT_SET_COMMS_PROTOCOL_VERSION

#define OPTIGA_CRYPT_SET_COMMS_PROTOCOL_VERSION	(	p_instance,
		version
	)	{}

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

Select the protocol version required for the I2C protected communication

Select the protocol version for the supplied instance.

Precondition

OPTIGA_COMMS_SHIELDED_CONNECTION macro must be defined.

Note

None

Parameters

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

Definition at line 2555 of file optiga_crypt.h.

Typedef Documentation

◆ optiga_crypt_params_t

typedef union optiga_crypt_params optiga_crypt_params_t

union for OPTIGA crypt parameters

◆ optiga_crypt_t

typedef struct optiga_crypt optiga_crypt_t

OPTIGA crypt instance structure type.

Definition at line 1 of file optiga_crypt.h.

Function Documentation

◆ optiga_crypt_clear_auto_state()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_clear_auto_state	(	optiga_crypt_t *	me,
		uint16_t	secret
	)

This operation clears the AUTO state at OPTIGA for input secret OID.

Clears the AUTO state and session if it's already acquired.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments.
Acquired session is released after completion of clear auto state operation.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	secret	OPTIGA OID with input secret. It should be of AUTOREF type

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete

Example
example_optiga_crypt_clear_auto_state.c

◆ optiga_crypt_create()

LIBRARY_EXPORTS optiga_crypt_t* optiga_crypt_create	(	uint8_t	optiga_instance_id,
		callback_handler_t	handler,
		void *	caller_context
	)

Create an instance of optiga_crypt_t.

Stores the callers context and callback handler.
Allocate memory for optiga_crypt_t.

Precondition

None

Note

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

Parameters

[in]	optiga_instance_id	Indicates the OPTIGA instance to be associated with optiga_crypt_t. Should be defined as below: Use OPTIGA_INSTANCE_ID_0.
[in]	handler	Pointer to callback function, must not be NULL.
[in]	caller_context	Pointer to upper layer context. Contains user context data.

Return values

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

◆ optiga_crypt_destroy()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_destroy ( optiga_crypt_t * me )

Destroys an instance of optiga_crypt_t.

Destroys the optiga_crypt_t instance.

De-allocate the memory of the optiga_crypt_t instance.

Precondition

An instance of optiga_crypt using optiga_crypt_create must be available.

Note

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

Parameters

[in] me Valid instance of optiga_crypt_t.

Return values

OPTIGA_LIB_SUCCESS	Successful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete.

◆ optiga_crypt_ecc_generate_keypair()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecc_generate_keypair	(	optiga_crypt_t *	me,
		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 a key pair based on ECC curves.

Generates an ECC key-pair based on the input curve.

Invokes optiga_cmd_gen_keypair API, based on the input arguments.
Generate an ECC key pair using OPTIGA.
Private key is exported only if explicitly requested otherwise it is stored in the input private key OID.
Public key is always exported.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	curve_id	ECC curve id as optiga_ecc_curve.
[in]	key_usage	Key usage defined in optiga_key_usage_t. Values from optiga_key_usage can be logically ORed and passed. It is ignored if export_private_key is TRUE (1).
[in]	export_private_key	TRUE (1) or Non-Zero value - Exports private key to the host. FALSE (0) - Exports only public key to the host and writes private key to OPTIGA. 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 buffer to store public_key, later updated as actual length of public_key.

Return values

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

Example
example_optiga_crypt_ecc_generate_keypair.c

◆ optiga_crypt_ecdh()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdh	(	optiga_crypt_t *	me,
		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

Invokes optiga_cmd_calc_ssec API, based on the input arguments.
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.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
There must be a private key available in the "session context / data object OID" provided as input parameter.
If the private_key type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecc_generate_keypair )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is 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]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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) or Non-Zero value - 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. The size of the buffer shall be equal or more than the key size. Otherwise provide NULL as input.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. Session is not available in instance and the private_key type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecdh.c

◆ optiga_crypt_ecdsa_sign()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdsa_sign	(	optiga_crypt_t *	me,
		const 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.

Invokes optiga_cmd_calc_sign API, based on the input arguments.
Generates signature for the input digest.
Exports the generated signature.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application before using this API.
If the private_key type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecc_generate_keypair )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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	Pointer to store 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,out]	signature_length	Length of signature. Initial value set as length of buffer, later updated as the actual length of generated signature.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. Session is not available in instance and the private_key type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecdsa_sign.c

◆ optiga_crypt_ecdsa_verify()

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

Verifies the signature over the given digest.

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

Invokes optiga_cmd_verify_sign API, based on the input arguments.
Verifies the signature over the given provided with the input data using public key.
It invokes the callback handler of the instance, when it is asynchronously completed.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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 or Non-Zero value , if the public key is provided by host.
[in]	public_key	Public key from host / OID of certificate object. 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
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecdsa_verify.c

◆ optiga_crypt_generate_auth_code()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_generate_auth_code	(	optiga_crypt_t *	me,
		optiga_rng_type_t	rng_type,
		const uint8_t *	optional_data,
		uint16_t	optional_data_length,
		uint8_t *	random_data,
		uint16_t	random_data_length
	)

Generates a random number using OPTIGA and stores the same in acquired session context at OPTIGA.

Generates random stream code for user provided length.

Invokes optiga_cmd_get_random API, based on the input arguments to retrieve random data
Generated random is returned to host .
Generated random and optional data is also stored in the session context acquired at OPTIGA.
Data stored in the acquired session context acquired at OPTIGA is used as an auth code.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.
Minimum length of generated random data is 8 bytes.
Auth Code is a concatenation of optional data and random data.
Maximum length of auth code is 48 bytes.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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]	optional_data	Optional data that gets prepended to the generated random secret. Can be set to NULL, if not required
[in]	optional_data_length	Length of the optional data provided. It is ignored if optional_data is NULL Value can be up to 58 bytes Difference in random data length and optional data length is less than 8 bytes
[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. Minimum range is 8 bytes.

Return values

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

◆ optiga_crypt_hash()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash	(	optiga_crypt_t *	me,
		optiga_hash_type_t	hash_algorithm,
		uint8_t	source_of_data_to_hash,
		const void *	data_to_hash,
		uint8_t *	hash_output
	)

Updates a hashing for input data and returns digest.

Updates hashing for the given data and returns digest.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

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

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	hash_algorithm	Hash algorithm of optiga_hash_type_t.
[in]	source_of_data_to_hash	Data from host / Data in OPTIGA. Must be one of the below OPTIGA_CRYPT_HOST_DATA or Non-Zero value ,if source of data is from Host. OPTIGA_CRYPT_OID_DATA, if the source of data is from OPTIGA.
[in]	data_to_hash	Data for hashing either in hash_data_from_host_t or in hash_data_in_optiga_t
[in,out]	hash_output	Pointer to the valid buffer to store hash output.

Return values

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

Example
example_optiga_crypt_hash.c

◆ optiga_crypt_hash_finalize()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_finalize	(	optiga_crypt_t *	me,
		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.

Invokes optiga_cmd_calc_hash API, based on the input arguments.
Finalize the hash from the input hash context
Exports the finalized hash.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
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]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	hash_ctx	Pointer to optiga_hash_context_t containing hash context from OPTIGA, must not be NULL. The minimum size of the context_buffer must be 209 bytes in optiga_hash_context_t for hash algo OPTIGA_HASH_TYPE_SHA_256.
[in,out]	hash_output	Output Hash.

Return values

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

Example
example_optiga_crypt_hash.c

◆ optiga_crypt_hash_start()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_start	(	optiga_crypt_t *	me,
		optiga_hash_context_t *	hash_ctx
	)

Initializes a hash context.

Sets up a hash context and exports it.

Invokes optiga_cmd_calc_hash API, based on the input arguments.
Initializes a new hash context.
Exports the hash context to caller.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
Error codes from lower layer will be returned as it is.
User must save the output hash context for further usage because OPTIGA does not store it internally.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in,out]	hash_ctx	Pointer to optiga_hash_context_t to store the hash context from OPTIGA. The minimum size of the context_buffer must be 209 bytes in optiga_hash_context_t for hash algo OPTIGA_HASH_TYPE_SHA_256. The input hash_algo in hash_ctx must be from optiga_hash_type.

Return values

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

Example
example_optiga_crypt_hash.c

◆ optiga_crypt_hash_update()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_update	(	optiga_crypt_t *	me,
		optiga_hash_context_t *	hash_ctx,
		uint8_t	source_of_data_to_hash,
		const 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.

Invokes optiga_cmd_calc_hash API, based on the input arguments.
Update the input hash context.
Exports the hash context to caller.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
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]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	hash_ctx	Pointer to optiga_hash_context_t containing hash context from OPTIGA, must not be NULL The minimum size of the context_buffer must be 209 bytes in optiga_hash_context_t for hash algo OPTIGA_HASH_TYPE_SHA_256.
[in]	source_of_data_to_hash	Data from host / Data in optiga. Must be one of the below OPTIGA_CRYPT_HOST_DATA or Non-Zero value ,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.
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_hash.c

◆ optiga_crypt_hkdf()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hkdf	(	optiga_crypt_t *	me,
		optiga_hkdf_type_t	type,
		uint16_t	secret,
		const uint8_t *	salt,
		uint16_t	salt_length,
		const uint8_t *	info,
		uint16_t	info_length,
		uint16_t	derived_key_length,
		bool_t	export_to_host,
		uint8_t *	derived_key
	)

Derives a key or shared secret using HKDF operation from the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
The derived key is either stored in a OPTIGA session context or exported back to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.
If the secret type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecdh )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	type	HKDF scheme as optiga_hkdf_type_t.
[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]	salt	Pointer to buffer containing salt value, can be NULL if not applicable.
[in]	salt_length	Length of salt.
[in]	info	Pointer to buffer containing application specific information, can be NULL if not applicable.
[in]	info_length	Length of info.
[in]	derived_key_length	Length of derived key. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. Session is not available in instance and the secret type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_hkdf.c

Here is the caller graph for this function:

◆ optiga_crypt_hkdf_sha256()

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hkdf_sha256	(	optiga_crypt_t *	me,
		uint16_t	secret,
		const uint8_t *	salt,
		uint16_t	salt_length,
		const uint8_t *	info,
		uint16_t	info_length,
		uint16_t	derived_key_length,
		bool_t	export_to_host,
		uint8_t *	derived_key
	)

Derives a key or shared secret using HKDF-SHA256 operation from the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
The derived key is either stored in a OPTIGA session context or exported back to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.
If the secret type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecdh )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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]	salt	Pointer to buffer containing salt value, can be NULL if not applicable.
[in]	salt_length	Length of salt.
[in]	info	Pointer to buffer containing application specific information, can be NULL if not applicable.
[in]	info_length	Length of info.
[in]	derived_key_length	Length of derived key. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. Session is not available in instance and the secret type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_hkdf.c

Definition at line 2145 of file optiga_crypt.h.

Here is the call graph for this function:

◆ optiga_crypt_hkdf_sha384()

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hkdf_sha384	(	optiga_crypt_t *	me,
		uint16_t	secret,
		const uint8_t *	salt,
		uint16_t	salt_length,
		const uint8_t *	info,
		uint16_t	info_length,
		uint16_t	derived_key_length,
		bool_t	export_to_host,
		uint8_t *	derived_key
	)

Derives a key or shared secret using HKDF-SHA384 operation from the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
The derived key is either stored in a OPTIGA session context or exported back to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.
If the secret type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecdh )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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]	salt	Pointer to buffer containing salt value, can be NULL if not applicable.
[in]	salt_length	Length of salt.
[in]	info	Pointer to buffer containing application specific information, can be NULL if not applicable.
[in]	info_length	Length of info.
[in]	derived_key_length	Length of derived key. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. Session is not available in instance and the secret type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
None

Definition at line 2216 of file optiga_crypt.h.

Here is the call graph for this function:

◆ optiga_crypt_hkdf_sha512()

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hkdf_sha512	(	optiga_crypt_t *	me,
		uint16_t	secret,
		const uint8_t *	salt,
		uint16_t	salt_length,
		const uint8_t *	info,
		uint16_t	info_length,
		uint16_t	derived_key_length,
		bool_t	export_to_host,
		uint8_t *	derived_key
	)

Derives a key or shared secret using HKDF-SHA512 operation from the secret stored in OPTIGA.

Derives a key or shared secret using HKDF-SHA384 operation from the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
The derived key is either stored in a OPTIGA session context or exported back to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.
If the secret type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecdh )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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]	salt	Pointer to buffer containing salt value, can be NULL if not applicable.
[in]	salt_length	Length of salt.
[in]	info	Pointer to buffer containing application specific information, can be NULL if not applicable.
[in]	info_length	Length of info.
[in]	derived_key_length	Length of derived key. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. Session is not available in instance and the secret type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
None

Definition at line 2287 of file optiga_crypt.h.

Here is the call graph for this function:

◆ optiga_crypt_hmac()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hmac	(	optiga_crypt_t *	me,
		optiga_hmac_type_t	type,
		uint16_t	secret,
		const uint8_t *	input_data,
		uint32_t	input_data_length,
		uint8_t *	mac,
		uint32_t *	mac_length
	)

Generates HMAC on the input message using input secret from OPTIGA and exports the generated HMAC to the host.

Generates HMAC on the input message using input secret from OPTIGA and exports the generated HMAC to host.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Generates HMAC on the input data and exports it to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	type	HMAC type
[in]	secret	OPTIGA OID with input secret Input secret must be available at the specified OID. To indicate session OID (already acquired by instance), specify OPTIGA_KEY_ID_SESSION_BASED
[in]	input_data	Pointer to input data for HMAC generation.
[in]	input_data_length	Length of input data for HMAC generation. Must be greater than 0.
[in,out]	mac	Pointer to buffer to store generated HMAC
[in,out]	mac_length	Pointer to length of the mac. Initial value set as length of buffer, later updated as the actual length of generated HMAC. The size of the buffer must be sufficient enough to accommodate the HMAC. If the mac_length is lesser than the length of MAC received from OPTIGA, then first mac_length bytes are only returned. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_hmac.c

◆ optiga_crypt_hmac_finalize()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hmac_finalize	(	optiga_crypt_t *	me,
		const uint8_t *	input_data,
		uint32_t	input_data_length,
		uint8_t *	mac,
		uint32_t *	mac_length
	)

Generates HMAC on the input message using input secret from OPTIGA and exports the finalized HMAC to host.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Generates HMAC on the input data and exports it to host.
Input secret specified in optiga_crypt_hmac_start is used to generate HMAC.
It terminates the strict sequence.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The HMAC sequence must have been initiated, by invoking optiga_crypt_hmac_start, before calling this API.
The data object specified by input secret must have a secret written into it.

Note

For protected I2C communication, value set in optiga_crypt_hmac_start is used in this API.
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated in case of an error from lower layer
Invoking this API without successful completion of optiga_crypt_hmac_start throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	input_data	Pointer to input data for HMAC generation.
[in]	input_data_length	Length of input data for HMAC generation. Must be greater than 0.
[in,out]	mac	Pointer to buffer to store generated HMAC
[in,out]	mac_length	Pointer to length of the mac. Initial value set as length of buffer, later updated as the actual length of generated HMAC. The size of the buffer must be sufficient enough to accommodate the HMAC. If the mac_length is lesser than the length of MAC received from OPTIGA, then first mac_length bytes are only returned. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_hmac.c

◆ optiga_crypt_hmac_start()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hmac_start	(	optiga_crypt_t *	me,
		optiga_hmac_type_t	type,
		uint16_t	secret,
		const uint8_t *	input_data,
		uint32_t	input_data_length
	)

Initiates a HMAC generation sequence for the input data using input secret from OPTIGA.

Initiates a HMAC generation sequence for the input data.

It marks the beginning of a strict sequence. None of the service layer API will be processed until the strict sequence is terminated.
Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Generates HMAC on the input data but does not export it to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION.
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated
- In case of an error from lower layer.
- Same instance is used for other service layer APIs (except optiga_crypt_hmac_update and optiga_crypt_hmac_finalize).

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	type	HMAC type
[in]	secret	OPTIGA OID with input secret Input secret must be available at the specified OID. To indicate session OID (already acquired by instance), specify OPTIGA_KEY_ID_SESSION_BASED
[in]	input_data	Pointer to input data for HMAC generation.
[in]	input_data_length	Length of input data for HMAC generation. Must be greater than 0.

Return values

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

Example
example_optiga_crypt_hmac.c

◆ optiga_crypt_hmac_update()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hmac_update	(	optiga_crypt_t *	me,
		const uint8_t *	input_data,
		uint32_t	input_data_length
	)

Generates HMAC on the input message using input secret from OPTIGA, update the previously generated HMAC value internally.

Generates HMAC on the input message using input secret from OPTIGA and updates the previously generated HMAC value internally.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Generates HMAC on the input data but does not export it to host.
Input secret specified in optiga_crypt_hmac_start is used to generate HMAC.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The HMAC sequence must have been initiated, by invoking optiga_crypt_hmac_start, before calling this API.
The data object specified by input secret must have a secret written into it.

Note

For protected I2C communication, value set in optiga_crypt_hmac_start is used in this API.
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated in case of an error from lower layer
Invoking this API without successful completion of optiga_crypt_hmac_start throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	input_data	Pointer to input data for HMAC generation.
[in]	input_data_length	Length of input data for HMAC generation. Must be greater than 0.

Return values

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

Example
example_optiga_crypt_hmac.c

◆ optiga_crypt_hmac_verify()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hmac_verify	(	optiga_crypt_t *	me,
		optiga_hmac_type_t	type,
		uint16_t	secret,
		const uint8_t *	input_data,
		uint32_t	input_data_length,
		const uint8_t *	hmac,
		uint32_t	hmac_length
	)

Performs the HMAC verification for the provided authorization value using OPTIGA.

Verifies HMAC generated at host with HMAC generated from OPTIGA for the provided authorization value.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments.
Acquired session gets released after completion of hmac verify operation between host and OPTIGA.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The data object specified by input secret must have a secret written into it.
Session has already been acquired by optiga_crypt_generate_auth_code.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	type	HMAC type as optiga_hmac_type_t
[in]	secret	OPTIGA OID with input secret Input secret must be available at the specified OID. Data object type must be AUTOREF.
[in]	input_data	Pointer to input data for HMAC generation. Input data is concatenation of optional data, random and arbitrary data. Optional data is input provided to optiga_crypt_generate_auth_code and random data is returned by optiga_crypt_generate_auth_code.
[in]	input_data_length	Length of input data. Must be greater than 0.
[in]	hmac	Pointer to buffer of HMAC generated at host which gets verified at OPTIGA.
[in]	hmac_length	Length of the generated hmac at host. Host generated hmac length must be the size of output defined in respective hash algorithm used in hmac scheme.

Return values

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

Example
example_optiga_crypt_hmac_verify.c

◆ optiga_crypt_random()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_random	(	optiga_crypt_t *	me,
		optiga_rng_type_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.

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

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is 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]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[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.
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_random.c

◆ optiga_crypt_rsa_decrypt_and_export()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_decrypt_and_export	(	optiga_crypt_t *	me,
		optiga_rsa_encryption_scheme_t	encryption_scheme,
		const uint8_t *	encrypted_message,
		uint16_t	encrypted_message_length,
		const uint8_t *	label,
		uint16_t	label_length,
		optiga_key_id_t	private_key,
		uint8_t *	message,
		uint16_t *	message_length
	)

Decrypts input data using OPTIGA private key and export it to the host.

Decrypts input data using RSA private key from OPTIGA and exports the decrypted data to the host.

Invokes optiga_cmd_decrypt_asym API, based on the input arguments.
Decrypts the input data using a RSA private key.
The RSA private key from OPTIGA is referred by optiga_key_id_t.
Decrypted data is exported back to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.
Error codes from lower layers is returned as it is to the application.
*message_length Initially , it contains the size of buffer provided by user to store the decrypted data. On successful decryption, this value is updated with actual length of the decrypted data.
In case of any error, the value is set to 0.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_scheme	RSA encryption scheme.
[in]	encrypted_message	Pointer to the data to be decrypted.
[in]	encrypted_message_length	Length of the data to be decrypted.
[in]	label	Pointer to a label (Reserved for future use).
[in]	label_length	Length of the label (Reserved for future use).
[in]	private_key	RSA private key in OPTIGA
[in,out]	message	Pointer to buffer to store decrypted message.
[in,out]	message_length	Pointer to length of the decrypted message.

Return values

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

Example
example_optiga_crypt_decrypt.c

◆ optiga_crypt_rsa_decrypt_and_store()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_decrypt_and_store	(	optiga_crypt_t *	me,
		optiga_rsa_encryption_scheme_t	encryption_scheme,
		const uint8_t *	encrypted_message,
		uint16_t	encrypted_message_length,
		const uint8_t *	label,
		uint16_t	label_length,
		optiga_key_id_t	private_key
	)

Decrypts input data using OPTIGA private key and stores it in a OPTIGA session.

Decrypts input data using RSA private key from OPTIGA and stores it in a OPTIGA session.

Invokes optiga_cmd_decrypt_asym API, based on the input arguments.
Decrypts the input data using a RSA private key.
The RSA private key from OPTIGA is referred by optiga_key_id_t.
Stores the decrypted data in the acquired OPTIGA session.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_scheme	RSA encryption scheme.
[in]	encrypted_message	Pointer to the data to be decrypted.
[in]	encrypted_message_length	Length of the data to be decrypted.
[in]	label	Pointer to a label (Reserved for future use).
[in]	label_length	Length of the label (Reserved for future use).
[in]	private_key	RSA private key in OPTIGA.

Return values

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

Example
example_optiga_crypt_decrypt.c

◆ optiga_crypt_rsa_encrypt_message()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_encrypt_message	(	optiga_crypt_t *	me,
		optiga_rsa_encryption_scheme_t	encryption_scheme,
		const uint8_t *	message,
		uint16_t	message_length,
		const uint8_t *	label,
		uint16_t	label_length,
		uint8_t	public_key_source_type,
		const void *	public_key,
		uint8_t *	encrypted_message,
		uint16_t *	encrypted_message_length
	)

Encrypts message using RSA public key.

Encrypts message using RSA public key which is either provided by the host or stored in OPTIGA.

Invokes optiga_cmd_encrypt_asym API, based on the input arguments.
Encrypts the input message using a RSA public key.
The RSA public key either provided by the host or refers to a OID in OPTIGA containing the public key certificate.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is to the application.
encrypted_message_length Initially, it contains the size of buffer provided by user to store the encrypted data. On successful encryption, this value is updated with actual length of the encrypted data.
In case of any error, the value is set to 0.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_scheme	RSA encryption scheme.
[in]	message	Pointer to message to be encrypted.
[in]	message_length	Length of the message to be encrypted.
[in]	label	Pointer to a label (Reserved for future use).
[in]	label_length	Length of the label (Reserved for future use).
[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 be used from the certificate data object from OPTIGA. OPTIGA_CRYPT_HOST_DATA or Non-Zero value , 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 to OID value must be passed. For Public key from host, pointer to public_key_from_host_t instance.
[in,out]	encrypted_message	Pointer to buffer to store encrypted message.
[in,out]	encrypted_message_length	Pointer to length of the encrypted message. Out length is depends on the key size.

Return values

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

Example
example_optiga_crypt_encrypt_message.c

◆ optiga_crypt_rsa_encrypt_session()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_encrypt_session	(	optiga_crypt_t *	me,
		optiga_rsa_encryption_scheme_t	encryption_scheme,
		const uint8_t *	label,
		uint16_t	label_length,
		uint8_t	public_key_source_type,
		const void *	public_key,
		uint8_t *	encrypted_message,
		uint16_t *	encrypted_message_length
	)

Encrypts session data using RSA public key.

Encrypts session data using RSA public key which is either provided by the host or stored in OPTIGA.

Invokes optiga_cmd_encrypt_asym API, based on the input arguments.
Encrypts the data in the session OID using a RSA public key.
The RSA public key either provided by the host or refers to a OID in OPTIGA containing the public key certificate.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
A session OID must be acquired using optiga_crypt_rsa_generate_pre_master_secret otherwise OPTIGA_CMD_ERROR_INVALID_INPUT is returned.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION.
Error codes from lower layers is returned as it is to the application.
encrypted_message_length contains the size of buffer provided by user to store the encrypted data. On successful encryption, this value is updated with actual length of the encrypted data.
In case of any error, the value is set to 0.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_scheme	RSA encryption scheme.
[in]	label	Pointer to a label (used only is case of RSAES_OAEP_SHA256 otherwise ignored).
[in]	label_length	Length of the label (used only is case of RSAES_OAEP_SHA256 otherwise ignored).
[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 be used from the certificate data object from OPTIGA. OPTIGA_CRYPT_HOST_DATA or Non-Zero value, 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 to OID value must be passed. For Public key from host, pointer to public_key_from_host_t instance.
[in,out]	encrypted_message	Pointer to buffer to store encrypted message.
[in,out]	encrypted_message_length	Pointer to length of the encrypted message.

Return values

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

Example
example_optiga_crypt_encrypt_session.c

◆ optiga_crypt_rsa_generate_keypair()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_generate_keypair	(	optiga_crypt_t *	me,
		optiga_rsa_key_type_t	key_type,
		uint8_t	key_usage,
		bool_t	export_private_key,
		void *	private_key,
		uint8_t *	public_key,
		uint16_t *	public_key_length
	)

Generates a key pair based on RSA key type.

Generates a RSA key-pair based on the type of the key.

Invokes optiga_cmd_gen_keypair API, based on the input arguments.
Generate an RSA key pair using OPTIGA.
If export is requested, exports the private key else stores it in the input private key OID.
Always exports the public keys.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.
RSA key pair generation on OPTIGA can go beyond 50 seconds therefore use a larger value for optiga comms TL_MAX_EXIT_TIMEOUT. The default value is hence set to 180 seconds.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	key_type	RSA key type defined in optiga_rsa_key_type_t.
[in]	key_usage	Key usage defined in optiga_key_usage_t. Values from optiga_key_usage can be logically ORed and passed. It is ignored if export_private_key is TRUE (1) or non-zero.
[in]	export_private_key	TRUE (1) or a non-zero value - Exports private key to the host. FALSE (0) - Exports only public key to the host and writes private key to OPTIGA. The input key_usage is ignored.
[in,out]	private_key	Buffer to store private key or private key OID of OPTIGA, must not be NULL. If export_private_key is TRUE, assign a pointer to a buffer to store the generated 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 a pointer to variable of type optiga_key_id_t.
[in,out]	public_key	Buffer to store public key, must not be NULL.
[in,out]	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
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_rsa_generate_keypair.c

◆ optiga_crypt_rsa_generate_pre_master_secret()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_generate_pre_master_secret	(	optiga_crypt_t *	me,
		const uint8_t *	optional_data,
		uint16_t	optional_data_length,
		uint16_t	pre_master_secret_length
	)

Generates a pre-master secret.

Generates a pre-master secret for RSA key exchange and stores in the acquired session

Invokes optiga_cmd_get_random API, based on the input arguments.
Generates the pre-master secret
Pre-master secret is stored in session OID.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.
Pre Master Secret :
- Minimum length of generated pre master secret is 8 bytes.
- The maximum length supported by OPTIGA is 48 bytes.
- It is a concatenation of optional data and random secret.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	optional_data	Optional data that gets prepended to the generated random secret. Can be set to NULL, if not required
[in]	optional_data_length	Length of the optional data provided. It is ignored if optional_data is NULL Value can be up to 58 bytes Difference in shared secret length and optional data length is less than 8 bytes
[in]	pre_master_secret_length	Length of the shared secret to be generated. Length validation for more than maximum length is not done, since OPTIGA will provide an error for an invalid shared secret length.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided. optional_data_length is more than 40 bytes Difference in shared secret length and optional data length is less than 8 bytes
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_encrypt_session.c

◆ optiga_crypt_rsa_sign()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_sign	(	optiga_crypt_t *	me,
		optiga_rsa_signature_scheme_t	signature_scheme,
		const uint8_t *	digest,
		uint8_t	digest_length,
		optiga_key_id_t	private_key,
		uint8_t *	signature,
		uint16_t *	signature_length,
		uint16_t	salt_length
	)

Generates a RSA signature for the given digest based on the input signature scheme.

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

Invokes optiga_cmd_calc_sign API, based on the input arguments.
Generates signature for the input digest.
Exports the generated signature.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	signature_scheme	RSA signature scheme defined in optiga_rsa_signature_scheme_t
[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. This is static private key only.
[in,out]	signature	Pointer to store generated signature, must not be NULL.
[in]	signature_length	Length of signature. Initial value set as length of buffer, later updated as the actual length of generated signature. The size of the buffer must be sufficient enough to accommodate the signature.
[in]	salt_length	Reserved for future use. Parameter for RSA PSS signature scheme.

Return values

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

Example
example_optiga_crypt_rsa_sign.c

◆ optiga_crypt_rsa_verify()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_rsa_verify	(	optiga_crypt_t *	me,
		optiga_rsa_signature_scheme_t	signature_scheme,
		const uint8_t *	digest,
		uint8_t	digest_length,
		const uint8_t *	signature,
		uint16_t	signature_length,
		uint8_t	public_key_source_type,
		const void *	public_key,
		uint16_t	salt_length
	)

Verifies the RSA signature over the given digest.

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

Invokes optiga_cmd_verify_sign API, based on the input arguments.
Verifies the signature over the given provided with the input data using public key.
It invokes the callback handler of the instance, when it is asynchronously completed.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	signature_scheme	RSA signature scheme defined in optiga_rsa_signature_scheme_t
[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 or Non-Zero value , 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 to an OID value must be passed. For Public key from host, pointer to public_key_from_host_t instance.
[in]	salt_length	Reserved for future use. Parameter for RSA PSS signature scheme.

Return values

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

Example
example_optiga_crypt_rsa_verify.c

◆ optiga_crypt_symmetric_decrypt()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_decrypt	(	optiga_crypt_t *	me,
		optiga_symmetric_encryption_mode_t	encryption_mode,
		optiga_key_id_t	symmetric_key_oid,
		const uint8_t *	encrypted_data,
		uint32_t	encrypted_data_length,
		const uint8_t *	iv,
		uint16_t	iv_length,
		const uint8_t *	associated_data,
		uint16_t	associated_data_length,
		uint8_t *	plain_data,
		uint32_t *	plain_data_length
	)

Decrypt the encrypted data using symmetric encryption mode and export plain message to host.

Decrypt the encrypted data using symmetric key from OPTIGA and export the plain data to host.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments.
Decrypts the input message based on the encryption mode.
Use the symmetric key referred by symmetric key OID.
Exports the decrypted message back to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.
The API does not support MAC based encryption modes.
No internal padding is performed by OPTIGA, hence encrypted data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_mode	Symmetric encryption mode
[in]	symmetric_key_oid	OPTIGA symmetric key OID Symmetric key must be available at the specified OID.
[in]	encrypted_data	Pointer to the data to be decrypted.
[in]	encrypted_data_length	Length of the data to be decrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in]	iv	Pointer to an IV(initialization vector) or nonce. Only supported for CBC and CCM mode.
[in]	iv_length	Length of the IV Only supported for CBC and CCM mode.
[in]	associated_data	Pointer to associated data Only supported for CCM mode.
[in]	associated_data_length	Length of associated data Only supported for CBC mode.
[in,out]	plain_data	Pointer to buffer to store plain data.
[in,out]	plain_data_length	Pointer to length of the plain_data. Initial value set as length of buffer, later updated as the actual length of plain data. The size of the buffer must be sufficient enough to accommodate the plain data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_decrypt_continue()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_decrypt_continue	(	optiga_crypt_t *	me,
		const uint8_t *	encrypted_data,
		uint32_t	encrypted_data_length,
		uint8_t *	plain_data,
		uint32_t *	plain_data_length
	)

Decrypts input encrypted data using symmetric key from OPTIGA and exports block aligned plain data.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments.
Decrypts the input message and exports the decrypted message.
Encryption mode and the Symmetric key OID specified in optiga_crypt_symmetric_decrypt_start is used to decrypt the data by OPTIGA.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The decryption sequence must have been initiated, by invoking optiga_crypt_symmetric_decrypt_start, before calling this API.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, value set in optiga_crypt_symmetric_decrypt_start is used in this API.
No internal padding is performed by OPTIGA, hence encrypted data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated in case of an error from lower layer
Invoking this API without successful completion of optiga_crypt_symmetric_decrypt_start throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encrypted_data	Pointer to the data to be decrypted.
[in]	encrypted_data_length	Length of the data to be decrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in,out]	plain_data	Pointer to buffer to store plain data.
[in,out]	plain_data_length	Pointer to length of the plain_data. Initial value set as length of buffer, later updated as the actual length of plain data. The size of the buffer must be sufficient enough to accommodate the plain data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_decrypt_ecb()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_decrypt_ecb	(	optiga_crypt_t *	me,
		optiga_key_id_t	symmetric_key_oid,
		const uint8_t *	encrypted_data,
		uint32_t	encrypted_data_length,
		uint8_t *	plain_data,
		uint32_t *	plain_data_length
	)

Decrypt the data using symmetric encryption scheme using ECB mode of operation.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments.
Decrypts the input message based on ecb mode.
Use the symmetric key referred by symmetric key OID.
Exports the decrypted message back to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.
No internal padding is performed by OPTIGA, hence encrypted data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	symmetric_key_oid	OID of the symmetric key object to be used to decrypt the data. Symmetric key must be available at the specified OID.
[in]	encrypted_data	Pointer to the encrypted data to be decrypted.
[in]	encrypted_data_length	Length of the encrypted data to be decrypted.
[in,out]	plain_data	Pointer to buffer to store decrypted data.
[in,out]	plain_data_length	Pointer to length of the plain_data. Initial value set as length of buffer, later updated as the actual length of plain data. The size of the buffer must be sufficient enough to accommodate the plain data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt_ecb.c

◆ optiga_crypt_symmetric_decrypt_final()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_decrypt_final	(	optiga_crypt_t *	me,
		const uint8_t *	encrypted_data,
		uint32_t	encrypted_data_length,
		uint8_t *	plain_data,
		uint32_t *	plain_data_length
	)

Decrypts input data using symmetric key from OPTIGA, exports block aligned plain data and completes the decryption sequence.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments to generate and export the plain message to host.
Decrypts the input message and exports the decrypted message.
Encryption mode and the symmetric key OID specified in optiga_crypt_symmetric_decrypt_start is used to decrypt the data by OPTIGA.
It terminates the strict sequence.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The decryption sequence must have been initiated, by invoking optiga_crypt_symmetric_decrypt_start, before calling this API.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, value set in optiga_crypt_symmetric_decrypt_start is used in this API.
No internal padding is performed by OPTIGA, hence encrypted data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated in case of an error from lower layer
Invoking this API without successful completion of optiga_crypt_symmetric_decrypt_start throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encrypted_data	Pointer to the data to be decrypted.
[in]	encrypted_data_length	Length of the data to be decrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in,out]	plain_data	Pointer to buffer to store plain data.
[in,out]	plain_data_length	Pointer to length of the plain_data. Initial value set as length of buffer, later updated as the actual length of plain data. The size of the buffer must be sufficient enough to accommodate the plain data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_decrypt_start()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_decrypt_start	(	optiga_crypt_t *	me,
		optiga_symmetric_encryption_mode_t	encryption_mode,
		optiga_key_id_t	symmetric_key_oid,
		const uint8_t *	encrypted_data,
		uint32_t	encrypted_data_length,
		const uint8_t *	iv,
		uint16_t	iv_length,
		const uint8_t *	associated_data,
		uint16_t	associated_data_length,
		uint16_t	total_encrypted_data_length,
		uint8_t *	plain_data,
		uint32_t *	plain_data_length
	)

Initiate symmetric decryption sequence for input data using symmetric key from OPTIGA.

Invokes optiga_cmd_decrypt_sym API, based on the input arguments.
It marks the beginning of a strict sequence. None of the service layer API will be processed until the strict sequence is terminated.
Invokes optiga_cmd_decrypt_sym API, based on the input arguments to generate and export the plain message to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_RESPONSE_PROTECTION.
The API does not support MAC based encryption modes.
No internal padding is performed by OPTIGA, hence encrypted data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated
- In case of an error from lower layer.
- Same instance is used for other service layer APIs (except optiga_crypt_symmetric_decrypt_continue and optiga_crypt_symmetric_decrypt_final).

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_mode	Symmetric encryption mode
[in]	symmetric_key_oid	OPTIGA symmetric key OID Symmetric key must be available at the specified OID.
[in]	encrypted_data	Pointer to the data to be decrypted.
[in]	encrypted_data_length	Length of the data to be decrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in]	iv	Pointer to an IV(initialization vector) or nonce. Only supported for CBC and CCM mode.
[in]	iv_length	Length of the IV Only supported for CBC and CCM mode.
[in]	associated_data	Pointer to associated data Only supported for CCM mode.
[in]	associated_data_length	Length of associated data Only supported for CCM mode.
[in]	total_encrypted_data_length	Length of total data to be decrypted until optiga_crypt_symmetric_decrypt_final. Only supported for CCM mode.
[in,out]	plain_data	Pointer to buffer to store plain data.
[in,out]	plain_data_length	Pointer to length of the plain_data. Initial value set as length of buffer, later updated as the actual length of plain data. The size of the buffer must be sufficient enough to accommodate the plain data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_encrypt()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_encrypt	(	optiga_crypt_t *	me,
		optiga_symmetric_encryption_mode_t	encryption_mode,
		optiga_key_id_t	symmetric_key_oid,
		const uint8_t *	plain_data,
		uint32_t	plain_data_length,
		const uint8_t *	iv,
		uint16_t	iv_length,
		const uint8_t *	associated_data,
		uint16_t	associated_data_length,
		uint8_t *	encrypted_data,
		uint32_t *	encrypted_data_length
	)

Encrypt the data using symmetric encryption mode and export encrypted message to host.

Encrypt the input message using symmetric key from OPTIGA and export the encrypted message to host.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Encrypts the input message based on the encryption mode.
Use the symmetric key referred by symmetric key OID.
Exports the encrypted message back to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION.
No internal padding is performed by OPTIGA, hence plain data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_mode	Symmetric encryption mode
[in]	symmetric_key_oid	OPTIGA symmetric key OID Symmetric key must be available at the specified OID.
[in]	plain_data	Pointer to the data to be encrypted.
[in]	plain_data_length	Length of the data to be encrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in]	iv	Pointer to an IV(initialization vector) or nonce. It must be block aligned, otherwise OPTIGA returns an error. Only supported for CBC and CCM mode.
[in]	iv_length	Length of the IV Only supported for CBC and CCM mode.
[in]	associated_data	Pointer to associated data Only supported for CCM mode.
[in]	associated_data_length	Length of associated data Only supported for CCM mode.
[in,out]	encrypted_data	Pointer to buffer to store encrypted data
[in,out]	encrypted_data_length	Pointer to length of the encrypted_data. Initial value set as length of buffer, later updated as the actual length of encrypted data. The size of the buffer must be sufficient enough to accommodate the encrypted data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_encrypt_continue()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_encrypt_continue	(	optiga_crypt_t *	me,
		const uint8_t *	plain_data,
		uint32_t	plain_data_length,
		uint8_t *	encrypted_data,
		uint32_t *	encrypted_data_length
	)

Encrypts input data using symmetric key from OPTIGA and exports block aligned encrypted data.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Encrypts the input message and exports the encrypted message.
Encryption mode and Symmetric key OID specified in optiga_crypt_symmetric_encrypt_start is used to encrypt the data by OPTIGA.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The encryption sequence must have been initiated, by invoking optiga_crypt_symmetric_encrypt_start, before calling this API.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, value set in optiga_crypt_symmetric_encrypt_start is used in this API.
No internal padding is performed by OPTIGA, hence plain data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated in case of an error from lower layer
Invoking this API without successful completion of optiga_crypt_symmetric_encrypt_start throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	plain_data	Pointer to the data to be encrypted.
[in]	plain_data_length	Length of the data to be encrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in,out]	encrypted_data	Pointer to buffer to store encrypted data. Can be NULL for MAC based operations.
[in,out]	encrypted_data_length	Pointer to length of the encrypted_data. Initial value set as length of buffer, later updated as the actual length of encrypted data. The size of the buffer must be sufficient enough to accommodate the encrypted data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_encrypt_ecb()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_encrypt_ecb	(	optiga_crypt_t *	me,
		optiga_key_id_t	symmetric_key_oid,
		const uint8_t *	plain_data,
		uint32_t	plain_data_length,
		uint8_t *	encrypted_data,
		uint32_t *	encrypted_data_length
	)

Encrypt the data using symmetric encryption scheme using ECB mode of operation.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Encrypts the input message in ecb mode.
Use the symmetric key referred by symmetric key OID.
Exports the encrypted message back to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION.
No internal padding is performed by OPTIGA hence plain data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	symmetric_key_oid	OID of the symmetric key object to be used to encrypt the data. Symmetric key must be available at the specified OID.
[in]	plain_data	Pointer to the data to be encrypted.
[in]	plain_data_length	Length of the data to be encrypted.
[in,out]	encrypted_data	Pointer to buffer to store encrypted data.
[in,out]	encrypted_data_length	Pointer to length of the encrypted_data. Initial value set as length of buffer, later updated as the actual length of encrypted data. The size of the buffer must be sufficient enough to accommodate the encrypted data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt_ecb.c

◆ optiga_crypt_symmetric_encrypt_final()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_encrypt_final	(	optiga_crypt_t *	me,
		const uint8_t *	plain_data,
		uint32_t	plain_data_length,
		uint8_t *	encrypted_data,
		uint32_t *	encrypted_data_length
	)

Encrypts input data using symmetric key from OPTIGA, exports block aligned encrypted data and completes the encryption sequence.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
Encrypts the input message and exports the encrypted message.
Encryption mode and Symmetric key OID specified in optiga_crypt_symmetric_encrypt_start is used to encrypt the data by OPTIGA.
It terminates the strict sequence.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
The encryption sequence must have been initiated, by invoking optiga_crypt_symmetric_encrypt_start, before calling this API.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, value set in optiga_crypt_symmetric_encrypt_start is used in this API.
No internal padding is performed by OPTIGA, hence plain data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated in case of an error from lower layer
Invoking this API without successful completion of optiga_crypt_symmetric_encrypt_start throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	plain_data	Pointer to the data to be encrypted.
[in]	plain_data_length	Length of the data to be encrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in,out]	encrypted_data	Pointer to buffer to store encrypted data.
[in,out]	encrypted_data_length	Pointer to length of the encrypted_data. Initial value set as length of buffer, later updated as the actual length of encrypted data. The size of the buffer must be sufficient enough to accommodate the encrypted data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_encrypt_start()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_encrypt_start	(	optiga_crypt_t *	me,
		optiga_symmetric_encryption_mode_t	encryption_mode,
		optiga_key_id_t	symmetric_key_oid,
		const uint8_t *	plain_data,
		uint32_t	plain_data_length,
		const uint8_t *	iv,
		uint16_t	iv_length,
		const uint8_t *	associated_data,
		uint16_t	associated_data_length,
		uint16_t	total_plain_data_length,
		uint8_t *	encrypted_data,
		uint32_t *	encrypted_data_length
	)

Initiates a symmetric encryption sequence for input data using symmetric key from OPTIGA.

Invokes optiga_cmd_encrypt_sym API, based on the input arguments.
It marks the beginning of a strict sequence. None of the service layer API will be processed until the strict sequence is terminated.
Invokes optiga_cmd_encrypt_sym API, based on the input arguments to generate and export the encrypted message to host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

The application on OPTIGA must be opened using optiga_util_open_application.
Symmetric key must be available at symmetric key OID in OPTIGA.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL.
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION.
No internal padding is performed by OPTIGA, hence plain data length must be block aligned (minimum 1 block).
Error codes from lower layers is returned as it is to the application.
The strict sequence is terminated
- In case of an error from lower layer.
- Same instance is used for other service layer APIs (except optiga_crypt_symmetric_encrypt_continue and optiga_crypt_symmetric_encrypt_final).

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	encryption_mode	Symmetric encryption mode
[in]	symmetric_key_oid	OPTIGA symmetric key OID Symmetric key must be available at the specified OID.
[in]	plain_data	Pointer to the data to be encrypted.
[in]	plain_data_length	Length of the data to be encrypted. It must be block aligned, otherwise OPTIGA returns an error.
[in]	iv	Pointer to an IV(initialization vector) or nonce. Only supported for CBC and CCM mode.
[in]	iv_length	Length of the IV Only supported for CBC and CCM mode.
[in]	associated_data	Pointer to associated data Only supported for CCM mode.
[in]	associated_data_length	Length of associated data Only supported for CCM mode.
[in]	total_plain_data_length	Length of total data to be encrypted until optiga_crypt_symmetric_encrypt_final. Only supported for CCM mode.
[in,out]	encrypted_data	Pointer to buffer to store encrypted data. Can be NULL for MAC based operations.
[in,out]	encrypted_data_length	Pointer to length of the encrypted_data. Initial value set as length of buffer, later updated as the actual length of encrypted data. The size of the buffer must be sufficient enough to accommodate the encrypted data. In case of any error, the value is set to 0.

Return values

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

Example
example_optiga_crypt_symmetric_encrypt_decrypt.c

◆ optiga_crypt_symmetric_generate_key()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_symmetric_generate_key	(	optiga_crypt_t *	me,
		optiga_symmetric_key_type_t	key_type,
		uint8_t	key_usage,
		bool_t	export_symmetric_key,
		void *	symmetric_key
	)

Generates a symmetric key using OPTIGA.

Generates a symmetric key using OPTIGA for different key sizes.

Invokes optiga_cmd_gen_symkey API, based on input arguments.
Symmetric key is generated based on the key type.
If export to host is requested, exports the symmetric key back to host otherwise stores it in the provided symmetric key OID.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
Error codes from lower layers is returned as it is.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	key_type	Key type of optiga_symmetric_key_type_t.
[in]	key_usage	Key usage defined in optiga_key_usage_t. It is ignored if export_symmetric_key is TRUE (1) or Non-Zero.
[in]	export_symmetric_key	TRUE (1) or Non-Zero value - Exports symmetric key to the host. FALSE (0) - Stores symmetric key in OPTIGA.
[in,out]	symmetric_key	Pointer to buffer of symmetric key. If export_symmetric_key is TRUE or non-zero, assign pointer to a buffer to store symmetric key. If export_symmetric_key is FALSE, assign pointer to variable of type optiga_key_id_t. The size of the buffer must be sufficient enough to accommodate the key.

Return values

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

Example
example_optiga_crypt_symmetric_generate_key.c

◆ optiga_crypt_tls_prf()

LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_tls_prf	(	optiga_crypt_t *	me,
		optiga_tls_prf_type_t	type,
		uint16_t	secret,
		const uint8_t *	label,
		uint16_t	label_length,
		const 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.

Invokes optiga_cmd_derive_key API, based on the input arguments.
Stores the derived key into OPTIGA session context or export it to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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.
If the secret type is OPTIGA_KEY_ID_SESSION_BASED then session must be already available in the instance. (For .e.g Using optiga_crypt_ecdh )

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID..
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	type	Type of scheme to be used for TLS PRF as optiga_tls_prf_type_t.
[in]	secret	Object ID where the secret is 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. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	- Wrong Input arguments provided Attempt to use a session OID which is not acquired in optiga_crypt_ecdh Session is not available in instance and the secret type is OPTIGA_KEY_ID_SESSION_BASED
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_tls_prf_sha256.c

Here is the caller graph for this function:

◆ optiga_crypt_tls_prf_sha256()

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

Derives a key using TLS PRF SHA256.

Derives a key TLS PRF SHA256 using the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
Stores the derived key into OPTIGA session context or export it to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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.
Try to access session OID without acquiring session in optiga_crypt_ecdh throws OPTIGA_CMD_ERROR_INVALID_INPUT error.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	secret	Object ID where the secret is 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. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided Attempt to use a session OID which is not acquired in optiga_crypt_ecdh
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_tls_prf_sha256.c

Definition at line 706 of file optiga_crypt.h.

Here is the call graph for this function:

◆ optiga_crypt_tls_prf_sha384()

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_tls_prf_sha384	(	optiga_crypt_t *	me,
		uint16_t	secret,
		const uint8_t *	label,
		uint16_t	label_length,
		const uint8_t *	seed,
		uint16_t	seed_length,
		uint16_t	derived_key_length,
		bool_t	export_to_host,
		uint8_t *	derived_key
	)

Derives a key using TLS PRF SHA384.

Derives a key using the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
Stores the derived key into OPTIGA session context or export it to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	secret	Object ID where the secret is 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. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided Attempt to use a session OID which is not acquired in optiga_crypt_ecdh
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
None

Definition at line 776 of file optiga_crypt.h.

Here is the call graph for this function:

◆ optiga_crypt_tls_prf_sha512()

_STATIC_INLINE LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_tls_prf_sha512	(	optiga_crypt_t *	me,
		uint16_t	secret,
		const uint8_t *	label,
		uint16_t	label_length,
		const uint8_t *	seed,
		uint16_t	seed_length,
		uint16_t	derived_key_length,
		bool_t	export_to_host,
		uint8_t *	derived_key
	)

Derives a key using TLS PRF SHA512.

Derives a key using the secret stored in OPTIGA.

Invokes optiga_cmd_derive_key API, based on the input arguments.
Stores the derived key into OPTIGA session context or export it to the host.
The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.

Precondition

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.

Note

For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
- Default protection level for this API is OPTIGA_COMMS_COMMAND_PROTECTION if secret is in session OID.
Error codes from lower layers is returned as it is to the application.

Parameters

[in]	me	Valid instance of optiga_crypt_t created using optiga_crypt_create.
[in]	secret	Object ID where the secret is 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. Export to Host : The minimum length of the derived key can be 1 byte. Save in Sesssion OID : The minimum length of the derived key should be 16 bytes. For derived key lengths from 1 to 15, OPTIGA derives 16 bytes key in the session OID.
[in]	export_to_host	TRUE (1) or Non-Zero value - 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 is non-zero value). Otherwise set to NULL.

Return values

OPTIGA_CRYPT_SUCCESS	Successful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUT	Wrong Input arguments provided Attempt to use a session OID which is not acquired in optiga_crypt_ecdh
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USE	The previous operation with the same instance is not complete
OPTIGA_DEVICE_ERROR	Command execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
None

Definition at line 846 of file optiga_crypt.h.

Here is the call graph for this function:

Data Structures

Detailed Description

Macro Definition Documentation

◆ OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL

◆ OPTIGA_CRYPT_SET_COMMS_PROTOCOL_VERSION

Typedef Documentation

◆ optiga_crypt_params_t

◆ optiga_crypt_t

Function Documentation

◆ optiga_crypt_clear_auto_state()

◆ optiga_crypt_create()

◆ optiga_crypt_destroy()

◆ optiga_crypt_ecc_generate_keypair()

◆ optiga_crypt_ecdh()

◆ optiga_crypt_ecdsa_sign()

◆ optiga_crypt_ecdsa_verify()

◆ optiga_crypt_generate_auth_code()

◆ optiga_crypt_hash()

◆ optiga_crypt_hash_finalize()

◆ optiga_crypt_hash_start()

◆ optiga_crypt_hash_update()

◆ optiga_crypt_hkdf()

◆ optiga_crypt_hkdf_sha256()

◆ optiga_crypt_hkdf_sha384()

◆ optiga_crypt_hkdf_sha512()

◆ optiga_crypt_hmac()

◆ optiga_crypt_hmac_finalize()

◆ optiga_crypt_hmac_start()

◆ optiga_crypt_hmac_update()

◆ optiga_crypt_hmac_verify()

◆ optiga_crypt_random()

◆ optiga_crypt_rsa_decrypt_and_export()

◆ optiga_crypt_rsa_decrypt_and_store()

◆ optiga_crypt_rsa_encrypt_message()

◆ optiga_crypt_rsa_encrypt_session()

◆ optiga_crypt_rsa_generate_keypair()

◆ optiga_crypt_rsa_generate_pre_master_secret()

◆ optiga_crypt_rsa_sign()

◆ optiga_crypt_rsa_verify()

◆ optiga_crypt_symmetric_decrypt()

◆ optiga_crypt_symmetric_decrypt_continue()

◆ optiga_crypt_symmetric_decrypt_ecb()

◆ optiga_crypt_symmetric_decrypt_final()

◆ optiga_crypt_symmetric_decrypt_start()

◆ optiga_crypt_symmetric_encrypt()

◆ optiga_crypt_symmetric_encrypt_continue()

◆ optiga_crypt_symmetric_encrypt_ecb()

◆ optiga_crypt_symmetric_encrypt_final()

◆ optiga_crypt_symmetric_encrypt_start()

◆ optiga_crypt_symmetric_generate_key()

◆ optiga_crypt_tls_prf()

◆ optiga_crypt_tls_prf_sha256()

◆ optiga_crypt_tls_prf_sha384()

◆ optiga_crypt_tls_prf_sha512()