Utility module

Functions
void	full_path_to_fapi_path (IFAPI_KEYSTORE *keystore, char *path)
TSS2_RC	ifapi_authorize_object (FAPI_CONTEXT *context, IFAPI_OBJECT *object, ESYS_TR *session)
TPM2_RC	ifapi_capability_get (FAPI_CONTEXT *context, TPM2_CAP capability, UINT32 count, TPMS_CAPABILITY_DATA **capability_data)
TPM2_RC	ifapi_capability_init (FAPI_CONTEXT *context)
TSS2_RC	ifapi_change_auth_hierarchy (FAPI_CONTEXT *context, ESYS_TR handle, IFAPI_OBJECT *hierarchy_object, TPM2B_AUTH *newAuthValue)
TSS2_RC	ifapi_change_policy_hierarchy (FAPI_CONTEXT *context, ESYS_TR handle, IFAPI_OBJECT *hierarchy_object, TPMS_POLICY *policy)
TSS2_RC	ifapi_cleanup_session (FAPI_CONTEXT *context)
TSS2_RC	ifapi_esys_serialize_object (ESYS_CONTEXT *ectx, IFAPI_OBJECT *object)
TSS2_RC	ifapi_flush_object (FAPI_CONTEXT *context, ESYS_TR handle)
void	ifapi_free_object (FAPI_CONTEXT *context, IFAPI_OBJECT **object)
void	ifapi_free_objects (FAPI_CONTEXT *context)
TSS2_RC	ifapi_get_certificates (FAPI_CONTEXT *context, UINT32 min_handle, UINT32 max_handle, NODE_OBJECT_T **cert_list)
TSS2_RC	ifapi_get_description (IFAPI_OBJECT *object, char **description)
TSS2_RC	ifapi_get_free_handle_async (FAPI_CONTEXT *fctx, TPM2_HANDLE *handle)
TSS2_RC	ifapi_get_free_handle_finish (FAPI_CONTEXT *fctx, TPM2_HANDLE *handle, TPM2_HANDLE max)
TSS2_RC	ifapi_get_json (FAPI_CONTEXT *context, IFAPI_OBJECT *object, char **json_string)
TSS2_RC	ifapi_get_random (FAPI_CONTEXT *context, size_t numBytes, uint8_t **data)
TSS2_RC	ifapi_get_session_async (ESYS_CONTEXT *esys, ESYS_TR saltkey, const IFAPI_PROFILE *profile, TPMI_ALG_HASH hashAlg)
TSS2_RC	ifapi_get_session_finish (ESYS_CONTEXT *esys, ESYS_TR *session, TPMA_SESSION flags)
TSS2_RC	ifapi_get_sessions_async (FAPI_CONTEXT *context, IFAPI_SESSION_TYPE session_flags, TPMA_SESSION attribute_flags1, TPMA_SESSION attribute_flags2)
TSS2_RC	ifapi_get_sessions_finish (FAPI_CONTEXT *context, const IFAPI_PROFILE *profile, TPMI_ALG_HASH hash_alg)
TSS2_RC	ifapi_get_sig_scheme (FAPI_CONTEXT *context, IFAPI_OBJECT *object, char const *padding, TPM2B_DIGEST *digest, TPMT_SIG_SCHEME *sig_scheme)
TSS2_RC	ifapi_init_primary_async (FAPI_CONTEXT *context, TSS2_KEY_TYPE ktype)
TSS2_RC	ifapi_initialize_object (ESYS_CONTEXT *ectx, IFAPI_OBJECT *object)
TSS2_RC	ifapi_key_create (FAPI_CONTEXT *context, IFAPI_KEY_TEMPLATE *template)
TSS2_RC	ifapi_key_create_prepare (FAPI_CONTEXT *context, char const *keyPath, char const *policyPath)
TSS2_RC	ifapi_key_create_prepare_auth (FAPI_CONTEXT *context, char const *keyPath, char const *policyPath, char const *authValue)
TSS2_RC	ifapi_key_create_prepare_sensitive (FAPI_CONTEXT *context, char const *keyPath, char const *policyPath, size_t dataSize, char const *authValue, uint8_t const *data)
TSS2_RC	ifapi_key_sign (FAPI_CONTEXT *context, IFAPI_OBJECT *sig_key_object, char const *padding, TPM2B_DIGEST *digest, TPMT_SIGNATURE **tpm_signature, char **publicKey, char **certificate)
TSS2_RC	ifapi_load_key (FAPI_CONTEXT *context, char const *keyPath, IFAPI_OBJECT **key_object)
TSS2_RC	ifapi_load_key_async (FAPI_CONTEXT *context, size_t position)
TSS2_RC	ifapi_load_key_finish (FAPI_CONTEXT *context, bool flush_parent)
TSS2_RC	ifapi_load_keys_async (FAPI_CONTEXT *context, char const *keyPath)
TSS2_RC	ifapi_load_keys_finish (FAPI_CONTEXT *context, bool flush_parent, ESYS_TR *handle, IFAPI_OBJECT **key_object)
TSS2_RC	ifapi_load_primary_async (FAPI_CONTEXT *context, char *path)
TSS2_RC	ifapi_load_primary_finish (FAPI_CONTEXT *context, ESYS_TR *handle)
TSS2_RC	ifapi_merge_profile_into_nv_template (FAPI_CONTEXT *context, IFAPI_NV_TEMPLATE *template)
TSS2_RC	ifapi_merge_profile_into_template (const IFAPI_PROFILE *profile, IFAPI_KEY_TEMPLATE *template)
TSS2_RC	ifapi_non_tpm_mode_init (FAPI_CONTEXT *context)
TSS2_RC	ifapi_nv_read (FAPI_CONTEXT *context, uint8_t **data, size_t *size)
TSS2_RC	ifapi_nv_write (FAPI_CONTEXT *context, char *nvPath, size_t param_offset, uint8_t const *data, size_t size)
void	ifapi_primary_clean (FAPI_CONTEXT *context)
void	ifapi_session_clean (FAPI_CONTEXT *context)
TSS2_RC	ifapi_session_init (FAPI_CONTEXT *context)
TSS2_RC	ifapi_set_auth (FAPI_CONTEXT *context, IFAPI_OBJECT *auth_object, const char *description)
void	ifapi_set_description (IFAPI_OBJECT *object, char *description)
IFAPI_OBJECT *	ifapi_allocate_object (FAPI_CONTEXT *context)
TSS2_RC	ifapi_create_primary (FAPI_CONTEXT *context, IFAPI_KEY_TEMPLATE *template)
TSS2_RC	ifapi_get_key_properties (FAPI_CONTEXT *context, char const *key_path, bool *is_primary, bool *in_null_hierarchy)
const char *	ifapi_get_object_path (IFAPI_OBJECT *object)
TSS2_RC	ifapi_load_parent_keys_async (FAPI_CONTEXT *context, char const *keyPath)

