.TH "ifapi_keystore" 3 "Fri Oct 7 2022" "Version 3.2.0" "tpm2-tss" \" -*- nroff -*- .ad l .nh .SH NAME ifapi_keystore .SH SYNOPSIS .br .PP .SS "Functions" .in +1c .ti -1c .RI "void \fBifapi_cleanup_ifapi_duplicate\fP (\fBIFAPI_DUPLICATE\fP *duplicate)" .br .ti -1c .RI "void \fBifapi_cleanup_ifapi_ext_pub_key\fP (\fBIFAPI_EXT_PUB_KEY\fP *key)" .br .ti -1c .RI "void \fBifapi_cleanup_ifapi_hierarchy\fP (\fBIFAPI_HIERARCHY\fP *hierarchy)" .br .ti -1c .RI "void \fBifapi_cleanup_ifapi_key\fP (\fBIFAPI_KEY\fP *key)" .br .ti -1c .RI "void \fBifapi_cleanup_ifapi_keystore\fP (\fBIFAPI_KEYSTORE\fP *keystore)" .br .ti -1c .RI "void \fBifapi_cleanup_ifapi_nv\fP (\fBIFAPI_NV\fP *nv)" .br .ti -1c .RI "void \fBifapi_cleanup_ifapi_object\fP (\fBIFAPI_OBJECT\fP *object)" .br .ti -1c .RI "TSS2_RC \fBifapi_copy_ifapi_key\fP (\fBIFAPI_KEY\fP *dest, const \fBIFAPI_KEY\fP *src)" .br .ti -1c .RI "TSS2_RC \fBifapi_copy_ifapi_key_object\fP (\fBIFAPI_OBJECT\fP *dest, const \fBIFAPI_OBJECT\fP *src)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_delete\fP (\fBIFAPI_KEYSTORE\fP *keystore, char *path)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_initialize\fP (\fBIFAPI_KEYSTORE\fP *keystore, const char *config_systemdir, const char *config_userdir, const char *config_defaultprofile)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_list_all\fP (\fBIFAPI_KEYSTORE\fP *keystore, const char *searchpath, char ***results, size_t *numresults)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_load_async\fP (\fBIFAPI_KEYSTORE\fP *keystore, \fBIFAPI_IO\fP *io, const char *path)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_load_finish\fP (\fBIFAPI_KEYSTORE\fP *keystore, \fBIFAPI_IO\fP *io, \fBIFAPI_OBJECT\fP *object)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_remove_directories\fP (\fBIFAPI_KEYSTORE\fP *keystore, const char *dir_name)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_search_nv_obj\fP (\fBIFAPI_KEYSTORE\fP *keystore, \fBIFAPI_IO\fP *io, TPM2B_NV_PUBLIC *nv_public, char **found_path)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_search_obj\fP (\fBIFAPI_KEYSTORE\fP *keystore, \fBIFAPI_IO\fP *io, TPM2B_NAME *name, char **found_path)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_store_async\fP (\fBIFAPI_KEYSTORE\fP *keystore, \fBIFAPI_IO\fP *io, const char *path, const \fBIFAPI_OBJECT\fP *object)" .br .ti -1c .RI "TSS2_RC \fBifapi_copy_ifapi_hierarchy\fP (\fBIFAPI_HIERARCHY\fP *dest, const \fBIFAPI_HIERARCHY\fP *src)" .br .ti -1c .RI "TSS2_RC \fBifapi_copy_ifapi_hierarchy_object\fP (\fBIFAPI_OBJECT\fP *dest, const \fBIFAPI_OBJECT\fP *src)" .br .ti -1c .RI "TSS2_RC \fBifapi_keystore_object_does_not_exist\fP (\fBIFAPI_KEYSTORE\fP *keystore, const char *path, const \fBIFAPI_OBJECT\fP *object)" .br .in -1c .SH "Detailed Description" .PP Provides internal fapi functions for reading and writing to the key store\&. .SH "Function Documentation" .PP .SS "void ifapi_cleanup_ifapi_duplicate (\fBIFAPI_DUPLICATE\fP * duplicate)" Free memory allocated during deserialization of a duplicate object\&. .PP The duplicate object will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fIduplicate\fP The duplicate object to be cleaned up\&. .RE .PP .SS "void ifapi_cleanup_ifapi_ext_pub_key (\fBIFAPI_EXT_PUB_KEY\fP * key)" Free memory allocated during deserialization of a pubkey object\&. .PP The pubkey will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fIkey\fP The pubkey object to be cleaned up\&. .RE .PP .SS "void ifapi_cleanup_ifapi_hierarchy (\fBIFAPI_HIERARCHY\fP * hierarchy)" Free memory allocated during deserialization of a hierarchy object\&. .PP The hierarchy object will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fIhierarchy\fP The hierarchy object to be cleaned up\&. .RE .PP .SS "void ifapi_cleanup_ifapi_key (\fBIFAPI_KEY\fP * key)" Free memory allocated during deserialization of a key object\&. .PP The key will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fIkey\fP The key object to be cleaned up\&. .RE .PP .SS "void ifapi_cleanup_ifapi_keystore (\fBIFAPI_KEYSTORE\fP * keystore)" Free keystore related memory allocated during FAPI initialization\&. .PP The keystore object will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The kystore object to be cleaned up\&. .RE .PP .SS "void ifapi_cleanup_ifapi_nv (\fBIFAPI_NV\fP * nv)" Free memory allocated during deserialization of a nv object\&. .PP The nv object will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fInv\fP The nv object to be cleaned up\&. .RE .PP .SS "void ifapi_cleanup_ifapi_object (\fBIFAPI_OBJECT\fP * object)" Free memory allocated during deserialization of object\&. .PP The object will not be freed (might be declared on the stack)\&. .PP \fBParameters:\fP .RS 4 \fIobject\fP The object to be cleaned up\&. .RE .PP .SS "ifapi_copy_ifapi_hierarchy (\fBIFAPI_HIERARCHY\fP * dest, const \fBIFAPI_HIERARCHY\fP * src)" Create a copy of a an ifapi hierarchy\&. .PP \fBParameters:\fP .RS 4 \fIdest\fP The caller allocated hierarchy object which will be the destination of the copy operation\&. .br \fIsrc\fP The source hierarchy\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP if the function call was a success\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_MEMORY\fP if not enough memory can be allocated\&. .RE .PP .SS "ifapi_copy_ifapi_hierarchy_object (\fBIFAPI_OBJECT\fP * dest, const \fBIFAPI_OBJECT\fP * src)" Create a copy of a an ifapi object storing a hierarchy\&. .PP The hierarchy together with the policy of the hierarchy will be copied\&. .PP \fBParameters:\fP .RS 4 \fIdest\fP The caller allocated hierarchy object which will be the destination of the copy operation\&. .br \fIsrc\fP The source hieararchy\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP if the function call was a success\&. .br \fITSS2_FAPI_RC_GENERAL_FAILURE\fP if the source is not of type key\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_MEMORY\fP if not enough memory can be allocated\&. .RE .PP .SS "TSS2_RC ifapi_copy_ifapi_key (\fBIFAPI_KEY\fP * dest, const \fBIFAPI_KEY\fP * src)" Create a copy of a an ifapi key\&. .PP \fBParameters:\fP .RS 4 \fIdest\fP The caller allocated key object which will be the destination of the copy operation\&. .br \fIsrc\fP The source key\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP if the function call was a success\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_MEMORY\fP if not enough memory can be allocated\&. .RE .PP .SS "TSS2_RC ifapi_copy_ifapi_key_object (\fBIFAPI_OBJECT\fP * dest, const \fBIFAPI_OBJECT\fP * src)" Create a copy of a an ifapi object storing a key\&. .PP The key together with the policy of the key will be copied\&. .PP \fBParameters:\fP .RS 4 \fIdest\fP The caller allocated key object which will be the destination of the copy operation\&. .br \fIsrc\fP The source key\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP if the function call was a success\&. .br \fITSS2_FAPI_RC_GENERAL_FAILURE\fP if the source is not of type key\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_MEMORY\fP if not enough memory can be allocated\&. .RE .PP .SS "TSS2_RC ifapi_keystore_delete (\fBIFAPI_KEYSTORE\fP * keystore, char * path)" Remove file storing a keystore object\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories, the default profile\&. .br \fIpath\fP The relative name of the object be removed\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP On success\&. .br \fITSS2_FAPI_RC_MEMORY\fP If memory could not be allocated\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP If the file can't be removed\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .br \fITSS2_FAPI_RC_KEY_NOT_FOUND\fP if a key was not found\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_NOT_PROVISIONED\fP FAPI was not provisioned\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .RE .PP .SS "TSS2_RC ifapi_keystore_initialize (\fBIFAPI_KEYSTORE\fP * keystore, const char * config_systemdir, const char * config_userdir, const char * config_defaultprofile)" Store keystore parameters in the keystore context\&. .PP Also the user directory will be created if it does not exist\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The keystore to be initialized\&. .br \fIconfig_systemdir\fP The configured system directory\&. .br \fIconfig_userdir\fP The configured user directory\&. .br \fIconfig_defaultprofile\fP The configured profile\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP If the keystore can be initialized\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP If the user part of the keystore can't be initialized\&. .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the home directory of the user cannot be determined\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .RE .PP .SS "TSS2_RC ifapi_keystore_list_all (\fBIFAPI_KEYSTORE\fP * keystore, const char * searchpath, char *** results, size_t * numresults)" Create a list of of objects in a certain search path\&. .PP A vector of relative paths will be computed\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories, the default profile\&. .br \fIsearchpath\fP The relative search path in key store\&. .br \fIresults\fP The array with pointers to the relative object paths\&. .br \fInumresults\fP The number of found objects\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP on success\&. .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .RE .PP .SS "TSS2_RC ifapi_keystore_load_async (\fBIFAPI_KEYSTORE\fP * keystore, \fBIFAPI_IO\fP * io, const char * path)" Start loading FAPI object from key store\&. .PP Keys objects, NV objects, and hierarchies can be loaded\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories and default profile\&. .br \fIio\fP The input/output context being used for file I/O\&. .br \fIpath\fP The relative path of the object\&. For keys the path will expanded if possible\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP If the object can be read\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP if an I/O error was encountered\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if the file does not exist\&. .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated to hold the read data\&. .br \fITSS2_FAPI_RC_KEY_NOT_FOUND\fP if a key was not found\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_NOT_PROVISIONED\fP FAPI was not provisioned\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .RE .PP .SS "ifapi_keystore_object_does_not_exist (\fBIFAPI_KEYSTORE\fP * keystore, const char * path, const \fBIFAPI_OBJECT\fP * object)" Check whether the key path for a new object does not exist in key store\&. .PP To prevent overwriting of objects the functions returns an error if the object is already stored in key store\&. The FAPI path will be expanded to absolute path appropriate for the object to be checked\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories and default profile\&. .br \fIpath\fP The relative path of the object\&. For keys the path will expanded if possible\&. .br \fIobject\fP The object to be checked\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP if the object does not exist and a new object can be written\&. .br \fITSS2_FAPI_RC_PATH_ALREADY_EXISTS\fP if the object exists in key store\&. .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated to hold the output data\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .RE .PP .SS "TSS2_RC ifapi_keystore_remove_directories (\fBIFAPI_KEYSTORE\fP * keystore, const char * dir_name)" Remove directories in keystore\&. .PP If the expanded directory exists in userdir and systemdir both will be deleted\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories, the default profile\&. .br \fIdir_name\fP The relative name of the directory to be removed\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP on success\&. .br \fITSS2_FAPI_RC_MEMORY\fP If memory could not be allocated\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP If directory can't be deleted\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .RE .PP .SS "TSS2_RC ifapi_keystore_search_nv_obj (\fBIFAPI_KEYSTORE\fP * keystore, \fBIFAPI_IO\fP * io, TPM2B_NV_PUBLIC * nv_public, char ** found_path)" Search nv object with a certain nv_index (from nv_public) in keystore\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories, the default profile, and the state information for the asynchronous search\&. .br \fIio\fP The input/output context being used for file I/O\&. .br \fInv_public\fP The public data of the searched nv object\&. .br \fIfound_path\fP The relative path of the found key\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP on success\&. .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated\&. .br \fITSS2_FAPI_RC_KEY_NOT_FOUND\fP If the key was not found in keystore\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .br \fITSS2_FAPI_RC_TRY_AGAIN\fP if an I/O operation is not finished yet and this function needs to be called again\&. .br \fITSS2_FAPI_RC_BAD_SEQUENCE\fP if the context has an asynchronous operation already pending\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP if an error occurred while accessing the object store\&. .br \fITSS2_FAPI_RC_GENERAL_FAILURE\fP if an internal error occurred\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_PATH_ALREADY_EXISTS\fP if the object already exists in object store\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .br \fITSS2_FAPI_RC_NOT_PROVISIONED\fP FAPI was not provisioned\&. .RE .PP .SS "TSS2_RC ifapi_keystore_search_obj (\fBIFAPI_KEYSTORE\fP * keystore, \fBIFAPI_IO\fP * io, TPM2B_NAME * name, char ** found_path)" Search object with a certain name in keystore\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories, the default profile, and the state information for the asynchronous search\&. .br \fIio\fP The input/output context being used for file I/O\&. .br \fIname\fP The name of the searched object\&. .br \fIfound_path\fP The relative path of the found key\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP on success\&. .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated\&. .br \fITSS2_FAPI_RC_KEY_NOT_FOUND\fP If the key was not found in keystore\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .br \fITSS2_FAPI_RC_TRY_AGAIN\fP if an I/O operation is not finished yet and this function needs to be called again\&. .br \fITSS2_FAPI_RC_BAD_SEQUENCE\fP if the context has an asynchronous operation already pending\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP if an error occurred while accessing the object store\&. .br \fITSS2_FAPI_RC_GENERAL_FAILURE\fP if an internal error occurred\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .br \fITSS2_FAPI_RC_NOT_PROVISIONED\fP FAPI was not provisioned\&. .RE .PP .SS "TSS2_RC ifapi_keystore_store_async (\fBIFAPI_KEYSTORE\fP * keystore, \fBIFAPI_IO\fP * io, const char * path, const \fBIFAPI_OBJECT\fP * object)" Start writing FAPI object to the key store\&. .PP Keys objects, NV objects, and hierarchies can be written\&. .PP \fBParameters:\fP .RS 4 \fIkeystore\fP The key directories and default profile\&. .br \fIio\fP The input/output context being used for file I/O\&. .br \fIpath\fP The relative path of the object\&. For keys the path will expanded if possible\&. .br \fIobject\fP The object to be written to the keystore\&. .RE .PP \fBReturn values:\fP .RS 4 \fITSS2_RC_SUCCESS\fP if the object is written successfully\&. .br \fITSS2_FAPI_RC_IO_ERROR\fP if an I/O error was encountered; .br \fITSS2_FAPI_RC_MEMORY\fP if memory could not be allocated to hold the output data\&. .br \fITSS2_FAPI_RC_BAD_VALUE\fP if an invalid value was passed into the function\&. .br \fITSS2_FAPI_RC_GENERAL_FAILURE\fP if an internal error occurred\&. .br \fITSS2_FAPI_RC_BAD_REFERENCE\fP a invalid null pointer is passed\&. .br \fITSS2_FAPI_RC_BAD_PATH\fP if the path is used in inappropriate context or contains illegal characters\&. .br \fITSS2_FAPI_RC_PATH_NOT_FOUND\fP if a FAPI object path was not found during authorization\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for tpm2-tss from the source code\&.