Utility module
Feature API » Internals of Feature API

## 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_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()

TSS2_RC 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()

TSS2_RC 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()

const char * 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()

TSS2_RC 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.