Detailed Description

Provides internal utility functions.

Function Documentation

full_path_to_fapi_path()

void full_path_to_fapi_path	(	IFAPI_KEYSTORE *	keystore,
		char *	path
	)

Convert full FAPI path to relative path.

The relative path will be copied directly into the passed object.

Parameters

[in]	keystore	The key directories and default profile.
[in,out]	path	The absolute path.

ifapi_allocate_object()

ifapi_allocate_object

(

FAPI_CONTEXT *

context

)

Allocate ifapi object and store the result in a linked list.

Allocated ifapi objects will be recorded in the context.

Parameters

[in,out]

context

The FAPI_CONTEXT.

Return values

The	allocated ifapi object.
NULL	if the object cannot be allocated.

ifapi_authorize_object()

TSS2_RC ifapi_authorize_object	(	FAPI_CONTEXT *	context,
		IFAPI_OBJECT *	object,
		ESYS_TR *	session
	)

State machine to authorize a key, a NV object of a hierarchy.

Parameters

[in,out]	context	for storing all state information.
[in]	object	The FAPI object.
[out]	session	The session which can be used for object authorization.

Return values

TSS2_RC_SUCCESS	If the authorization is successful
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the policy store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If a policy for a certain path was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for the policy execution fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.

ifapi_capability_get()

TPM2_RC ifapi_capability_get	(	FAPI_CONTEXT *	context,
		TPM2_CAP	capability,
		UINT32	count,
		TPMS_CAPABILITY_DATA **	capability_data
	)

State machine for receiving TPM capability information.

The state machine shares the state with the FAPI function Fapi_GetInfo. context->state == GET_INFO_GET_CAP_MORE signals that more capability data can be retrieved.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	capability	The capability to be retrieved.
[in]	count	The maximal number of items that should be retrieved.
[out]	capability_data	The retrieved capability information.

Return values

TSS2_RC_SUCCESS	If all capability data is retrieved.
TSS2_FAPI_RC_TRY_AGAIN	if more capability data is available.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.

ifapi_capability_init()

TPM2_RC ifapi_capability_init

(

FAPI_CONTEXT *

context

)

Prepare the receiving of capability data.

Parameters

[in,out]

context

The FAPI_CONTEXT.

Return values

TSS2_RC_SUCCESS.

ifapi_change_auth_hierarchy()

TSS2_RC ifapi_change_auth_hierarchy	(	FAPI_CONTEXT *	context,
		ESYS_TR	handle,
		IFAPI_OBJECT *	hierarchy_object,
		TPM2B_AUTH *	newAuthValue
	)

State machine for changing the hierarchy authorization.

