OPTIGA Trust M  1.1.0
C++ library for Optiga Trust M Chip Security Controller
optiga_crypt.c File Reference

This file implements the OPTIGA Crypt module. More...

Include dependency graph for optiga_crypt.c:
#define OPTIGA_CRYPT_ECDSA_FIPS_186_3_WITHOUT_HASH   (0x11)
 ECDSA FIPS 186-3 without hash. More...
 
#define OPTIGA_CRYPT_ECDH_KEY_AGREEMENT_ALGORITHM   (0x01)
 Elliptic Curve Diffie-Hellman key agreement algorithm. More...
 
#define OPTIGA_CRYPT_MINIMUM_RANDOM_DATA_LENGTH   (0x08)
 Minimum length of random data. More...
 
#define OPTIGA_CRYTP_RANDOM_PARAM_PRE_MASTER_SECRET   (0x04)
 Param type for optiga pre-master secret. More...
 
#define OPTIGA_CRYTP_MINIMUM_OPTIONAL_DATA_LENGTH   (0x28)
 Minimum optional data length. More...
 
_STATIC_H void optiga_crypt_generic_event_handler (void *p_ctx, optiga_lib_status_t event)
 
_STATIC_H void optiga_crypt_reset_protection_level (optiga_crypt_t *me)
 
void optiga_cmd_set_shielded_connection_option (optiga_cmd_t *me, uint8_t value, uint8_t shielded_connection_option)
 
_STATIC_H optiga_lib_status_t optiga_crypt_generate_keypair (optiga_crypt_t *me, uint8_t cmd_param, uint8_t key_usage, bool_t export_private_key, void *p_private_key, uint8_t *p_public_key, uint16_t *p_public_key_length)
 
_STATIC_H optiga_lib_status_t optiga_crypt_sign (optiga_crypt_t *me, uint8_t signature_scheme, const uint8_t *p_digest, uint8_t digest_length, optiga_key_id_t private_key, uint8_t *p_signature, uint16_t *p_signature_length, uint16_t salt_length)
 
_STATIC_H optiga_lib_status_t optiga_crypt_verify (optiga_crypt_t *me, uint8_t cmd_param, const uint8_t *p_digest, uint8_t digest_length, const uint8_t *p_signature, uint16_t signature_length, uint8_t public_key_source_type, const void *p_public_key, uint16_t salt_length)
 
_STATIC_H optiga_lib_status_t optiga_crypt_rsa_enc_dec (optiga_crypt_t *me, optiga_rsa_encryption_scheme_t encryption_scheme, const uint8_t *p_message, uint16_t message_length, const uint8_t *p_label, uint16_t label_length, uint8_t public_key_source_type, const void *p_key, uint8_t *p_processed_message, uint16_t *p_processed_message_length, bool_t is_enc)
 
_STATIC_H optiga_lib_status_t optiga_crypt_get_random (optiga_crypt_t *me, uint8_t cmd_param, uint8_t *p_random_data, uint16_t random_data_length, const uint8_t *p_optional_data, uint16_t optional_data_length)
 
void optiga_crypt_set_comms_params (optiga_crypt_t *me, uint8_t parameter_type, uint8_t value)
 Sets/updates the OPTIGA Comms Shielded connection configuration in the respective (optiga_util) instance. More...
 
optiga_crypt_toptiga_crypt_create (uint8_t optiga_instance_id, callback_handler_t handler, void *caller_context)
 Create an instance of optiga_crypt_t. More...
 
optiga_lib_status_t optiga_crypt_destroy (optiga_crypt_t *me)
 Destroys an instance of optiga_crypt_t. More...
 
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...
 
optiga_lib_status_t optiga_crypt_hash_start (optiga_crypt_t *me, optiga_hash_context_t *hash_ctx)
 Initializes a hash context. More...
 
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...
 
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...
 
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 an key pair based on ECC curves. More...
 
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...
 
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...
 
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...
 
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.
More...
 
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 an key pair based on RSA key type. More...
 
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...
 
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...
 
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...
 
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...
 
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...
 
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...
 
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...
 

Detailed Description

This file implements the OPTIGA Crypt module.

Copyright (c) 2019 Infineon Technologies AG

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE

\endcopyright

Author
Infineon Technologies AG

