From 92cccad89d1c12b39165d5f0ed7ccd2d44965a1a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 23:41:43 +0200 Subject: Adding upstream version 0.9.2. Signed-off-by: Daniel Baumann --- man/man3/Makefile.am | 67 ++++++++ man/man3/TPMLIB_CancelCommand.pod | 29 ++++ man/man3/TPMLIB_ChooseTPMVersion.pod | 52 ++++++ man/man3/TPMLIB_DecodeBlob.pod | 66 ++++++++ man/man3/TPMLIB_GetInfo.pod | 52 ++++++ man/man3/TPMLIB_GetState.3 | 1 + man/man3/TPMLIB_GetTPMProperty.pod | 153 ++++++++++++++++++ man/man3/TPMLIB_GetVersion.pod | 30 ++++ man/man3/TPMLIB_MainInit.pod | 96 +++++++++++ man/man3/TPMLIB_Process.pod | 108 +++++++++++++ man/man3/TPMLIB_RegisterCallbacks.pod | 287 +++++++++++++++++++++++++++++++++ man/man3/TPMLIB_SetBufferSize.pod | 37 +++++ man/man3/TPMLIB_SetDebugFD.pod | 38 +++++ man/man3/TPMLIB_SetDebugLevel.3 | 1 + man/man3/TPMLIB_SetDebugPrefix.3 | 1 + man/man3/TPMLIB_SetState.pod | 54 +++++++ man/man3/TPMLIB_Terminate.3 | 1 + man/man3/TPMLIB_ValidateState.pod | 44 +++++ man/man3/TPMLIB_VolatileAll_Store.pod | 45 ++++++ man/man3/TPM_Free.3 | 1 + man/man3/TPM_IO_Hash_Data.3 | 1 + man/man3/TPM_IO_Hash_End.3 | 1 + man/man3/TPM_IO_Hash_Start.pod | 78 +++++++++ man/man3/TPM_IO_TpmEstablished_Get.pod | 58 +++++++ man/man3/TPM_IO_TpmEstablished_Reset.3 | 1 + man/man3/TPM_Malloc.pod | 72 +++++++++ man/man3/TPM_Realloc.3 | 1 + 27 files changed, 1375 insertions(+) create mode 100644 man/man3/Makefile.am create mode 100644 man/man3/TPMLIB_CancelCommand.pod create mode 100644 man/man3/TPMLIB_ChooseTPMVersion.pod create mode 100644 man/man3/TPMLIB_DecodeBlob.pod create mode 100644 man/man3/TPMLIB_GetInfo.pod create mode 100644 man/man3/TPMLIB_GetState.3 create mode 100644 man/man3/TPMLIB_GetTPMProperty.pod create mode 100644 man/man3/TPMLIB_GetVersion.pod create mode 100644 man/man3/TPMLIB_MainInit.pod create mode 100644 man/man3/TPMLIB_Process.pod create mode 100644 man/man3/TPMLIB_RegisterCallbacks.pod create mode 100644 man/man3/TPMLIB_SetBufferSize.pod create mode 100644 man/man3/TPMLIB_SetDebugFD.pod create mode 100644 man/man3/TPMLIB_SetDebugLevel.3 create mode 100644 man/man3/TPMLIB_SetDebugPrefix.3 create mode 100644 man/man3/TPMLIB_SetState.pod create mode 100644 man/man3/TPMLIB_Terminate.3 create mode 100644 man/man3/TPMLIB_ValidateState.pod create mode 100644 man/man3/TPMLIB_VolatileAll_Store.pod create mode 100644 man/man3/TPM_Free.3 create mode 100644 man/man3/TPM_IO_Hash_Data.3 create mode 100644 man/man3/TPM_IO_Hash_End.3 create mode 100644 man/man3/TPM_IO_Hash_Start.pod create mode 100644 man/man3/TPM_IO_TpmEstablished_Get.pod create mode 100644 man/man3/TPM_IO_TpmEstablished_Reset.3 create mode 100644 man/man3/TPM_Malloc.pod create mode 100644 man/man3/TPM_Realloc.3 (limited to 'man/man3') diff --git a/man/man3/Makefile.am b/man/man3/Makefile.am new file mode 100644 index 0000000..da8ec0f --- /dev/null +++ b/man/man3/Makefile.am @@ -0,0 +1,67 @@ +# +# man/man3/Makefile.am +# +# For the license, see the LICENSE file in the root directory. +# + + +man3_PODS = \ + TPM_IO_Hash_Start.pod \ + TPM_IO_TpmEstablished_Get.pod \ + TPMLIB_CancelCommand.pod \ + TPMLIB_ChooseTPMVersion.pod \ + TPMLIB_DecodeBlob.pod \ + TPMLIB_GetInfo.pod \ + TPMLIB_GetTPMProperty.pod \ + TPMLIB_GetVersion.pod \ + TPMLIB_MainInit.pod \ + TPMLIB_Process.pod \ + TPMLIB_RegisterCallbacks.pod \ + TPMLIB_SetBufferSize.pod \ + TPMLIB_SetDebugFD.pod \ + TPMLIB_SetState.pod \ + TPMLIB_ValidateState.pod \ + TPMLIB_VolatileAll_Store.pod \ + TPM_Malloc.pod + +man3_MANS = \ + TPM_Free.3 \ + TPM_IO_Hash_Data.3 \ + TPM_IO_Hash_End.3 \ + TPMLIB_GetState.3 \ + TPMLIB_SetDebugPrefix.3 \ + TPMLIB_SetDebugLevel.3 \ + TPM_IO_TpmEstablished_Reset.3 \ + TPMLIB_Terminate.3 \ + TPM_Realloc.3 + +man3_MANS_generated = \ + TPM_IO_Hash_Start.3 \ + TPM_IO_TpmEstablished_Get.3 \ + TPMLIB_CancelCommand.3 \ + TPMLIB_ChooseTPMVersion.3 \ + TPMLIB_DecodeBlob.3 \ + TPMLIB_GetInfo.3 \ + TPMLIB_GetTPMProperty.3 \ + TPMLIB_GetVersion.3 \ + TPMLIB_MainInit.3 \ + TPMLIB_Process.3 \ + TPMLIB_SetDebugFD.3 \ + TPMLIB_SetBufferSize.3 \ + TPMLIB_SetState.3 \ + TPMLIB_RegisterCallbacks.3 \ + TPMLIB_ValidateState.3 \ + TPMLIB_VolatileAll_Store.3 \ + TPM_Malloc.3 + +man3_MANS += $(man3_MANS_generated) + +%.3 : %.pod + @pod2man -r "libtpms" \ + -c "" \ + -n $(basename $@) \ + --section=3 $< > $@ + +EXTRA_DIST = $(man3_MANS) $(man3_PODS) + +CLEANFILES = $(man3_MANS_generated) diff --git a/man/man3/TPMLIB_CancelCommand.pod b/man/man3/TPMLIB_CancelCommand.pod new file mode 100644 index 0000000..b41efc2 --- /dev/null +++ b/man/man3/TPMLIB_CancelCommand.pod @@ -0,0 +1,29 @@ +=head1 NAME + +TPMLIB_CancelCommand - Cancel a TPM command + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +=head1 DESCRIPTION + +The B function indicates that the ongoing processing +of a TPM command is to be cancelled. The cancellation will only +be effective for certain time consuming operations, such as the creation +of keys. + +Note that an implementation that wants to support cancellation of commands +needs to process TPM commands in one thread and cancel them in another. + +=head1 SEE ALSO + +B(3) + +=cut diff --git a/man/man3/TPMLIB_ChooseTPMVersion.pod b/man/man3/TPMLIB_ChooseTPMVersion.pod new file mode 100644 index 0000000..65d0a6d --- /dev/null +++ b/man/man3/TPMLIB_ChooseTPMVersion.pod @@ -0,0 +1,52 @@ +=head1 NAME + +TPMLIB_ChooseTPMVersion - Choose the version of the TPM + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B IB<);> + + typedef enum TPMLIB_TPMVersion { + TPMLIB_TPM_VERSION_1_2, + TPMLIB_TPM_VERSION_2, + } TPMLIB_TPMVersion; + +=head1 DESCRIPTION + +The B function is used to choose the version +of the TPM, either a TPM 1.2 or TPM 2. + +This function must be called before B is called and +will otherwise return an error. This function may be called again once +B has been called. + +If this function is not called, the last chosen TPM version will be +started with B. If this function is not called, +a TPM 1.2 will be used. + +=head1 ERRORS + +=over 4 + +=item B + +The version of the TPM was chosen successfully. + +=item B + +The choice of the TPM was wrong, or TPMLIB_MainInit() has already been called. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 SEE ALSO + +B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_DecodeBlob.pod b/man/man3/TPMLIB_DecodeBlob.pod new file mode 100644 index 0000000..e600445 --- /dev/null +++ b/man/man3/TPMLIB_DecodeBlob.pod @@ -0,0 +1,66 @@ +=head1 NAME + +TPMLIB_DecodeBlob - Decode a base64-encode TPM blob + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B *IB<, + enum TPMLIB_BlobType> IB<, + unsigned char> **IB< + size_t> *IB<);> + +=head1 DESCRIPTION + +The B function is used to decode a base64-encoded +TPM state blob. The caller must pass what type of blob is expected to be +decoded and following that the function will look for the start and +end markers of the data. + +The following types of blobs are supported along with their start and +end markers: + +=over 4 + +=item B + +'-----BEGIN INITSTATE-----' marks the beginning of the base64-encoded blob. + +'-----END INITSTATE-----' marks the end of the base64-encoded blob. + +=back + +This function is useful when passing state to the TPM inside the +callback that is invoked to get the TPM's state blob. +See I(3). + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +The size of a requested buffer exceeds the limit or the +system is out of memory. + +=item B + +An error occurred while attempting to decode the blob. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 SEE ALSO + +B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_GetInfo.pod b/man/man3/TPMLIB_GetInfo.pod new file mode 100644 index 0000000..650b62b --- /dev/null +++ b/man/man3/TPMLIB_GetInfo.pod @@ -0,0 +1,52 @@ +=head1 NAME + +TPMLIB_GetInfo - Get Information about the TPM implementation + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +=head1 DESCRIPTION + +The B function allows to query for TPM implementation +specifics and get a JSON string in return. Which data is to be returned +can be specified in the flags parameter that may be a logical 'or' concatenation +of flags. If passed flags are not supported, nothing is returned . If a 0 is +passed in, an empty JSON Object '{}' is returned. + +The following flags are defined and return JSON objects as shown: + +=over 4 + +=item B + +{"TPMSpecification":{"family":"1.2","level":2,"revision":116}} + +=item B + +{"TPMAttributes":{"manufacturer":"id:00001014","version":"id:00740001","model":"swtpm"}} + +=item B (since v0.8.0) + +{"TPMFeatures":{"RSAKeySizes":[1024,2048,3072]}} + +This JSON object may be extended in the future. + +=back + +=head1 RETURN VALUE + +This function returns a JSON string on success and a NULL pointer if a memory +allocation failure occurred. + +The caller must free() the returned string. + +=head1 SEE ALSO + +=cut diff --git a/man/man3/TPMLIB_GetState.3 b/man/man3/TPMLIB_GetState.3 new file mode 100644 index 0000000..f9db45c --- /dev/null +++ b/man/man3/TPMLIB_GetState.3 @@ -0,0 +1 @@ +.so man3/TPMLIB_SetState.3 diff --git a/man/man3/TPMLIB_GetTPMProperty.pod b/man/man3/TPMLIB_GetTPMProperty.pod new file mode 100644 index 0000000..ab3c918 --- /dev/null +++ b/man/man3/TPMLIB_GetTPMProperty.pod @@ -0,0 +1,153 @@ +=head1 NAME + +TPMLIB_GetTPMProperty - Get a runtime property of the TPM + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +=head1 DESCRIPTION + +The B call is used to retrieve run-time parameters +of the TPM such as the number of authorization sessions it can hold or +the maximum sizes of the permanent state, savestate or volatile state blobs. + +This function can be called before or after the TPM has been created. +The current implementation of libtpms will return the same value before +and after the TPM was started. + +With the introduction of the function B, +the call to this function should be executed after the TPM version +has been chosen. The reason is that different TPM versions may return +different values. + +The following properties have been defined: + +=over 4 + +=item B + +The maximum size of an RSA key. + +=item B + +The maximum sizes of the TPM command and result buffers. + +=item B + +The number of key slots. + +=item B + +The number of owner-evict keys. + +=item B + +The number of authorization sessions. + +=item B + +The number of transport sessions. + +=item B + +The number of DAA sessions. + +=item B + +The size of the session list. + +=item B + +The number of monotonic counters. + +=item B + +The number of family entries. + +=item B + +The number of delegate entries. + +=item B + +The space safety margin used for the worst-case sizes of the savestate and +volatile state blobs. This safety margin is not used for the size of the +permanent data blob. + +=item B + +The maximum size of the permanent data blob. + +=item B + +The maximum size of the savestate blob (includes the space safety margin). + +=item B + +The maximum size of the volatile state blob (includes the space saferty +margin). + +=back + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +An undefined property was queried. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 EXAMPLE + + #include + + #include + #include + + int main(void) { + TPM_RESULT res; + int result; + int rc = 0; + + if (TPMLIB_MainInit() != TPM_SUCCESS) { + fprintf(stderr, "Could not start the TPM.\n"); + return 1; + } + + if (TPMLIB_GetTPMProperty(TPMPROP_TPM_RSA_KEY_LENGTH_MAX, &result) + != TPM_SUCCESS) { + fprintf(stderr, "Could not read the max. size of RSA keys.\n"); + goto err_exit; + } + + fprintf(stdout, "Max. size of RSA keys: %d\n", result); + + err_exit: + TPMLIB_Terminate(); + + return 0; + } + +=head1 SEE ALSO + +B(3), B(3), +B(3), B(3), B(3), +B(3) + +=cut diff --git a/man/man3/TPMLIB_GetVersion.pod b/man/man3/TPMLIB_GetVersion.pod new file mode 100644 index 0000000..3a5a476 --- /dev/null +++ b/man/man3/TPMLIB_GetVersion.pod @@ -0,0 +1,30 @@ +=head1 NAME + +TPMLIB_GetVersion - Get the version of the TPM library + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +=head1 DESCRIPTION + +The B function returns the libtpms library version. +The TPM library version is formatted as follows: + + Bits 0 - 7 : revision of the library + Bits 8 -15 : minor version number of the library + Bits 16-23 : major version number of the library + +V0.5.1 is therefore represented as 0x00000501. + +=head1 SEE ALSO + +B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_MainInit.pod b/man/man3/TPMLIB_MainInit.pod new file mode 100644 index 0000000..663b2a1 --- /dev/null +++ b/man/man3/TPMLIB_MainInit.pod @@ -0,0 +1,96 @@ +=head1 NAME + +TPMLIB_MainInit - Initialize the TPM + +TPMLIB_Terminate - Terminate the TPM + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B<#include > + +B + +B + +=head1 DESCRIPTION + +The B and B functions are used +to initialize and terminate the TPM respectively. The B +function must be called before the TPM processes any TPM command. +The B function is called to free all the internal +resources (memory allocations) the TPM has used and must be called after +the last TPM command was processed by the TPM. The B +function can then be called again. + +Use B to set callback functions for +initialization and writing and restoring the internal state in a +portable format. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +General failure. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 EXAMPLE + + #include + + #include + #include + #include + + int main(void) { + TPM_RESULT res; + unsigned char *respbuffer = NULL; + uint32_t resp_size = 0; + uint32_t respbufsize = 0; + unsigned char *command; + uint32_t command_size; + + [...] + + 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(3), B(3), B(3) +B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_Process.pod b/man/man3/TPMLIB_Process.pod new file mode 100644 index 0000000..2954105 --- /dev/null +++ b/man/man3/TPMLIB_Process.pod @@ -0,0 +1,108 @@ +=head1 NAME + +TPMLIB_Process - process a TPM command + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B **IB<, + uint32_t> *IB<, + uint32_t> *IB<, + unsigned char> *IB<, + uint32_t> IB<);> + +=head1 DESCRIPTION + +The B function is used to send TPM commands to the TPM +and receive the results. + +The I parameter provides the buffer for the TPM command and +the I the number of valid TPM command bytes within that buffer. + +The I is a pointer to a buffer where the TPM will return its +result. If no buffer is given (I is NULL), the TPM will +allocate a buffer. The parameter I returns the number of valid +TPM response bytes in the buffer. The number of valid bytes in the response +is guaranteed to not exceed the maximum I/O buffer size. Use the +I API and parameter I for +getting the maximum size. +The user must indicate the size of a provided buffer with the I +parameter. If the buffer is not big enough for the response, the TPM will +free the provided buffer and allocate one of sufficient size and adapt +I. The returned buffer is only subject to size restrictions +as explained for I. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +General failure. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 EXAMPLE + + #include + + #include + #include + #include + + static unsigned char TPM_Startup_ST_CLEAR[] = { + 0x00, 0xC1, 0x00, 0x00, 0x00, 0x0C, 0x00, 0x00, 0x00, 0x99, + 0x00, TPM_ST_CLEAR + }; + + int main(void) { + TPM_RESULT res; + unsigned char *respbuffer = NULL; + uint32_t resp_size = 0; + uint32_t respbufsize = 0; + unsigned char *command; + uint32_t command_size; + + [...] + + if (TPMLIB_MainInit() != TPM_SUCCESS) { + fprintf(stderr, "Could not start the TPM.\n"); + return 1; + } + + [...] + /* build TPM command */ + command = TPM_Startup_ST_CLEAR; + command_size = sizeof(TPM_Startup_ST_CLEAR); + [...] + + res = TPMLIB_Process(&respbuffer, &resp_size, + &respbufsize, + command, command_size); + [...] + + TPMLIB_Terminate(); + + return 0; + } + +=head1 SEE ALSO + +B(3), B(3), B(3) +B(3), B(3), B(3) + +=cut 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 > + +B<#include > + +B<#include > + +B + +=head1 DESCRIPTION + +The B 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 or I group is +set, then all of the callbacks in the respective group should +be implemented. + +=over 4 + +=item B + +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, a failure code +otherwise. + +The default implementation requires that the environment variable +I 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 +and the initialization of the TPM in B will fail. + +=item B + +This function is called when the TPM wants to load state from persistent +storage. The implementing function must allocate a buffer (I) +and return it to the TPM along with the length of the buffer (I). +The I is always 0 and can be ignored. +The I parameter is either one of B, +B, or B and indicates +which one of the 3 types of state is supposed to be loaded. + +Upon success this function should return B, a failure code +otherwise. + +The default implementation writes the TPM's state into files in a directory +where the I environment variable pointed to when +B 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 + +This function is called when the TPM wants to store state to persistent +storage. The I and I parameters provide the data to be +stored and the number of bytes. The implementing function must not +free the I buffer. +The I is always 0 and can be ignored. +The I parameter is either one of B, +B, or B and indicates +which one of the 3 types of state is supposed to be stored. + +Upon success this function should return B, a failure code +otherwise. + +The default implementation reads the TPM's state from files in a directory +where the I environment variable pointed to when +B 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 interface function is not set. + +=item B + +This function is called when the TPM wants to delete state on persistent +storage. +The I is always 0 and can be ignored. +The I parameter is either one of B, +B, or B and indicates +which one of the 3 types of state is supposed to be deleted. +The I parameter indicates whether the given data must exist +and the implementing function should return B if the data did +not exist. + +Upon success this function should return B, a failure code +otherwise. + +The default implementation deletes the TPM's state files in a directory +where the I environment variable pointed to when +B was executed. Failure to delete the TPM's state +files may put the TPM into failure mode. + +=item B + +This function is called to initialize the IO subsystem of the TPM. + +Upon success this function should return B, a failure code +otherwise. + +The default implementation simply returns B. + +=item B + +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 pointer. + +Upon success this function should return B, a failure code +otherwise. + +The default implementation returns 0 as the locality. + +=item B + +This function is called when the TPM needs to determine whether physical +presence has been asserted. The implementing function should write either +B or B into the physicalPresence pointer. + +Upon success this function should return B, a failure code +otherwise. + +The default implementation returns B for physical presence. + +=back + +=head1 RETURN VALUE + +Upon successful completion, B returns B, +an error value otherwise. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +General failure. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 EXAMPLE + + #include + #include + #include + + 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(3), B(3), B(3), +B(3) + +=cut diff --git a/man/man3/TPMLIB_SetBufferSize.pod b/man/man3/TPMLIB_SetBufferSize.pod new file mode 100644 index 0000000..6ba7afe --- /dev/null +++ b/man/man3/TPMLIB_SetBufferSize.pod @@ -0,0 +1,37 @@ +=head1 NAME + +TPMLIB_SetBufferSize - Set the TPM's I/O buffer size + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +=head1 DESCRIPTION + +The B function sets the size of the buffer +the TPM can use for input and output and that it advertises to users. +It also allows to get the minimum and maximum supported buffer +size. + +If 0 is given on input, the currently used buffer size is returned. +Any other number will try to change the buffer size. The returned +size may be smaller than the requested one, if the requested one was +above a maximum. The returned size may be larger than the requested +one, if the requested one was below a minimum. + +This function must be called after B has +been called. It should not be called after B has +been called but can again be called once B has +been called. + +=head1 SEE ALSO + +B(3), B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_SetDebugFD.pod b/man/man3/TPMLIB_SetDebugFD.pod new file mode 100644 index 0000000..25eda9c --- /dev/null +++ b/man/man3/TPMLIB_SetDebugFD.pod @@ -0,0 +1,38 @@ +=head1 NAME + +TPMLIB_SetDebugFD - Set the file descriptor to send the debug output to + +TPMLIB_SetDebugLevel - Set the debugging level + +TPMLIB_SetDebugPrefix - Set the prefix for each debugging line + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +B + +B + +=head1 DESCRIPTION + +B allows to set the file descriptor +to send the debug output to. + +B allows to set the debug level. +Only debug levels greater than 1 will produce output. The indentation +level of a line will determine whether it is printed. Lines with +0 indentation will be printed at debug level 1, 1 space of indentation +at debug level 2 and so on. + +B allows to set a prefix that is +to be printed in front of every line of debugging output. The +prefix can be used for further indentation. + +=cut diff --git a/man/man3/TPMLIB_SetDebugLevel.3 b/man/man3/TPMLIB_SetDebugLevel.3 new file mode 100644 index 0000000..9989e05 --- /dev/null +++ b/man/man3/TPMLIB_SetDebugLevel.3 @@ -0,0 +1 @@ +.so man3/TPMLIB_SetDebugFD.3 \ No newline at end of file diff --git a/man/man3/TPMLIB_SetDebugPrefix.3 b/man/man3/TPMLIB_SetDebugPrefix.3 new file mode 100644 index 0000000..9989e05 --- /dev/null +++ b/man/man3/TPMLIB_SetDebugPrefix.3 @@ -0,0 +1 @@ +.so man3/TPMLIB_SetDebugFD.3 \ No newline at end of file diff --git a/man/man3/TPMLIB_SetState.pod b/man/man3/TPMLIB_SetState.pod new file mode 100644 index 0000000..dea7e17 --- /dev/null +++ b/man/man3/TPMLIB_SetState.pod @@ -0,0 +1,54 @@ +=head1 NAME + +TPMLIB_SetState - Set the TPM's volatile, permanent, or save state + +TPMLIB_GetState - Get the TPM's volatile, permanent, or save state + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +B + +=head1 DESCRIPTION + +The B function allows to set either one of the state blobs of +the TPM. The passed state blob is tested for whether it can be accepted and a TPM +error code is returned in case it cannot be accepted. In case of acceptance, the +state blob will be passed to the TPM upon B. Setting a state blob +hides a file that may contain the same type of blob and would be read otherwise. +It is required to call this function with a NULL pointer for the buffer parameter +to hide a state blob in a file. + +It is only possible to set the state blobs after B +has been called. All state blobs are cleared when a different version of TPM is +chosen using B or when a call to B +fails because a state blob could not be accepted. + +The order in which state blobs are set is important. The first state blob has +to be the one representing the TPM's permanent state. Only after that either +the volatile or save state blobs can be set. + +The B function allows to get the current state of the TPM. +For as long as the TPM has not been started, this function either returns the state +blob previously set with B or the state is read from a file. +Once the TPM has been start the state of the running TPM is returned. + +The B (save state) type of TPM state can be set with this +function. The same state blob will be returned until TPM_Startup(ST_STATE) has been +called, after which an empty blob will be returned. This blob can also only be +read after TPM_SaveState() has been sent to the TPM. + +=head1 SEE ALSO + +B(3), B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_Terminate.3 b/man/man3/TPMLIB_Terminate.3 new file mode 100644 index 0000000..83a9c84 --- /dev/null +++ b/man/man3/TPMLIB_Terminate.3 @@ -0,0 +1 @@ +.so man3/TPMLIB_MainInit.3 \ No newline at end of file diff --git a/man/man3/TPMLIB_ValidateState.pod b/man/man3/TPMLIB_ValidateState.pod new file mode 100644 index 0000000..e258035 --- /dev/null +++ b/man/man3/TPMLIB_ValidateState.pod @@ -0,0 +1,44 @@ +=head1 NAME + +TPMLIB_ValidateState - Validate the state blobs of the TPM + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B + +=head1 DESCRIPTION + +The B function allows to validate the +state blobs that the TPM would read upon B or +once the TPM_Startup command has been sent to it. + +This function is useful for TPM state migration between possibly +different version of libtpms. Here the target libtpms needs to be +able to determine whether it can support the version of blobs that were +migrated and if this is not the case, the caller can refuse the +migration. + +The B parameter can be a logical 'or' of one or +multiple of of the following: B, +B, or B. +The B parameter is currently not used and should be set to 0. + +The first state blob that should be loaded is the permanent state, +since for example the volatile state requires it to be available +for validation. + +This function should be called before B is invoked. + +=head1 SEE ALSO + +B(3), B(3) + +=cut diff --git a/man/man3/TPMLIB_VolatileAll_Store.pod b/man/man3/TPMLIB_VolatileAll_Store.pod new file mode 100644 index 0000000..8906e18 --- /dev/null +++ b/man/man3/TPMLIB_VolatileAll_Store.pod @@ -0,0 +1,45 @@ +=head1 NAME + +TPMLIB_VolatileAll_Store - store all volatile state of the TPM in a buffer + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B + +=head1 DESCRIPTION + +The B function is used to get the volatile +state of the TPM. The function will allocate a I and return +the number of bytes of state information in the I variable. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +General failure. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 SEE ALSO + +B(3), B(3), B(3) + +=cut diff --git a/man/man3/TPM_Free.3 b/man/man3/TPM_Free.3 new file mode 100644 index 0000000..d8bddfd --- /dev/null +++ b/man/man3/TPM_Free.3 @@ -0,0 +1 @@ +.so man3/TPM_Malloc.3 diff --git a/man/man3/TPM_IO_Hash_Data.3 b/man/man3/TPM_IO_Hash_Data.3 new file mode 100644 index 0000000..f0f4e94 --- /dev/null +++ b/man/man3/TPM_IO_Hash_Data.3 @@ -0,0 +1 @@ +.so man3/TPM_IO_Hash_Start.3 \ No newline at end of file diff --git a/man/man3/TPM_IO_Hash_End.3 b/man/man3/TPM_IO_Hash_End.3 new file mode 100644 index 0000000..f0f4e94 --- /dev/null +++ b/man/man3/TPM_IO_Hash_End.3 @@ -0,0 +1 @@ +.so man3/TPM_IO_Hash_Start.3 \ No newline at end of file diff --git a/man/man3/TPM_IO_Hash_Start.pod b/man/man3/TPM_IO_Hash_Start.pod new file mode 100644 index 0000000..d75027e --- /dev/null +++ b/man/man3/TPM_IO_Hash_Start.pod @@ -0,0 +1,78 @@ +=head1 NAME + +TPM_IO_Hash_Start - indicate the beginging of a TPM TIS hash operation + +TPM_IO_Hash_Data - hash the provided data + +TPM_IO_Hash_End - indicate the end of a TPM TIS hash operation + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B<#include > + +B + +B *IB<, + uint32_t> IB<);> + +B + +=head1 DESCRIPTION + +The B function can be used by an implementation of the +TPM TIS hardware interface to indicate the beginning of a hash operation. +Following the TPM TIS interface specification it resets several PCRs and +terminates existing transport sessions. +The B function is used to send the data to be hashed to +the TPM. +The B function calculates the final hash and stores it +in the locality 4 PCR. +The 3 functions must be called in the order they were explained. + +The implementation of the above functions handles all TPM-internal actions +such as the setting and clearing of permanent flags and PCRs and the +calculation of the hash. Any functionality related to the TPM's TIS interface +and the handling of flags, locality and state has to be implemented by the +caller. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +General failure. + +=item B + +The B function was called before the TPM received +a TPM_Startup command. + +=item B + +The B or B functions were called before +the B function. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 SEE ALSO + +B(3), B(3), B(3), +B(3) + +=cut diff --git a/man/man3/TPM_IO_TpmEstablished_Get.pod b/man/man3/TPM_IO_TpmEstablished_Get.pod new file mode 100644 index 0000000..2fcab8c --- /dev/null +++ b/man/man3/TPM_IO_TpmEstablished_Get.pod @@ -0,0 +1,58 @@ +=head1 NAME + +TPM_IO_TpmEstablished_Get - get the value of the TPMEstablished flag + +TPM_IO_TpmEstablished_Reset - reset the TPMEstablished flag + +=head1 LIBRARY + +TPM library (libtpms, -ltpms) + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B<#include > + +B *IB<);> + +B + +=head1 DESCRIPTION + +The B function returns the value of the +TPMEstablished flag of the TPM's permanent data. + +The B function resets the TPMEstablished +flag. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +General failure. + +=item B + +The locality used for resetting the flags is wrong. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 SEE ALSO + +B(3), B(3), B(3), +B(3), B(3), B(3), +B(3) + +=cut diff --git a/man/man3/TPM_IO_TpmEstablished_Reset.3 b/man/man3/TPM_IO_TpmEstablished_Reset.3 new file mode 100644 index 0000000..e731ebc --- /dev/null +++ b/man/man3/TPM_IO_TpmEstablished_Reset.3 @@ -0,0 +1 @@ +.so man3/TPM_IO_TpmEstablished_Get.3 diff --git a/man/man3/TPM_Malloc.pod b/man/man3/TPM_Malloc.pod new file mode 100644 index 0000000..60446cc --- /dev/null +++ b/man/man3/TPM_Malloc.pod @@ -0,0 +1,72 @@ +=head1 NAME + +TPM_Malloc - Allocate memory + +TPM_Realloc - Reallocate memory + +TPM_Free - Free memory + +=head1 SYNOPSIS + +B<#include > + +B<#include > + +B<#include > + +B **IB<, + uint32_t> IB<);> + +B **IB<, + uint32_t> IB<);> + +B *IB<);> + +=head1 DESCRIPTION + +The B function is used to allocate a buffer of the given size. +The allocated buffer will be returned in the I parameter. + +The B function is used to resize a buffer. The new size of +the buffer is given in the I parameter. The reallocated buffer will +contain the data from the original buffer. + +Both functions have the restriction that the buffer they can allocate +is limited to B (64k) bytes. This size is sufficient +for all buffers needed by the TPM. + +Upon successful completion, the functions return B. In case the +requested buffer exceeds the limit, B will be returned. See further +possible error codes below. + +The B function frees the memory previously allocated using +either B or B. + +=head1 ERRORS + +=over 4 + +=item B + +The function completed successfully. + +=item B + +The size of the requested buffer exceeds the limit or the +system is out of memory. + +=item B + +Requested buffer is of size 0. + +=back + +For a complete list of TPM error codes please consult the include file +B + +=head1 SEE ALSO + +B(3), B(3) +B(3), B(3), B(3) + +=cut diff --git a/man/man3/TPM_Realloc.3 b/man/man3/TPM_Realloc.3 new file mode 100644 index 0000000..bc24f9e --- /dev/null +++ b/man/man3/TPM_Realloc.3 @@ -0,0 +1 @@ +.so man3/TPM_Malloc.3 \ No newline at end of file -- cgit v1.2.3