First it will be tried to set the auth value of the hierarchy with a "null" authorization. If this trial is not successful it will be tried to authorize the hierarchy via a callback. If an not null auth value is passed with_auth is set to yes for the object otherwise to no. So for later authorizations it will be clear whether null authorization is possible or not.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	handle	The ESAPI handle of the hierarchy.
[in,out]	hierarchy_object	The internal FAPI representation of a hierarchy.
[in]	newAuthValue	The new authorization for the hierarchy.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occured.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_IO_ERROR	if an error occured while accessing the object store.
TSS2_FAPI_RC_POLICY_UNKNOWN	if policy search for a certain policy digest was not successful.

ifapi_change_policy_hierarchy()

TSS2_RC ifapi_change_policy_hierarchy	(	FAPI_CONTEXT *	context,
		ESYS_TR	handle,
		IFAPI_OBJECT *	hierarchy_object,
		TPMS_POLICY *	policy
	)

State machine for changing the policy of a hierarchy.

Based on a passed policy the policy digest will be computed. First it will be tried to set the policy of the hierarchy with a "null" authorization. If this trial is not successful it will be tried to authorize the hierarchy via a callback. If an not null auth value is passed with_auth is set to yes for the object otherwise to no. So for later authorizations it will be clear whether null authorization is possible or not.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	handle	The ESAPI handle of the hierarchy.
[in,out]	hierarchy_object	The internal FAPI representation of a hierarchy.
[in]	policy	The new policy assigned to the hierarchy.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during policy calculation.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the policy store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If an object needed for policy calculation was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

< no path needed

ifapi_cleanup_session()

TSS2_RC ifapi_cleanup_session

(

FAPI_CONTEXT *

context

)

State machine for asynchronous cleanup of a FAPI session.

Used sessions and the SRK will be flushed.

Parameters

[in]

context

The FAPI_CONTEXT storing the used handles.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.

ifapi_create_primary()

ifapi_create_primary	(	FAPI_CONTEXT *	context,
		IFAPI_KEY_TEMPLATE *	template
	)

Creation of a primary key.

Depending on the flags stored in the context the creation of a primary key will be prepared.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	template	The template which defines the key attributes and whether the key will be persistent.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_VALUE	if a wrong type was passed.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_IO_ERROR	if an error occurred while accessing the object store.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_POLICY_UNKNOWN	if policy search for a certain policy digest was not successful.
TSS2_FAPI_RC_PATH_ALREADY_EXISTS	if the object already exists in object store.

ifapi_esys_serialize_object()

TSS2_RC ifapi_esys_serialize_object	(	ESYS_CONTEXT *	ectx,
		IFAPI_OBJECT *	object
	)

Serialize persistent objects into buffer of keystore object.

NV objects and persistent keys will serialized via the ESYS API to enable reconstruction durinng loading from keystore.

Parameters

[in]	ectx	The ESAPI context.
[in,out]	object	The nv object or the key.

Return values

TSS2_RC_SUCCESS	if the function call was a success.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occured.

ifapi_flush_object()

TSS2_RC ifapi_flush_object	(	FAPI_CONTEXT *	context,
		ESYS_TR	handle
	)

State machine for flushing objects.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	handle	of the object to be flushed.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.

ifapi_free_objects()

void ifapi_free_objects

(

FAPI_CONTEXT *

context

)

Free all ifapi objects stored in the context.

Parameters

[in,out]

context

The FAPI_CONTEXT.

ifapi_get_certificates()

TSS2_RC ifapi_get_certificates	(	FAPI_CONTEXT *	context,
		UINT32	min_handle,
		UINT32	max_handle,
		NODE_OBJECT_T **	cert_list
	)

Get certificates stored in NV ram.

The NV handles in the certificate range are determined. The corresponding certificates are read out and stored in a linked list.

Parameters

[in,out]	context	The FAPI_CONTEXT. The sub context for NV reading will be used.
[in]	min_handle	The first possible handle in the handle range.
[in]	max_handle	Maximal handle to filter out the handles not in the handle range for certificates.
[out]	cert_list	The callee allocates linked list of certificates.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_IO_ERROR	if an error occurred while accessing the object store.
TSS2_FAPI_RC_POLICY_UNKNOWN	if policy search for a certain policy digest was not successful.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_get_description()

TSS2_RC ifapi_get_description	(	IFAPI_OBJECT *	object,
		char **	description
	)

Get description of an internal FAPI object.

Parameters

[in]	object	The object with the description.
[out]	description	The callee allocated description.

Return values

TSS2_RC_SUCCESS	If a copy of the description can be returned or if no description exists.
TSS2_FAPI_RC_MEMORY	in the copy cannot be allocated.

ifapi_get_free_handle_async()

TSS2_RC ifapi_get_free_handle_async	(	FAPI_CONTEXT *	fctx,
		TPM2_HANDLE *	handle
	)

Preparation for getting a free handle after a start handle number.

Parameters

[in]	fctx	The FAPI_CONTEXT.
[in]	handle	The start value for handle search.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.

ifapi_get_free_handle_finish()

TSS2_RC ifapi_get_free_handle_finish	(	FAPI_CONTEXT *	fctx,
		TPM2_HANDLE *	handle,
		TPM2_HANDLE	max
	)

Execution of get capability until a free handle is found.

The get capability method is called until a free handle is found or the max number of trials passe to the function is exeeded.

Parameters

[in]	fctx	The FAPI_CONTEXT.
[out]	handle	The free handle.
[in]	max	The maximal number of trials.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_NV_TOO_SMALL	if too many NV handles are defined.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.

ifapi_get_json()

TSS2_RC ifapi_get_json	(	FAPI_CONTEXT *	context,
		IFAPI_OBJECT *	object,
		char **	json_string
	)

Get json encoding for FAPI object.

A json representation which can be used for exporting of a FAPI object will be created.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	object	The object to be serialized.
[out]	json_string	The json string created by the deserialzation function (callee-allocated).

Return values

TSS2_RC_SUCCESS	If the serialization was successful.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during serialization.
TSS2_FAPI_RC_BAD_REFERENCE	If a NULL pointer was passed for the object.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_ESYS_RC_*	possible error codes of ESAPI.

ifapi_get_key_properties()

ifapi_get_key_properties	(	FAPI_CONTEXT *	context,
		char const *	key_path,
		bool *	is_primary,
		bool *	in_null_hierarchy
	)

Determine key properties (primary, null hierarchy).

It will be checked whether a path is the path of a primary key, and whether it's a key in null hiearchy

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	key_path	the key path.
[out]	is_primary	if key path is the path of a primary.
[out]	in_null_hierarchy	if key is a null hierarchy key.

Return values

TSS2_RC_SUCCESS	If the preparation is successful.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_get_object_path()

ifapi_get_object_path

(

IFAPI_OBJECT *

object

)

Get relative path of a FAPI object.

Parameters

[in]

object

The internal FAPI object.

Return values

The	relative path of the object.
NULL	if no path is available.

ifapi_get_random()

TSS2_RC ifapi_get_random	(	FAPI_CONTEXT *	context,
		size_t	numBytes,
		uint8_t **	data
	)

State machine to retrieve random data from TPM.

If the buffer size exceeds the maximum size, several ESAPI calls are made.

Parameters

[in,out]	context	for storing all state information.
[in]	numBytes	Number of random bytes to be computed.
[out]	data	The random data.

Return values

TSS2_RC_SUCCESS	If random data can be computed.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.

ifapi_get_session_async()

TSS2_RC ifapi_get_session_async	(	ESYS_CONTEXT *	esys,
		ESYS_TR	saltkey,
		const IFAPI_PROFILE *	profile,
		TPMI_ALG_HASH	hashAlg
	)

Preparation for getting a session handle.

The corresponding async call be executed and a session secret for encryption TPM2B parameters will be created.

Parameters

[in]	esys	The ESYS_CONTEXT.
[in]	saltkey	The key which will be used for the encryption of the session secret.
[in]	profile	The FAPI profile will be used to adjust the sessions symmetric parameters.
[in]	hashAlg	The hash algorithm used for the session.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.

ifapi_get_session_finish()

TSS2_RC ifapi_get_session_finish	(	ESYS_CONTEXT *	esys,
		ESYS_TR *	session,
		TPMA_SESSION	flags
	)

Call for getting a session handle and adjust session parameters.

Parameters

[in]	esys	The ESYS_CONTEXT.
[out]	session	The session handle.
[in]	flags	The flags to adjust the session attributes.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.

ifapi_get_sessions_async()

TSS2_RC ifapi_get_sessions_async	(	FAPI_CONTEXT *	context,
		IFAPI_SESSION_TYPE	session_flags,
		TPMA_SESSION	attribute_flags1,
		TPMA_SESSION	attribute_flags2
	)

Prepare the session creation of a FAPI command.

The initial state of the state machine for session creation will be determined. Depending of the session_flags creation of a primary for the encryption of the session secret can be adjusted. The session passed session attributes will be used for the ESAPI command Esys_TRSess_SetAttributes.

Parameters

[in]	context	The FAPI_CONTEXT storing the used handles.
[in]	session_flags	The flags to adjust used session and encryption key. With IFAPI_SESSION1 and IFAPI_SESSION2 the session creation for sesion1 and session2 can be activated, IFAPI_SESSION_GEN_SRK triggers the creation of the primary for session secret encryption.
[in]	attribute_flags1	The attributes used for session1.
[in]	attribute_flags2	The attributes used for session2.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_PATH_NOT_FOUND	if the hierarchy file or the primary key file does not exist.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names. of the primary.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_IO_ERROR	if an error occurred while accessing the object store.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

ifapi_get_sessions_finish()

TSS2_RC ifapi_get_sessions_finish	(	FAPI_CONTEXT *	context,
		const IFAPI_PROFILE *	profile,
		TPMI_ALG_HASH	hash_alg
	)

State machine for the session creation of a FAPI command.

The sessions needed for a FAPI command will be created. If needed also the primary key for session encryption will be created.

Parameters

[in]	context	The FAPI_CONTEXT storing the used handles.
[in]	profile	The FAPI profile will be used to adjust session parameters.
[in]	hash_alg	The hash algorithm used for the session.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_IO_ERROR	if an I/O error was encountered.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_POLICY_UNKNOWN	if policy search for a certain policy digest was not successful.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

ifapi_get_sig_scheme()

TSS2_RC ifapi_get_sig_scheme	(	FAPI_CONTEXT *	context,
		IFAPI_OBJECT *	object,
		char const *	padding,
		TPM2B_DIGEST *	digest,
		TPMT_SIG_SCHEME *	sig_scheme
	)

Get signature scheme for key.

If padding is passed the scheme will be derived from paddint otherwise the scheme form object will be used.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	object	The internal FAPI object of the key.
[in]	padding	The strings RSA_SSA or RSA_PSS will be converted into the TSS constants used for the signing scheme.
[in]	digest	The digest size will be used to determine the hashalg for the signature scheme.
[out]	sig_scheme	The computed signature scheme.

Return values

TSS2_FAPI_RC_BAD_VALUE	If the digest size is not appropriate.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.

ifapi_init_primary_async()

TSS2_RC ifapi_init_primary_async	(	FAPI_CONTEXT *	context,
		TSS2_KEY_TYPE	ktype
	)

Prepare the creation of a primary key.

Depending on the parameters the creation of an endorsement or storage root key will be prepared.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	ktype	The type of key TSS2_EK or TSS2_SRK.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_VALUE	if a wrong type was passed.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_IO_ERROR	if an error occurred while accessing the object store.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

< no path needed

ifapi_initialize_object()

TSS2_RC ifapi_initialize_object	(	ESYS_CONTEXT *	ectx,
		IFAPI_OBJECT *	object
	)

Initialize the part of an IFAPI_OBJECT which is not serialized.

For persistent objects the correspodning ESYS object will be created.

Parameters

[in,out]	ectx	The ESYS context.
[out]	object	the deserialzed binary object.

Return values

TSS2_RC_SUCCESS	if the function call was a success.
TSS2_FAPI_RC_BAD_VALUE	if the json object can't be deserialized.

ifapi_key_create()

TSS2_RC ifapi_key_create	(	FAPI_CONTEXT *	context,
		IFAPI_KEY_TEMPLATE *	template
	)

State machine for key creation.

The function for the preparation of the key have to called before the state machine can be activated. The linked list for the used directories must be available in the FAPI context. It will be checked whether the object already exists in key store and the FAPI context will be initialized appropriate for key creation.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	template	The template which defines the key attributes and whether the key will be persistent.

Return values

TSS2_RC_SUCCESS	If the key could be generated.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the policy store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If an object needed for creation or authentication was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for creation fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_PATH_ALREADY_EXISTS	if the object already exists in object store.

ifapi_key_create_prepare()

TSS2_RC ifapi_key_create_prepare	(	FAPI_CONTEXT *	context,
		char const *	keyPath,
		char const *	policyPath
	)

Prepare key creation if possible.

It will be checked whether the object already exists in key store and the FAPI context will be initialized appropriate for key creation.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	keyPath	the key path without the parent directories of the key store. (e.g. HE/EK, HS/SRK/mykey)
[in]	policyPath	identifies the policy to be associated with the new key. policyPath MAY be NULL. If policyPath is NULL then no policy will be associated with the key.

Return values

TSS2_RC_SUCCESS	If the preparation was successful.
TSS2_FAPI_RC_PATH_ALREADY_EXISTS	If the object with does already exist in keystore.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_NO_TPM	if FAPI was initialized in no-TPM-mode via its config file.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_key_create_prepare_auth()

TSS2_RC ifapi_key_create_prepare_auth	(	FAPI_CONTEXT *	context,
		char const *	keyPath,
		char const *	policyPath,
		char const *	authValue
	)

Prepare key creation with an auth value.

The auth value will be copied int the FAPI context for later use in key creation.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	keyPath	the key path without the parent directories of the key store. (e.g. HE/EK, HS/SRK/mykey)
[in]	policyPath	identifies the policy to be associated with the new key. policyPath MAY be NULL. If policyPath is NULL then no policy will be associated with the key.
[in]	authValue	The authentication value of the key.

Return values

TSS2_RC_SUCCESS	If the preparation was successful.
TSS2_FAPI_RC_PATH_ALREADY_EXISTS	If the object with does already exist in keystore.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_NO_TPM	if FAPI was initialized in no-TPM-mode via its config file.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_key_create_prepare_sensitive()