Macro Definition Documentation

◆ OPTIGA_CRYPT_ECDH_KEY_AGREEMENT_ALGORITHM

#define OPTIGA_CRYPT_ECDH_KEY_AGREEMENT_ALGORITHM   (0x01)

Elliptic Curve Diffie-Hellman key agreement algorithm.

◆ OPTIGA_CRYPT_ECDSA_FIPS_186_3_WITHOUT_HASH

#define OPTIGA_CRYPT_ECDSA_FIPS_186_3_WITHOUT_HASH   (0x11)

ECDSA FIPS 186-3 without hash.

◆ OPTIGA_CRYPT_MINIMUM_RANDOM_DATA_LENGTH

#define OPTIGA_CRYPT_MINIMUM_RANDOM_DATA_LENGTH   (0x08)

Minimum length of random data.

◆ OPTIGA_CRYTP_MINIMUM_OPTIONAL_DATA_LENGTH

#define OPTIGA_CRYTP_MINIMUM_OPTIONAL_DATA_LENGTH   (0x28)

Minimum optional data length.

◆ OPTIGA_CRYTP_RANDOM_PARAM_PRE_MASTER_SECRET

#define OPTIGA_CRYTP_RANDOM_PARAM_PRE_MASTER_SECRET   (0x04)

Param type for optiga pre-master secret.

Function Documentation

◆ optiga_cmd_set_shielded_connection_option()

void optiga_cmd_set_shielded_connection_option ( optiga_cmd_t me,
uint8_t  value,
uint8_t  shielded_connection_option 
)

◆ optiga_crypt_create()

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.

Create an instance of optiga_crypt_t.

  • Stores the callers context and callback handler.
  • Allocate memory for optiga_crypt_t.
Precondition
  • None
Note
Parameters
[in]optiga_instance_idIndicates the OPTIGA instance to be associated with optiga_crypt_t. Should be defined as below: Use OPTIGA_INSTANCE_ID_0.
[in]handlerPointer to callback function, must not be NULL.
[in]caller_contextPointer to upper layer context. Contains user context data.
Return values
optiga_crypt_tOn success function will return pointer of optiga_crypt_t.
NULLInput arguments are NULL.
Low layer function fails.
OPTIGA_CMD_MAX_REGISTRATIONS number of instances are already created.
Here is the call graph for this function:

◆ optiga_crypt_destroy()

optiga_lib_status_t optiga_crypt_destroy ( optiga_crypt_t me)

Destroys an instance of optiga_crypt_t.

Destroys the optiga_crypt_t instance.

Precondition
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]meValid instance of optiga_crypt_t.
Return values
OPTIGA_LIB_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
Here is the call graph for this function:

◆ optiga_crypt_ecc_generate_keypair()

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 an key pair based on ECC curves.

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

  • Generate an ECC 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 key.
Precondition
Note
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]curve_idECC curve id.
[in]key_usageKey usage defined by optiga_key_usage_t.
  • Values from optiga_key_usage can be logically ORed and passed.
  • It is ignored if export_private_key is TRUE (1).
[in]export_private_keyTRUE (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_keyBuffer 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_keyBuffer to store public key, must not be NULL.
[in]public_key_lengthInitially set as length of public_key, later updated as actual length of public_key.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecc_generate_keypair.c

Here is the call graph for this function:

◆ optiga_crypt_ecdh()

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

  • 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.
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.
Note
  • For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
  • Error codes from lower layers will be returned as it is.
  • The buffer size for shared secret should be appropriately provided by the user
  • If the user provides private_key as session based and export_to_host as FALSE,
    then the shared secret generated will overwrite the private key stored in the session object ID
  • Try to access session OID without acquiring session in optiga_crypt_ecc_generate_keypair throws OPTIGA_CMD_ERROR_INVALID_INPUT error.
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]private_keyObject 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_keyPointer to the public key structure for shared secret generation with its properties, must not be NULL.
[in]export_to_hostTRUE (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_secretPointer to the shared secret buffer, only if export_to_host is TRUE.
Otherwise provide NULL as input.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecdh.c

Here is the call graph for this function:

◆ optiga_crypt_ecdsa_sign()

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.

  • Generates signature for the input digest.
  • Exports the generated signature.
Precondition
Note
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]digestDigest on which signature is generated.
[in]digest_lengthLength of the input digest.
[in]private_keyPrivate key OID to generate signature.
[in,out]signaturePointer 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_lengthLength of signature. Initial value set as length of buffer, later updated as the actual length of generated signature.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecdsa_sign.c

