optiga_example.h File Reference

This file defines APIs, types and data structures used in the OPTIGA example. More...

#include "optiga_lib_config.h"
#include "optiga_lib_logger.h"

Include dependency graph for optiga_example.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

#define	OPTIGA_LIB_ENABLE_EXAMPLE_LOGGING
#define	OPTIGA_EXAMPLE   "[optiga example] : "
#define	OPTIGA_EXAMPLE_COLOR   OPTIGA_LIB_LOGGER_COLOR_DEFAULT
#define	OPTIGA_EXAMPLE_LOG_MESSAGE(msg)
	Logs the message provided from Application layer. More...
#define	OPTIGA_EXAMPLE_LOG_HEX_DATA(array, array_len)
	Logs the byte array buffer provided from Application layer in hexadecimal format. More...
#define	OPTIGA_EXAMPLE_LOG_STATUS(return_value)
	Logs the status info provided from Application layer. More...
void	example_optiga_crypt_hash (void)
void	example_optiga_crypt_ecc_generate_keypair (void)
void	example_optiga_crypt_ecdsa_sign (void)
void	example_optiga_crypt_ecdsa_verify (void)
void	example_optiga_crypt_ecdh (void)
void	example_optiga_crypt_random (void)
void	example_optiga_crypt_tls_prf_sha256 (void)
void	example_optiga_util_read_data (void)
void	example_optiga_util_write_data (void)
void	example_optiga_crypt_rsa_generate_keypair (void)
void	example_optiga_crypt_rsa_sign (void)
void	example_optiga_crypt_rsa_verify (void)
void	example_optiga_crypt_rsa_decrypt_and_export (void)
void	example_optiga_crypt_rsa_decrypt_and_store (void)
void	example_optiga_crypt_rsa_encrypt_message (void)
void	example_optiga_crypt_rsa_encrypt_session (void)
void	example_optiga_util_update_count (void)
void	example_optiga_util_protected_update (void)
void	example_optiga_util_read_uuid (void)
void	example_pair_host_and_optiga_using_pre_shared_secret (void)
void	example_optiga_util_hibernate_restore (void)

Detailed Description

This file defines APIs, types and data structures used in the OPTIGA example.

Copyright

MIT License

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_EXAMPLE

#define OPTIGA_EXAMPLE   "[optiga example] : "

OPTIGA_EXAMPLE_COLOR

#define OPTIGA_EXAMPLE_COLOR   OPTIGA_LIB_LOGGER_COLOR_DEFAULT

OPTIGA_EXAMPLE_LOG_HEX_DATA

#define OPTIGA_EXAMPLE_LOG_HEX_DATA	(		array,
			array_len
	)

Value:

{\
    optiga_lib_print_array_hex_format(array,array_len,OPTIGA_UNPROTECTED_DATA_COLOR);\
}

Logs the byte array buffer provided from Application layer in hexadecimal format.

Logs the byte array buffer provided from Application layer in hexadecimal format

Precondition

Note

• None

Parameters

[in]	array	Valid pointer to array to be logged
[in]	array_len	Length of array buffer

OPTIGA_EXAMPLE_LOG_MESSAGE

#define OPTIGA_EXAMPLE_LOG_MESSAGE

(

msg

)

Value:

{\
    optiga_lib_print_message(msg,OPTIGA_EXAMPLE,OPTIGA_EXAMPLE_COLOR);\
}

Logs the message provided from Application layer.

Logs the message provided from Application layer

Precondition

Note

• None

Parameters

[in]

msg

Valid pointer to string to be logged

OPTIGA_EXAMPLE_LOG_STATUS

#define OPTIGA_EXAMPLE_LOG_STATUS

(

return_value

)

Value:

{ \
    if (OPTIGA_LIB_SUCCESS != return_value) \
    { \
        optiga_lib_print_status(OPTIGA_EXAMPLE,OPTIGA_ERROR_COLOR,return_value); \
    } \
    else\
    { \
        optiga_lib_print_status(OPTIGA_EXAMPLE,OPTIGA_EXAMPLE_COLOR,return_value); \
    } \
}

Logs the status info provided from Application layer.

Logs the status info provided from Application layer

Precondition

Note

• None

Parameters

[in]

return_value

Status information Application layer

OPTIGA_LIB_ENABLE_EXAMPLE_LOGGING

#define OPTIGA_LIB_ENABLE_EXAMPLE_LOGGING

Function Documentation

example_optiga_crypt_ecc_generate_keypair()

void example_optiga_crypt_ecc_generate_keypair

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Generate ECC Key pair
   • Use ECC NIST P 256 Curve
   • Specify the Key Usage (Key Agreement or Sign based on requirement)
   • Store the Private key in OPTIGA Key store
   • Export Public Key

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_ecdh()

void example_optiga_crypt_ecdh

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Generate ECC Key pair - To use the private key with ECDH in the next step
   • Use ECC NIST P 256 Curve
   • Specify the Key Usage as Key Agreement
   • Store the Private key with in OPTIGA Session
   • Export Public Key
3. Perform ECDH using the Peer Public key
   • Use ECC NIST P 256 Curve
   • Provide the peer public key details
   • Export the generated shared secret with protected I2C communication

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_ecdsa_sign()

void example_optiga_crypt_ecdsa_sign

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Sign the digest using Private key from Key Store ID E0F0

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_ecdsa_verify()

void example_optiga_crypt_ecdsa_verify

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Verify ECDSA signature using public key from host

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_hash()

void example_optiga_crypt_hash

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Initialize the Hash context
3. Initialize the hashing context at OPTIGA
4. Continue hashing the data
5. Finalize the hash

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_random()

void example_optiga_crypt_random

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Generate Random -
   • Specify the Random type as TRNG

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_rsa_decrypt_and_export()

void example_optiga_crypt_rsa_decrypt_and_export

(

void

)

example_optiga_crypt_rsa_decrypt_and_store()

void example_optiga_crypt_rsa_decrypt_and_store

(

void

)

example_optiga_crypt_rsa_encrypt_message()

void example_optiga_crypt_rsa_encrypt_message

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. RSA encryption

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_rsa_encrypt_session()

void example_optiga_crypt_rsa_encrypt_session

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Generate 1024 bit RSA Key pair
3. Generate 48 byte RSA Pre master secret in acquired session OID
4. Encrypt (RSA) the data in session OID

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_rsa_generate_keypair()

void example_optiga_crypt_rsa_generate_keypair

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Generate RSA Key pair
   • Use 1024 or 2048 bit RSA key
   • Specify the Key Usage
   • Store the Private key in OPTIGA Key store (When exporting the private key, provide buffer of sufficient length (key size in bytes + encoding length))
   • Export Public Key

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_rsa_sign()

void example_optiga_crypt_rsa_sign

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Sign the digest -
   • Use Private key from Key Store ID E0FC
   • Signature scheme is SHA256,

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_rsa_verify()

void example_optiga_crypt_rsa_verify

(

void

)

Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Create OPTIGA Crypt Instance
2. Verify RSA signature using public key from host

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_crypt_tls_prf_sha256()

void example_optiga_crypt_tls_prf_sha256

(

void

)

Default metadata

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Write the shared secret to the Arbitrary data object F1D0
   • This is typically a one time activity and
   • use the this OID as input secret to derive keys further
2. Use Erase and Write (OPTIGA_UTIL_ERASE_AND_WRITE) option, to clear the remaining data in the object

1. Change data object type to PRESSEC
2. Create OPTIGA Crypt Instance
3. Derive key (e.g. decryption key) using optiga_crypt_tls_prf_sha256 with protected I2C communication.
   • Use shared secret from F1D0 data object
4. Change meta data to default value

Close the application on OPTIGA using optiga_util_close_application

Here is the call graph for this function:

example_optiga_util_hibernate_restore()

void example_optiga_util_hibernate_restore

(

void

)

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

To perform the hibernate, Security Event Counter(SEC) must be 0. Read SEC data object (0xE0C5) and wait until SEC = 0

Hibernate the application on OPTIGA using optiga_util_close_application with perform_hibernate parameter as true

Restore the application on OPTIGA using optiga_util_open_application with perform_restore parameter as true

Close the application on OPTIGA without hibernating using optiga_util_close_application

Here is the call graph for this function:

example_optiga_util_protected_update()

void example_optiga_util_protected_update

(

void

)

Manifest for ECC-256

Fragment array for continue with 608 bytes of payload and 32 bytes of digest of next fragment

Fragment array for final with 50 bytes of payload

Sample metadata of 0xE0E1 to change access condition to integrity protected and reseting the version tag

Sample metadata of 0xE0E3 for execute access condition

Create OPTIGA util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

Precondition 1 : Write Metadata for 0xE0E1 and 0xE0E3

Precondition 2 : Write ECC-256 certificate for 0xE0E3

Send the manifest using optiga_util_protected_update_start

Send the first fragment using optiga_util_protected_update_continue

Send the last fragment using optiga_util_protected_update_final

Close the application on OPTIGA without hibernating using optiga_util_close_application

Here is the call graph for this function:

example_optiga_util_read_data()

void example_optiga_util_read_data

(

void

)

1. Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Read data from a data object (e.g. certificate data object) using optiga_util_read_data.

Read metadata of a data object (e.g. certificate data object E0E0) using optiga_util_read_data.

Close the application on OPTIGA without hibernating using optiga_util_close_application

Here is the call graph for this function:

example_optiga_util_read_uuid()

void example_optiga_util_read_uuid

(

void

)

1. Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

1. Read data from a data object (e.g. certificate data object) using optiga_util_read_data.

Close the application on OPTIGA without hibernating using optiga_util_close_application

Here is the call graph for this function:

example_optiga_util_update_count()

void example_optiga_util_update_count

(

void

)

Initialize the counter object with a threshold value 0x0A

1. Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

Pre-condition Any data object can be converted to counter data object by changing metadata as mentioned below:

• As precondition write access should be always or LCSO < OPERATIONAL
• Write metadata as "0xD0, 0x01, 0x01" using optiga_util_write_metadata

Write default count and threshold value to counter data object (e.g. E120) using optiga_util_write_data.

Use Erase and Write (OPTIGA_UTIL_ERASE_AND_WRITE) option, in order to correctly update the used length of the object.

Close the application on OPTIGA without hibernating using optiga_util_close_application

Here is the call graph for this function:

example_optiga_util_write_data()

void example_optiga_util_write_data

(

void

)

Sample metadata

1. Create OPTIGA Util Instance

Open the application on OPTIGA which is a precondition to perform any other operations using optiga_util_open_application

Write Trust Anchor to a Trust Anchor object (e.g. E0E8) using optiga_util_write_data with no shielded connection protection.

Use Erase and Write (OPTIGA_UTIL_ERASE_AND_WRITE) option, to clear the remaining data in the object

Write metadata to Trust Anchor to a Trust Anchor object (e.g. E0E8) using optiga_util_write_metadata.

Sample metadata: write "Read" access condition as LcsO < Operational

Close the application on OPTIGA without hibernating using optiga_util_close_application

Here is the call graph for this function:

example_pair_host_and_optiga_using_pre_shared_secret()

void example_pair_host_and_optiga_using_pre_shared_secret

(

void

)