nRF5 SDK v17.1.0
Data Structures | Macros | Typedefs | Enumerations | Functions

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

Data Structures

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

Macros

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

Typedefs

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

Enumerations

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

Functions

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

Detailed Description

Infineon OPTIGA(TM) Trust X crypt module APIs.

Macro Definition Documentation

#define OPTIGA_CRYPT_SUCCESS   (0x0000)

OPTIGA crypt API execution is successful.

OPTIGA crypt module return values

Typedef Documentation

Typedef for Key IDs The KEY_STORE_ID_xxx holds only private key.

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

OPTIGA Random Generation types

Enumeration Type Documentation

Specifies the hashing algorithm type in OPTIGA.

Enumerator
OPTIGA_HASH_TYPE_SHA_256 

Hash algorithm type SHA256.

Typedef for Key IDs The KEY_STORE_ID_xxx holds only private key.

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

Enumerator
OPTIGA_KEY_STORE_ID_E0F0 

Key from key store (non-volatile)

OPTIGA_KEY_STORE_ID_E0F1 

Key from key store (non-volatile)

OPTIGA_KEY_STORE_ID_E0F2 

Key from key store (non-volatile)

OPTIGA_KEY_STORE_ID_E0F3 

Key from key store (non-volatile)

OPTIGA_SESSION_ID_E100 

Key from Session context id 1 (volatile)

OPTIGA_SESSION_ID_E101 

Key from Session context id 2 (volatile)

OPTIGA_SESSION_ID_E102 

Key from Session context id 3 (volatile)

OPTIGA_SESSION_ID_E103 

Key from Session context id 4 (volatile)

Enumerator
OPTIGA_KEY_USAGE_AUTHENTICATION 

This enables the private key for the signature generation as part of authentication commands.

OPTIGA_KEY_USAGE_SIGN 

This enables the private key for the signature generation.

OPTIGA_KEY_USAGE_KEY_AGREEMENT 

This enables the private key for key agreement (e.g. ecdh operations)

OPTIGA Random Generation types

Enumerator
OPTIGA_RNG_TYPE_TRNG 

Generate Random data using TRNG.

OPTIGA_RNG_TYPE_DRNG 

Generate Random data using DRNG.

Function Documentation

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

Generates an key pair based on ECC curves.

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

Pre Conditions:

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

API Details:

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

Notes:

  • Error codes from lower layers will be returned as it is.
Parameters
[in]curve_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 FALSE (0).
[in]export_private_keyTRUE (1) - Exports both private key and public key to the host.
FALSE (0) - Exports only public key to the host. The input key_usage is ignored.
[in]private_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 of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdh ( optiga_key_id_t  private_key,
public_key_from_host_t public_key,
bool_t  export_to_host,
uint8_t *  shared_secret 
)

Calculates the shared secret using ECDH algorithm.

Calculates the shared secret using ECDH algorithm.

Pre Conditions:

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

API Details:

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

Notes:

  • Error codes from lower layers will be returned as it is.
  • The buffer size for shared secret should be appropriately provided by the user
  • If the user provides private_key as session based and export_to_host as FALSE,
    then the shared secret generated will overwrite the private key stored in the session object ID
Parameters
[in]private_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.
  • Provide the inputs according to the structure type public_key_from_host_t
[in]export_to_hostTRUE (1) - Exports the generated shared secret to Host.
FALSE (0) - Stores the generated shared secret into the session object ID acquired by the instance.
[in,out]shared_secretPointer to the shared secret buffer, only if export_to_host is TRUE.
Otherwise supply NULL as input.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdsa_sign ( uint8_t *  digest,
uint8_t  digest_length,
optiga_key_id_t  private_key,
uint8_t *  signature,
uint16_t *  signature_length 
)

Generates a signature for the given digest.

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

Pre Conditions:

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

API Details:

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

Notes:

  • Error codes from lower layers will be returned as it is.
Parameters
[in]digestDigest on which signature is generated.
[in]digest_lengthLength of the input digest.
[in]private_keyPrivate key OID to generate signature.
[in,out]signatureGenerated signature, must not be NULL.
  • The size of the buffer must be sufficient enough to accommodate the additional DER encoding formatting for R and S components of signature.
[in]signature_lengthLength of signature.Intial value set as length of buffer, later updated as the actual length of generated signature.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_ecdsa_verify ( uint8_t *  digest,
uint8_t  digest_length,
uint8_t *  signature,
uint16_t  signature_length,
uint8_t  public_key_source_type,
void *  public_key 
)

Verifies the signature over the given digest.

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

Pre Conditions:

  • The application on OPTIGA must be opened using optiga_util_open_application.

API Details:

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

Notes:

  • Error codes from lower layers will be returned as it is to the application.
Parameters
[in]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
  • OPTIGA_CRYPT_OID_DATA, if the public key is to used from the certificate data object from OPTIGA.
  • OPTIGA_CRYPT_HOST_DATA, if the public key is provided by host.
[in]public_keyPublic key from host / public key of certificate OID. Value must be one of the below
  • For certificate OID, pointer OID value must be passed.
  • For Public key from host, pointer to public_key_from_host_t instance.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_finalize ( optiga_hash_context_t hash_ctx,
uint8_t *  hash_output 
)

Finalizes and exports the hash output.

Finalizes the hash context and returns hash as output.

Pre Conditions:

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

API Details:

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

Notes:

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


Parameters
[in]hash_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 of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_start ( optiga_hash_context_t hash_ctx)

Initializes a hash context.

Sets up a hash context and exports it.

Pre Conditions:

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

API Details:

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

Notes:

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


Parameters
[in,out]hash_ctxPointer to optiga_hash_context_t to store the hash context from OPTIGA
  • The input hash_algo in hash_ctx must be from optiga_hash_type.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_hash_update ( optiga_hash_context_t hash_ctx,
uint8_t  source_of_data_to_hash,
void *  data_to_hash 
)

Updates a hash context with the input data.

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

Pre Conditions:

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

API Details:

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

Notes:

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


Parameters
[in]hash_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
  • OPTIGA_CRYPT_HOST_DATA,if source of data is from Host.
  • OPTIGA_CRYPT_OID_DATA,if the source of data is from OPITGA.
[in]data_to_hashData for hashing either in hash_data_from_host or in hash_data_in_optiga
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_random ( optiga_rng_types_t  rng_type,
uint8_t *  random_data,
uint16_t  random_data_length 
)

Generates a random number.

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

Pre Conditions:

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

API Details:

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

Notes:

  • Error codes from lower layers will be returned as it is.
  • The maximum value of the random_data_length parameter is size of buffer random_data. In case the value is greater than buffer size, memory corruption can occur.
Parameters
[in]rng_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 of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)
LIBRARY_EXPORTS optiga_lib_status_t optiga_crypt_tls_prf_sha256 ( uint16_t  secret,
uint8_t *  label,
uint16_t  label_length,
uint8_t *  seed,
uint16_t  seed_length,
uint16_t  derived_key_length,
bool_t  export_to_host,
uint8_t *  derived_key 
)

Derives a key.

Derives a key using the secret stored in OPTIGA.

Pre Conditions:

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

API Details:

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

Notes:

  • At present, the minimum length of the output derived key is 16.
  • Error codes from lower layers will be returned as it is to the application.
Parameters
[in]secretObject 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]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) - 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= TRUE). Otherwise set to NULL.
Return values
OPTIGA_CRYPT_SUCCESSSuccessful invocation of optiga cmd module
OPTIGA_CRYPT_ERROR_INVALID_INPUTWrong Input arguments provided
OPTIGA_CRYPT_ERROR_INSTANCE_IN_USESame instance with ongoing request servicing is used
OPTIGA_DEVICE_ERRORCommand execution failure in OPTIGA and the LSB indicates the error code.(Refer Solution Reference Manual)

Documentation feedback | Developer Zone | Subscribe | Updated