Here is the call graph for this function:

◆ optiga_crypt_ecdsa_verify()

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.

  • 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.
Precondition
Note
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]digestPointer to a given digest buffer, must not be NULL.
[in]digest_lengthLength of digest.
[in]signaturePointer to a given signature buffer, must not be NULL.
[in]signature_lengthLength of signature.
[in]public_key_source_typePublic key from host / public key of certificate OID from OPTIGA. Value must be one of the below
[in]public_keyPublic 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_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_ecdsa_verify.c

Here is the call graph for this function:

◆ optiga_crypt_generate_keypair()

_STATIC_H optiga_lib_status_t optiga_crypt_generate_keypair ( optiga_crypt_t me,
uint8_t  cmd_param,
uint8_t  key_usage,
bool_t  export_private_key,
void *  p_private_key,
uint8_t *  p_public_key,
uint16_t *  p_public_key_length 
)
Here is the call graph for this function:

◆ optiga_crypt_generic_event_handler()

_STATIC_H void optiga_crypt_generic_event_handler ( void *  p_ctx,
optiga_lib_status_t  event 
)

◆ optiga_crypt_get_random()

_STATIC_H optiga_lib_status_t optiga_crypt_get_random ( optiga_crypt_t me,
uint8_t  cmd_param,
uint8_t *  p_random_data,
uint16_t  random_data_length,
const uint8_t *  p_optional_data,
uint16_t  optional_data_length 
)
Here is the call graph for this function:

◆ optiga_crypt_hash_finalize()

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.

  • Finalize the hash from the input hash context
  • Exports the finalized hash.
Precondition
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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]hash_ctxPointer to optiga_hash_context_t containing hash context from OPTIGA, must not be NULL.
[in,out]hash_outputOutput Hash.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_hash.c

Here is the call graph for this function:

◆ optiga_crypt_hash_start()

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.

  • Initializes a new hash context.
  • Exports the hash context to caller.
Precondition
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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in,out]hash_ctxPointer to optiga_hash_context_t to store the hash context from OPTIGA.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_hash.c

Here is the call graph for this function:

◆ optiga_crypt_hash_update()

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.

  • Update the input hash context.
  • Exports the hash context to caller.
Precondition
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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]hash_ctxPointer to optiga_hash_context_t containing hash context from OPTIGA, must not be NULL
[in]source_of_data_to_hashData from host / Data in optiga. Must be one of the below
[in]data_to_hashData for hashing either in hash_data_from_host or in hash_data_in_optiga
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_hash.c

Here is the call graph for this function:

◆ optiga_crypt_random()

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.

Precondition
Note
  • For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
  • Error codes from lower layers will be returned as it is.
  • The maximum value of the random_data_length parameter is size of buffer random_data. In case the value is greater than buffer size, memory corruption can occur.
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]rng_typeType 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_dataPointer to the buffer into which random data is stored, must not be NULL.
[in]random_data_lengthLength 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_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_random.c

Here is the call graph for this function:

◆ optiga_crypt_reset_protection_level()

_STATIC_H void optiga_crypt_reset_protection_level ( optiga_crypt_t me)

◆ optiga_crypt_rsa_decrypt_and_export()

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.

  • Provides the input data from decryption.
  • Uses the RSA private key from OPTIGA that is referred by optiga_key_id_t.
  • Decrypted data is exported to the host.
  • The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.
Precondition
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 will be 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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]encryption_schemeRSA encryption scheme.
[in]encrypted_messagePointer to the data to be decrypted.
[in]encrypted_message_lengthLength of the data to be decrypted.
[in]labelPointer to a label (Reserved for future use).
[in]label_lengthLength of the label (Reserved for future use).
[in]private_keyRSA private key in OPTIGA
[in,out]messagePointer to buffer to store decrypted message.
[in,out]message_lengthPointer to length of the decrypted message.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_decrypt.c

Here is the call graph for this function:

