Adding upstream version 0.9.2.upstream/0.9.2upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 287 insertions, 0 deletions

diff --git a/man/man3/TPMLIB_RegisterCallbacks.pod b/man/man3/TPMLIB_RegisterCallbacks.pod
new file mode 100644
index 0000000..0f698b9
--- /dev/null
+++ b/man/man3/TPMLIB_RegisterCallbacks.pod
@@ -0,0 +1,287 @@
+
+
+=head1 NAME
+
+TPMLIB_RegisterCallbacks    - Register callbacks for implementing customized
+behavior of certain functions
+
+=head1 LIBRARY
+
+TPM library (libtpms, -ltpms)
+
+=head1 SYNOPSIS
+
+B<#include <libtpms/tpm_types.h>>
+
+B<#include <libtpms/tpm_library.h>>
+
+B<#include <libtpms/tpm_error.h>>
+
+B<TPM_RESULT TPMLIB_RegisterCallbacks(struct tpmlibrary_callbacks *);>
+
+=head1 DESCRIPTION
+
+The B<TPMLIB_RegisterCallbacks()> functions allows to register several
+callback functions with libtpms that enable a user to implement customized
+behavior of several library-internal functions. This feature will typically
+be used if the behavior of the provided internal functions is not as needed.
+An example would be that libtpms writes all data into files with certain names.
+If, however, the data needs to be written into a special type of storage
+the user will register callbacks with the library that are invoked when
+the TPM needs to write, read or delete data from storage and the user may
+then implement custom behavior in these functions.
+
+The following shows the data structure used for registering the callbacks.
+
+    struct libtpms_callbacks {  
+	    int sizeOfStruct;
+	    TPM_RESULT (*tpm_nvram_init)(void);
+	    TPM_RESULT (*tpm_nvram_loaddata)(unsigned char **data,
+	                                     uint32_t *length,
+	                                     uint32_t tpm_number,
+	                                     const char *name);
+	    TPM_RESULT (*tpm_nvram_storedata)(const unsigned char *data,
+	                                      uint32_t length,
+	                                      uint32_t tpm_number,
+	                                      const char *name);
+	    TPM_RESULT (*tpm_nvram_deletename)(uint32_t tpm_number,
+	                                       const char *name,
+	                                       TPM_BOOL mustExist);
+	    TPM_RESULT (*tpm_io_init)(void);
+	    TPM_RESULT (*tpm_io_getlocality)(TPM_MODIFIER_INDICATOR *localityModifer,
+                                             uint32_t tpm_number);
+	    TPM_RESULT (*tpm_io_getphysicalpresence)(TPM_BOOL *physicalPresence,
+                                                     uint32_t tpm_number);
+    };
+
+Currently 7 callbacks are supported. If a callback pointer in the above
+structure is set to NULL the default library-internal implementation
+of that function will be used.
+
+If one of the callbacks in either the I<tpm_nvram> or I<tpm_io> group is
+set, then all of the callbacks in the respective group should
+be implemented.
+
+=over 4
+
+=item B<tpm_nvram_init>
+
+This function is called before any access to persitent storage is done. It
+allows the user to perform initialization of access to persitent storage.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation requires that the environment variable
+I<TPM_PATH> is set and points to a directory where the TPM's state
+can be written to. If the variable is not set, it will return B<TPM_FAIL>
+and the initialization of the TPM in B<TPMLIB_MainInit()> will fail.
+
+=item B<tpm_nvram_loaddata>
+
+This function is called when the TPM wants to load state from persistent
+storage. The implementing function must allocate a buffer (I<data>)
+and return it to the TPM along with the length of the buffer (I<length>).
+The I<tpm_number> is always 0 and can be ignored. 
+The I<name> parameter is either one of B<TPM_SAVESTATE_NAME>,
+B<TPM_VOLATILESTATE_NAME>, or B<TPM_PERMANENT_ALL_NAME> and indicates
+which one of the 3 types of state is supposed to be loaded.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation writes the TPM's state into files in a directory
+where the I<TPM_PATH> environment variable pointed to when
+B<TPMLIB_MainInit()> was executed. Failure to write the TPM's state into
+files will put the TPM into failure mode.
+
+If this function is not set (NULL), then the original NVChip file
+will be read when using a TPM 2. This file contains the memory dump of
+internal data structures and is neither portable between endianesses or
+architectures of different sizes (32 bit, 64 bit), nor will it allow
+handling extensions of those internal data structures it carries
+through additions in the TPM 2 code. In the worst case this may result
+in memory access errors by internal functions and result in crashes.
+Therefore, it is recommended to set this function and handle the writing
+of the TPM state.
+
+=item B<tpm_nvram_storedata>
+
+This function is called when the TPM wants to store state to persistent
+storage. The I<data> and I<length> parameters provide the data to be
+stored and the number of bytes. The implementing function must not
+free the I<data> buffer.
+The I<tpm_number> is always 0 and can be ignored. 
+The I<name> parameter is either one of B<TPM_SAVESTATE_NAME>,
+B<TPM_VOLATILESTATE_NAME>, or B<TPM_PERMANENT_ALL_NAME> and indicates
+which one of the 3 types of state is supposed to be stored.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation reads the TPM's state from files in a directory
+where the I<TPM_PATH> environment variable pointed to when
+B<TPMLIB_MainInit()> was executed. Failure to read the TPM's state from
+files may put the TPM into failure mode.
+
+If this function is not set (NULL), the memory dump will be written
+to the NVChip file (TPM 2) and the same comments apply as when the
+I<tpm_nvram_loaddata> interface function is not set.
+
+=item B<tpm_nvram_deletename>
+
+This function is called when the TPM wants to delete state on persistent
+storage. 
+The I<tpm_number> is always 0 and can be ignored. 
+The I<name> parameter is either one of B<TPM_SAVESTATE_NAME>,
+B<TPM_VOLATILESTATE_NAME>, or B<TPM_PERMANENT_ALL_NAME> and indicates
+which one of the 3 types of state is supposed to be deleted.
+The I<mustExist> parameter indicates whether the given data must exist
+and the implementing function should return B<TPM_FAIL> if the data did
+not exist.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation deletes the TPM's state files in a directory
+where the I<TPM_PATH> environment variable pointed to when
+B<TPMLIB_MainInit()> was executed. Failure to delete the TPM's state
+files may put the TPM into failure mode.
+
+=item B<tpm_io_init>
+
+This function is called to initialize the IO subsystem of the TPM.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation simply returns B<TPM_SUCCESS>.
+
+=item B<tpm_io_getlocality>
+
+This function is called when the TPM needs to determine the locality
+under which a command is supposed to be executed. The implementing function
+should return the number of the locality by writing it into the 
+B<localityModifier> pointer.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation returns 0 as the locality.
+
+=item B<tpm_io_getphysicalpresence>
+
+This function is called when the TPM needs to determine whether physical
+presence has been asserted. The implementing function should write either
+B<TRUE> or B<FALSE> into the physicalPresence pointer.
+
+Upon success this function should return B<TPM_SUCCESS>, a failure code
+otherwise.
+
+The default implementation returns B<FALSE> for physical presence.
+
+=back
+
+=head1 RETURN VALUE
+
+Upon successful completion, B<TPMLIB_MainInit()> returns B<TPM_SUCCESS>,
+an error value otherwise.
+
+=head1 ERRORS
+
+=over 4
+
+=item B<TPM_SUCCESS>
+
+The function completed successfully.
+
+=item B<TPM_FAIL>
+
+General failure.
+
+=back
+
+For a complete list of TPM error codes please consult the include file
+B<libtpms/tpm_error.h>
+
+=head1 EXAMPLE
+
+ #include <libtpms/tpm_types.h>
+ #include <libtpms/tpm_library.h>
+ #include <libtpms/tpm_error.h>
+
+ static TPM_MODIFIER_INDICATOR locality;
+
+ static TPM_RESULT mytpm_io_init(void)
+ {
+ 	return TPM_SUCCESS;
+ }
+
+ static TPM_RESULT mytpm_io_getlocality(TPM_MODIFIER_INDICATOR *locModif,
+                                        uint32_t tpm_number)
+ {
+ 	*locModif = locality;
+
+ 	return TPM_SUCCESS:
+ }
+
+ static TPM_RESULT mytpm_io_getphysicalpresence(TPM_BOOL *physicalPresence,
+                                                uint32_t tpm_number)
+ {
+ 	*physicalPresence = FALSE;
+
+ 	return TPM_SUCCESS;
+ }
+
+ int main(void) {
+     TPM_RESULT res;
+     unsigned char *respbuffer;
+     uint32_t resp_size;
+     uint32_t respbufsize;
+     unsigned char *command;
+     uint32_t command_size;
+
+     struct libtpms_callbacks cbs = {
+         .sizeOfStruct               = sizeof(struct libtpms_callbacks),
+         .tpm_nvram_init             = NULL,
+         .tpm_nvram_loaddata         = NULL,
+         .tpm_nvram_storedata        = NULL,
+         .tpm_nvram_deletename       = NULL,
+         .tpm_io_init                = mytpm_io_init,
+         .tpm_io_getlocality         = mytpm_io_getlocality,
+         .tpm_io_getphysicalpresence = mytpm_io_getphysicalpresence,
+     };
+
+
+     [...]
+
+     if (TPMLIB_RegisterCallbacks(&cbs) != TPM_SUCCESS) {
+         fprintf(stderr, "Could not register the callbacks.\n");
+         return 1;
+     }
+
+     if (TPMLIB_MainInit()) != TPM_SUCCESS) {
+         fprintf(stderr, "Could not start the TPM.\n");
+         return 1;
+     }
+
+     [...]
+     /* build TPM command */
+     [...]
+
+     res = TPMLIB_Process(&respbuffer, &resp_size,
+                          &respbufsize,
+                          command, command_size);
+     [...]
+
+     TPMLIB_Terminate();
+
+     return 0;
+ }
+
+=head1 SEE ALSO
+
+B<TPMLIB_Process>(3), B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3),
+B<TPMLIB_DecodeBlobs>(3)
+
+=cut