Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
TPMLIB_RegisterCallbacks(3)			   TPMLIB_RegisterCallbacks(3)

NAME
       TPMLIB_RegisterCallbacks	   - Register callbacks	for implementing
       customized behavior of certain functions

LIBRARY
       TPM library (libtpms, -ltpms)

SYNOPSIS
       #include	<libtpms/tpm_types.h>

       #include	<libtpms/tpm_library.h>

       #include	<libtpms/tpm_error.h>

       TPM_RESULT TPMLIB_RegisterCallbacks(struct tpmlibrary_callbacks *);

DESCRIPTION
       The 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 tpm_nvram or tpm_io group is set,
       then all	of the callbacks in the	respective group should	be
       implemented.

       tpm_nvram_init
	   This	function is called before any access to	persistent storage is
	   done. It allows the user to perform initialization of access	to
	   persistent storage.

	   Upon	success	this function should return TPM_SUCCESS, a failure
	   code	otherwise.

	   The default implementation requires that the	environment variable
	   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 TPM_FAIL
	   and the initialization of the TPM in	TPMLIB_MainInit() will fail.

       tpm_nvram_loaddata
	   This	function is called when	the TPM	wants to load state from
	   persistent storage. The implementing	function must allocate a
	   buffer (data) and return it to the TPM along	with the length	of the
	   buffer (length).  The tpm_number is always 0	and can	be ignored.
	   The name parameter is either	one of TPM_SAVESTATE_NAME,
	   TPM_VOLATILESTATE_NAME, or 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 TPM_SUCCESS, a failure
	   code	otherwise.

	   The default implementation writes the TPM's state into files	in a
	   directory where the TPM_PATH	environment variable pointed to	when
	   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.

       tpm_nvram_storedata
	   This	function is called when	the TPM	wants to store state to
	   persistent storage. The data	and length parameters provide the data
	   to be stored	and the	number of bytes. The implementing function
	   must	not free the data buffer.  The tpm_number is always 0 and can
	   be ignored.	The name parameter is either one of
	   TPM_SAVESTATE_NAME, TPM_VOLATILESTATE_NAME, or
	   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 TPM_SUCCESS, a failure
	   code	otherwise.

	   The default implementation reads the	TPM's state from files in a
	   directory where the TPM_PATH	environment variable pointed to	when
	   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
	   tpm_nvram_loaddata interface	function is not	set.

       tpm_nvram_deletename
	   This	function is called when	the TPM	wants to delete	state on
	   persistent storage.	The tpm_number is always 0 and can be ignored.
	   The name parameter is either	one of TPM_SAVESTATE_NAME,
	   TPM_VOLATILESTATE_NAME, or TPM_PERMANENT_ALL_NAME and indicates
	   which one of	the 3 types of state is	supposed to be deleted.	 The
	   mustExist parameter indicates whether the given data	must exist and
	   the implementing function should return TPM_FAIL if the data	did
	   not exist.

	   Upon	success	this function should return TPM_SUCCESS, a failure
	   code	otherwise.

	   The default implementation deletes the TPM's	state files in a
	   directory where the TPM_PATH	environment variable pointed to	when
	   TPMLIB_MainInit() was executed. Failure to delete the TPM's state
	   files may put the TPM into failure mode.

       tpm_io_init
	   This	function is called to initialize the IO	subsystem of the TPM.

	   Upon	success	this function should return TPM_SUCCESS, a failure
	   code	otherwise.

	   The default implementation simply returns TPM_SUCCESS.

       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 localityModifier	pointer.

	   This	function is expected to	return TPM_SUCCESS along with a	valid
	   locality number. The	program	implementing the called	function is
	   trusted to manage locality numbers correctly.

	   The default implementation returns 0	as the locality.

       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 TRUE or FALSE into the physicalPresence
	   pointer.

	   Upon	success	this function should return TPM_SUCCESS, a failure
	   code	otherwise.

	   The default implementation returns FALSE for	physical presence.

RETURN VALUE
       Upon successful completion, TPMLIB_MainInit() returns TPM_SUCCESS, an
       error value otherwise.

ERRORS
       TPM_SUCCESS
	   The function	completed successfully.

       TPM_FAIL
	   General failure.

       For a complete list of TPM error	codes please consult the include file
       libtpms/tpm_error.h

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;
	}

SEE ALSO
       TPMLIB_Process(3), TPMLIB_MainInit(3), TPMLIB_Terminate(3),
       TPMLIB_DecodeBlobs(3)

libtpms				  2025-06-10	   TPMLIB_RegisterCallbacks(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=TPMLIB_RegisterCallbacks&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help