◆ optiga_crypt_rsa_decrypt_and_store()

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.

  • Provides the input data for decryption.
  • Uses the RSA private key from OPTIGA that 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
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 will be returned as it is to the application.
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]encryption_schemeRSA encryption scheme.
[in]encrypted_messagePointer to the data to be decrypted.
[in]encrypted_message_lengthLength of the data to be decrypted.
[in]labelPointer to a label (Reserved for future use).
[in]label_lengthLength of the label (Reserved for future use).
[in]private_keyRSA private key in OPTIGA.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_decrypt.c

Here is the call graph for this function:

◆ optiga_crypt_rsa_enc_dec()

_STATIC_H optiga_lib_status_t optiga_crypt_rsa_enc_dec ( optiga_crypt_t me,
optiga_rsa_encryption_scheme_t  encryption_scheme,
const uint8_t *  p_message,
uint16_t  message_length,
const uint8_t *  p_label,
uint16_t  label_length,
uint8_t  public_key_source_type,
const void *  p_key,
uint8_t *  p_processed_message,
uint16_t *  p_processed_message_length,
bool_t  is_enc 
)
Here is the call graph for this function:

◆ optiga_crypt_rsa_encrypt_message()

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.

  • Provides the input message to OPTIGA for encryption.
  • Uses the RSA public key either provided by the host or the OID referring to public key certificate in OPTIGA.
  • The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.
Precondition
Note
  • For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
  • Error codes from lower layers will be 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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]encryption_schemeRSA encryption scheme.
[in]messagePointer to message to be encrypted.
[in]message_lengthLength of the message to be encrypted.
[in]labelPointer to a label (Reserved for future use).
[in]label_lengthLength of the label (Reserved for future use).
[in]public_key_source_typePublic key from host / public key of certificate OID from OPTIGA. Value must be one of the below
[in]public_keyPublic 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_messagePointer to buffer to store encrypted message.
[in,out]encrypted_message_lengthPointer to length of the encrypted message.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_encrypt_message.c

Here is the call graph for this function:

◆ optiga_crypt_rsa_encrypt_session()

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.

  • Provides the session OID to OPTIGA for encrypting the session data.
  • Uses the RSA public key either provided by host or the OID referring to public key certificate in OPTIGA.
  • The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.
Precondition
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 will be 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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]encryption_schemeRSA encryption scheme.
[in]labelPointer to a label (used only is case of RSAES_OAEP_SHA256 otherwise ignored).
[in]label_lengthLength of the label (used only is case of RSAES_OAEP_SHA256 otherwise ignored).
[in]public_key_source_typePublic key from host / public key of certificate OID from OPTIGA. Value must be one of the below
[in]public_keyPublic 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_messagePointer to buffer to store encrypted message.
[in,out]encrypted_message_lengthPointer to length of the encrypted message.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_encrypt_session.c

Here is the call graph for this function:

◆ optiga_crypt_rsa_generate_keypair()

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 an key pair based on RSA key type.

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

  • 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.
Precondition
Note
  • For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
  • Error codes from lower layers will be 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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]key_typeRSA key type defined by optiga_rsa_key_type_t.
[in]key_usageKey usage defined by optiga_key_usage_t.
  • Values from optiga_key_usage can be logically ORed and passed.
  • It is ignored if export_private_key is TRUE (1) or non-zero.
[in]export_private_keyTRUE (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_keyBuffer 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_keyBuffer to store public key, must not be NULL.
[in,out]public_key_lengthInitially set as length of public_key, later updated as actual length of public_key.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_rsa_generate_keypair.c

Here is the call graph for this function:

◆ optiga_crypt_rsa_generate_pre_master_secret()

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.
Precondition
Note
  • For protected I2C communication, Refer OPTIGA_CRYPT_SET_COMMS_PROTECTION_LEVEL
  • Error codes from lower layers will be 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]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]optional_dataOptional data that gets prepended to the generated random secret.
  • Can be set to NULL, if not required
[in]optional_data_lengthLength of the optional data provided. It is ignored if optional_data is NULL
  • Value should be less than 40 bytes
  • Difference in shared secret length and optional data length is less than 8 bytes
[in]pre_master_secret_lengthLength 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_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong 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_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_encrypt_session.c

Maximum length of shared secret supported by OPTIGA is 48 bytes, minimum is 8 bytes.