TSS2_RC ifapi_key_create_prepare_sensitive	(	FAPI_CONTEXT *	context,
		char const *	keyPath,
		char const *	policyPath,
		size_t	dataSize,
		char const *	authValue,
		uint8_t const *	data
	)

Prepare key creation with an auth value and sensitive data.

The auth value and the sensitive data will be copied int the FAPI context for later use in key creation.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	keyPath	the key path without the parent directories of the key store. (e.g. HE/EK, HS/SRK/mykey)
[in]	policyPath	identifies the policy to be associated with the new key. policyPath MAY be NULL. If policyPath is NULL then no policy will be associated with the key.
[in]	dataSize	The size of the sensitive data.
[in]	authValue	The authentication value of the key.
[in]	data	The sensitive data.

Return values

TSS2_RC_SUCCESS	If the preparation was successful.
TSS2_FAPI_RC_PATH_ALREADY_EXISTS	If the object with does already exist in keystore.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_NO_TPM	if FAPI was initialized in no-TPM-mode via its config file.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_key_sign()

TSS2_RC ifapi_key_sign	(	FAPI_CONTEXT *	context,
		IFAPI_OBJECT *	sig_key_object,
		char const *	padding,
		TPM2B_DIGEST *	digest,
		TPMT_SIGNATURE **	tpm_signature,
		char **	publicKey,
		char **	certificate
	)

State machine for signing operation.

The key used for signing will be authorized and the signing of the passed data will be executed.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	sig_key_object	The Fapi key object which will be used to sign the passed digest.
[in]	padding	is the padding algorithm used. Possible values are RSA_SSA, RSA_PPSS (case insensitive). padding MAY be NULL.
[in]	digest	is the data to be signed, already hashed. digest MUST NOT be NULL.
[out]	tpm_signature	returns the signature in binary form (DER format). tpm_signature MUST NOT be NULL (callee-allocated).
[out]	publicKey	is the public key of the signing key in PEM format. publicKey is callee allocated and MAY be NULL.
[out]	certificate	is the certificate associated with the signing key in PEM format. certificate MAY be NULL.

Return values

TSS2_RC_SUCCESS	If the signing was successful.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the policy store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If a policy for a certain path was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TSS2_FAPI_RC_BAD_TEMPLATE	In a invalid policy is loaded during execution.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for policy execution fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.

ifapi_load_key()

TSS2_RC ifapi_load_key	(	FAPI_CONTEXT *	context,
		char const *	keyPath,
		IFAPI_OBJECT **	key_object
	)

Load a key and initialize profile and session for ESAPI execution.

This state machine prepares the session for key loading. Some session related parameters will be taken from profile.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	keyPath	the key path without the parent directories of the key store. (e.g. HE/EK, HS/SRK/mykey)
[out]	key_object	The callee allocated internal representation of a key object.

Return values

TSS2_RC_SUCCESS	If the key was loaded successfully.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the object store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If a policy or key was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for policy execution fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

ifapi_load_key_async()

TSS2_RC ifapi_load_key_async	(	FAPI_CONTEXT *	context,
		size_t	position
	)

Initialize state machine for loading a key.

Parameters

[in,out]	context	for storing all state information.
[in]	position	the position of the key in path list stored in context->loadKey.path_list.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.

ifapi_load_key_finish()

TSS2_RC ifapi_load_key_finish	(	FAPI_CONTEXT *	context,
		bool	flush_parent
	)

State machine for loading a key.

A stack with all sup keys will be created and decremented during the loading auf all keys. The object of the loaded key will be stored in: context->loadKey.auth_object

Parameters

[in,out]	context	for storing all state information.
[in]	flush_parent	If flush_parent is false parent is only flushed if a new parent is available.

Return values

TSS2_RC_SUCCESS	If the loading of the key was successful.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the policy store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If an object needed for loading or authentication was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for loading fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.

< to avoid scan-build errors.

< to avoid scan-build errors.

ifapi_load_keys_async()

TSS2_RC ifapi_load_keys_async	(	FAPI_CONTEXT *	context,
		char const *	keyPath
	)

Asynchronous preparation for loading a key and parent keys.

The key loading is prepared. The pathname will be extended if possible and a linked list with the directories will be created.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	keyPath	the key path without the parent directories of the key store. (e.g. HE/EK, HS/SRK/mykey)

Return values

TSS2_RC_SUCCESS	If the preparation is successful.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_load_keys_finish()

TSS2_RC ifapi_load_keys_finish	(	FAPI_CONTEXT *	context,
		bool	flush_parent,
		ESYS_TR *	handle,
		IFAPI_OBJECT **	key_object
	)

Asynchronous finish function for loading a key.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	flush_parent	If false the parent of the key to be loaded will not be flushed.
[out]	handle	The ESYS handle of the key.
[out]	key_object	The object which will be used for the authorization of the loaded key.

Return values

TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_IO_ERROR	if an error occurred while accessing the object store.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_POLICY_UNKNOWN	if policy search for a certain policy digest was not successful.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.

ifapi_load_parent_keys_async()

ifapi_load_parent_keys_async	(	FAPI_CONTEXT *	context,
		char const *	keyPath
	)

Asynchronous preparation for loading of the parent keys.

The key loading is prepared. The pathname will be extended if possible and a linked list with the directories will be created.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	keyPath	the key path without the parent directories of the key store. (e.g. HE/EK, HS/SRK/mykey)

Return values

TSS2_RC_SUCCESS	If the preparation is successful.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.
TSS2_FAPI_RC_BAD_VALUE	if an invalid value was passed into the function.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_PATH_NOT_FOUND	if a FAPI object path was not found during authorization.

ifapi_load_primary_async()

TSS2_RC ifapi_load_primary_async	(	FAPI_CONTEXT *	context,
		char *	path
	)

Prepare the loading of a primary key from key store.

The asynchronous loading or the key from keystore will be prepared and the path will be stored in the FAPI context.

Parameters

[in]	context	The FAPI_CONTEXT.
[in]	path	The FAPI path of the primary key.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_VALUE	if a wrong type was passed.
TSS2_FAPI_RC_IO_ERROR	if an I/O error was encountered.
TSS2_FAPI_RC_PATH_NOT_FOUND	if the file does not exist.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

ifapi_load_primary_finish()

TSS2_RC ifapi_load_primary_finish	(	FAPI_CONTEXT *	context,
		ESYS_TR *	handle
	)

State machine to finalize the loading of a primary key from key store.

The asynchronous loading or the key from keystore will be finalized. Afterwards the hierarchy object, which will be used for authorization will be loaded and the ESAPI functions for primary generation will be called if the primary is not persistent.

Parameters

[in]	context	The FAPI_CONTEXT.
[out]	handle	The object handle of the primary key.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_VALUE	if a wrong type was passed.
TSS2_FAPI_RC_PATH_NOT_FOUND	if the hierarchy file does not exist.
TSS2_FAPI_RC_IO_ERROR	if an I/O error was encountered.
TSS2_FAPI_RC_MEMORY	if memory could not be allocated for path names.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_GENERAL_FAILURE	if an internal error occurred.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a required authorization callback is not set.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_POLICY_UNKNOWN	if policy search for a certain policy digest was not successful.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.
TSS2_FAPI_RC_BAD_PATH	if the path is used in inappropriate context or contains illegal characters.

ifapi_merge_profile_into_nv_template()

TSS2_RC ifapi_merge_profile_into_nv_template	(	FAPI_CONTEXT *	context,
		IFAPI_NV_TEMPLATE *	template
	)

Merge profile already stored in FAPI context into a NV object template.

The defaults for NV creation which are stored in the FAPI default profile will be merged in the passed templates default values.

Parameters

[in]	context	The FAPI_CONTEXT with the default profile.
[in]	template	The template with the default values for the NV object.

Return values

TSS2_RC_SUCCESS

on success.

ifapi_merge_profile_into_template()

TSS2_RC ifapi_merge_profile_into_template	(	const IFAPI_PROFILE *	profile,
		IFAPI_KEY_TEMPLATE *	template
	)

Merge profile already stored in FAPI context into a key template.

The defaults for key creation which are stored in the FAPI default profile will be merged in the passed templates default values.

Parameters

[in]	profile	The profile which will be used to adjust the template.
[in]	template	The template with the default values for the key object.

Return values

TSS2_RC_SUCCESS

on success.

ifapi_non_tpm_mode_init()

TSS2_RC ifapi_non_tpm_mode_init

(

FAPI_CONTEXT *

context

)

Prepare session for FAPI command execution without TPM.

It will be checked whether the context of FAPI is initialized and whether no other FAPI command session is running. Also some handle variables in the context are initialized.

Parameters

[in]

context

The FAPI_CONTEXT.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_REFERENCE	if the context is not initialized.
TSS2_FAPI_RC_BAD_SEQUENCE	If a FAPI command session is active.

ifapi_nv_read()

TSS2_RC ifapi_nv_read	(	FAPI_CONTEXT *	context,
		uint8_t **	data,
		size_t *	size
	)

State machine to read data from the NV ram of the TPM.

The state machine can bes used to read NV data for a given ESAPI object or for a TPM NV index. If TPM NV index is used a ESAPI object will be created if the NV index exists. If not the size 0 will be returned. If a TPM handle is used the initial stat NV_READ_CHECK_HANDLE has to be set: context->nv_cmd.nv_read_state. Context nv_cmd has to be prepared before the call of this function: With an TPM handle:

• tpm_handle The ESAPI handle of the authorization object. With an ESYS handle:
• auth_index The ESAPI handle of the authorization object.
• numBytes The number of bytes which should be read.
• esys_handle The ESAPI handle of the NV object.

Parameters

[in,out]	context	for storing all state information.
[out]	data	the data fetched from TPM.
[in,out]	size	The number of bytes requested and fetched. will be 0 if a TPM handle is used but the NV index does not exist.

Return values

TSS2_RC_SUCCESS	If the data was read successfully.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the object store.
TSS2_FAPI_RC_PATH_NOT_FOUND	If a policy for a certain path was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for the execution fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.

ifapi_nv_write()

TSS2_RC ifapi_nv_write	(	FAPI_CONTEXT *	context,
		char *	nvPath,
		size_t	param_offset,
		uint8_t const *	data,
		size_t	size
	)

State machine to write data to the NV ram of the TPM.

The NV object will be read from object store and the data will be written by one, or more than one if necessary, ESAPI calls to the NV ram of the TPM. The sub context nv_cmd will be prepared:

• data The buffer for the data which has to be written
• offset The current offset for writing
• numBytes The number of bytes which have to be written.

Parameters

[in,out]	context	for storing all state information.
[in]	nvPath	The fapi path of the NV object.
[in]	param_offset	The offset in the NV memory (will be stored in context).
[in]	data	The pointer to the data to be written.
[in]	size	The number of bytes to be written.

Return values

TSS2_RC_SUCCESS	If data can be written.
TSS2_ESYS_RC_*	possible error codes of ESAPI.
TSS2_FAPI_RC_MEMORY	if not enough memory can be allocated.
TSS2_FAPI_RC_BAD_VALUE	If wrong values are detected during execution.
TSS2_FAPI_RC_GENERAL_FAILURE	If an internal error occurs, which is not covered by other return codes.
TSS2_FAPI_RC_IO_ERROR	If an error occurs during access to the object store.
TSS2_FAPI_RC_PATH_NOT_FOUND	The nv object or an object needed for authentication was not found.
TSS2_FAPI_RC_POLICY_UNKNOWN	If policy search for a certain policy digest was not successful.
TPM2_RC_BAD_AUTH	If the authentication for an object needed for the command execution fails.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	if a needed authorization callback is not defined.
TSS2_FAPI_RC_BAD_PATH	if a path is used in inappropriate context or contains illegal characters.
TSS2_FAPI_RC_TRY_AGAIN	if an I/O operation is not finished yet and this function needs to be called again.
TSS2_FAPI_RC_BAD_SEQUENCE	if the context has an asynchronous operation already pending.
TSS2_FAPI_RC_KEY_NOT_FOUND	if a key was not found.
TSS2_FAPI_RC_BAD_REFERENCE	a invalid null pointer is passed.
TSS2_FAPI_RC_AUTHORIZATION_FAILED	if the authorization attempt fails.
TSS2_FAPI_RC_NOT_PROVISIONED	FAPI was not provisioned.

ifapi_primary_clean()

void ifapi_primary_clean

(

FAPI_CONTEXT *

context

)

Cleanup primary keys in error cases (non asynchronous).

Parameters

[in]

context

The FAPI_CONTEXT storing the used handles.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_ESYS_RC_*	possible error codes of ESAPI.

ifapi_session_clean()

void ifapi_session_clean

(

FAPI_CONTEXT *

context

)

Cleanup FAPI sessions in error cases.

The uses sessions and the SRK (if not persistent) will be flushed non asynchronous in error cases.

Parameters

[in,out]

context

The FAPI_CONTEXT.

ifapi_session_init()

TSS2_RC ifapi_session_init

(

FAPI_CONTEXT *

context

)

Prepare session for FAPI command execution.

It will be checked whether the context of FAPI and ESAPI is initialized and whether no other FAPI command session is running. Also some handle variables in the context are initialized.

Parameters

[in]

context

The FAPI_CONTEXT.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_BAD_REFERENCE	if the context is not initialized.
TSS2_FAPI_RC_BAD_SEQUENCE	If a FAPI command session is active.
TSS2_FAPI_RC_NO_TPM	if the ESAPI context is not initialized.

ifapi_set_auth()

TSS2_RC ifapi_set_auth	(	FAPI_CONTEXT *	context,
		IFAPI_OBJECT *	auth_object,
		const char *	description
	)

Set authorization value for a FAPI object.

The callback which provides the auth value must be defined.

Parameters

[in,out]	context	The FAPI_CONTEXT.
[in]	auth_object	The auth value will be assigned to this object.
[in]	description	The description will be passed to the callback which delivers the auth value.

Return values

TSS2_RC_SUCCESS	on success.
TSS2_FAPI_RC_AUTHORIZATION_UNKNOWN	If the callback for getting the auth value is not defined.

ifapi_set_description()

void ifapi_set_description	(	IFAPI_OBJECT *	object,
		char *	description
	)

Set description of an internal FAPI object.

Parameters

[in,out]	object	The object with the description.
[in]	description	The description char strint or NULL.