The minimum difference between shared secret length and optional data length should be 8 bytes, since the minimum random length OPTIGA expects is 8 bytes (optional_data_length <= shared_length � 8 bytes).

Here is the call graph for this function:

◆ optiga_crypt_rsa_sign()

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.

  • Generates signature for the input digest.
  • Exports the generated signature.
Precondition
Note
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]signature_schemeRSA signature scheme defined by optiga_rsa_signature_scheme_t
[in]digestDigest on which signature is generated.
[in]digest_lengthLength of the input digest.
[in]private_keyPrivate key OID to generate signature. This is static private key only.
[in,out]signaturePointer to store generated signature, must not be NULL.
[in]signature_lengthLength 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_lengthReserved for future use. Parameter for RSA PSS signature scheme.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation.
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided.
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete.
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_rsa_sign.c

Here is the call graph for this function:

◆ optiga_crypt_rsa_verify()

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.

  • 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.
Precondition
Note
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]signature_schemeRSA signature scheme defined by optiga_rsa_signature_scheme_t
[in]digestPointer to a given digest buffer, must not be NULL.
[in]digest_lengthLength of digest.
[in]signaturePointer to a given signature buffer, must not be NULL.
[in]signature_lengthLength of signature.
[in]public_key_source_typePublic key from host / public key of certificate OID from OPTIGA. Value must be one of the below
[in]public_keyPublic 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_lengthReserved for future use. Parameter for RSA PSS signature scheme.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code. (Refer Solution Reference Manual)

Example
example_optiga_crypt_rsa_verify.c

Here is the call graph for this function:

◆ optiga_crypt_set_comms_params()

void optiga_crypt_set_comms_params ( optiga_crypt_t me,
uint8_t  configuration_type,
uint8_t  value 
)

Sets/updates the OPTIGA Comms Shielded connection configuration in the respective (optiga_util) instance.

Sets/updates the OPTIGA Comms Shielded connection configuration in the respective (optiga_util) instance.

Precondition
  • None
Note
  • None
Parameters
[in,out]meValid instance of optiga_util_t
[in]configuration_typeConfiguration Type Possible Types are OPTIGA_COMMS_PROTECTION_LEVEL OPTIGA_COMMS_PROTOCOL_VERSION
[in]valueValue part for the respective configuration

Example

◆ optiga_crypt_sign()

_STATIC_H optiga_lib_status_t optiga_crypt_sign ( optiga_crypt_t me,
uint8_t  signature_scheme,
const uint8_t *  p_digest,
uint8_t  digest_length,
optiga_key_id_t  private_key,
uint8_t *  p_signature,
uint16_t *  p_signature_length,
uint16_t  salt_length 
)
Here is the call graph for this function:

◆ optiga_crypt_tls_prf_sha256()

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.

Derives a key using the secret stored in OPTIGA.

  • Provides the options to store the derived key into OPTIGA session context or export to the host.
  • The callback registered with instance (optiga_crypt_create) gets invoked, when the operation is asynchronously completed.
Precondition
Note
  • Exporting the derived key:
    • The minimum length of the output derived key can be 1 byte.
  • 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 will be returned as it is to the application.
Parameters
[in]meValid instance of optiga_crypt_t created using optiga_crypt_create.
[in]secretObject ID of the secret stored in OPTIGA.
[in]labelPointer to the label, can be NULL if not applicable.
[in]label_lengthLength of the label.
[in]seedValid pointer to the seed, must not be NULL.
[in]seed_lengthLength of the seed.
[in]derived_key_lengthLength of derived key.
[in]export_to_hostTRUE (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_keyPointer 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_SUCCESSSuccessful invocation
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USEThe previous operation with the same instance is not complete
OPTIGA_DEVICE_ERRORCommand 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 call graph for this function:

◆ optiga_crypt_verify()

_STATIC_H optiga_lib_status_t optiga_crypt_verify ( optiga_crypt_t me,
uint8_t  cmd_param,
const uint8_t *  p_digest,
uint8_t  digest_length,
const uint8_t *  p_signature,
uint16_t  signature_length,
uint8_t  public_key_source_type,
const void *  p_public_key,
uint16_t  salt_length 
)
Here is the call graph for this function: