diff options
Diffstat (limited to 'man/man3')
27 files changed, 1375 insertions, 0 deletions
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 <libtpms/tpm_library.h>> + +B<uint32_t TPMLIB_CancelCommand(void);> + +=head1 DESCRIPTION + +The B<TPMLIB_CancelCommand()> 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<TPMLIB_Process>(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 <libtpms/tpm_types.h>> + +B<#include <libtpms/tpm_library.h>> + +B<TPM_RESULT TPMLIB_ChooseTPMVersion(TPMLIB_TPMVersion> I<ver>B<);> + + typedef enum TPMLIB_TPMVersion { + TPMLIB_TPM_VERSION_1_2, + TPMLIB_TPM_VERSION_2, + } TPMLIB_TPMVersion; + +=head1 DESCRIPTION + +The B<TPMLIB_ChooseTPMVersion()> 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<TPMLIB_MainInit()> is called and +will otherwise return an error. This function may be called again once +B<TPMLIB_Terminate()> has been called. + +If this function is not called, the last chosen TPM version will be +started with B<TPMLIB_MainInit()>. If this function is not called, +a TPM 1.2 will be used. + +=head1 ERRORS + +=over 4 + +=item B<TPM_SUCCESS> + +The version of the TPM was chosen successfully. + +=item B<TPM_FAIL> + +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<libtpms/tpm_error.h> + +=head1 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(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 <libtpms/tpm_types.h>> + +B<#include <libtpms/tpm_library.h>> + +B<TPM_RESULT TPMLIB_DecodeBlob(const char> *I<buffer>B<, + enum TPMLIB_BlobType> I<type>B<, + unsigned char> **I<result>B< + size_t> *I<result_len>B<);> + +=head1 DESCRIPTION + +The B<TPMLIB_DecodeBlob()> 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<BLOB_TYPE_INITSTATE> + +'-----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<TPMLIB_RegisterCallbacks>(3). + +=head1 ERRORS + +=over 4 + +=item B<TPM_SUCCESS> + +The function completed successfully. + +=item B<TPM_SIZE> + +The size of a requested buffer exceeds the limit or the +system is out of memory. + +=item B<TPM_FAIL> + +An error occurred while attempting to decode the blob. + +=back + +For a complete list of TPM error codes please consult the include file +B<libtpms/tpm_error.h> + +=head1 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_RegisterCallbacks>(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 <libtpms/tpm_library.h>> + +B<char *TPMLIB_GetInfo(TPMLIB_InfoFlags flags);> + +=head1 DESCRIPTION + +The B<TPMLIB_GetInfo()> 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<TPMLIB_INFO_TPMSPECIFICATION> + +{"TPMSpecification":{"family":"1.2","level":2,"revision":116}} + +=item B<TPMLIB_INFO_TPMATTRIBUTES> + +{"TPMAttributes":{"manufacturer":"id:00001014","version":"id:00740001","model":"swtpm"}} + +=item B<TPMLIB_INFO_TPMFEATURES> (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 <libtpms/tpm_library.h>> + +B<TPM_RESULT TPMLIB_GetTPMProperty(enum TPMLIB_TPMProperty, int *result);> + +=head1 DESCRIPTION + +The B<TPMLIB_GetTPMProperty()> 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<TPMLIB_ChooseTPMVersion()>, +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<TPMPROP_TPM_RSA_KEY_LENGTH_MAX> + +The maximum size of an RSA key. + +=item B<TPMPROP_TPM_BUFFER_MAX> + +The maximum sizes of the TPM command and result buffers. + +=item B<TPMPROP_TPM_KEY_HANDLES> + +The number of key slots. + +=item B<TPMPROP_TPM_OWNER_EVICT_KEY_HANDLES> + +The number of owner-evict keys. + +=item B<TPMPROP_TPM_MIN_AUTH_SESSIONS> + +The number of authorization sessions. + +=item B<TPMPROP_TPM_MIN_TRANS_SESSIONS> + +The number of transport sessions. + +=item B<TPMPROP_TPM_MIN_DAA_SESSIONS> + +The number of DAA sessions. + +=item B<TPMPROP_TPM_MIN_SESSION_LIST> + +The size of the session list. + +=item B<TPMPROP_TPM_MIN_COUNTERS> + +The number of monotonic counters. + +=item B<TPMPROP_TPM_NUM_FAMILY_TABLE_ENTRY_MIN> + +The number of family entries. + +=item B<TPMPROP_TPM_NUM_DELEGATE_TABLE_ENTRY_MIN> + +The number of delegate entries. + +=item B<TPMPROP_TPM_SPACE_SAFETY_MARGIN> + +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<TPMPROP_TPM_MAX_NV_SPACE> + +The maximum size of the permanent data blob. + +=item B<TPMPROP_TPM_MAX_SAVESTATE_SPACE> + +The maximum size of the savestate blob (includes the space safety margin). + +=item B<TPMPROP_TPM_MAX_VOLATILESTATE_SPACE> + +The maximum size of the volatile state blob (includes the space saferty +margin). + +=back + +=head1 ERRORS + +=over 4 + +=item B<TPM_SUCCESS> + +The function completed successfully. + +=item B<TPM_FAIL> + +An undefined property was queried. + +=back + +For a complete list of TPM error codes please consult the include file +B<libtpms/tpm_error.h> + +=head1 EXAMPLE + + #include <stdio.h> + + #include <libtpms/tpm_library.h> + #include <libtpms/tpm_error.h> + + 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<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3), +B<TPMLIB_Process>(3), B<TPMLIB_RegisterCallbacks>(3), B<TPMLIB_GetVersion>(3), +B<TPMLIB_ChooseTPMVersion>(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 <libtpms/tpm_library.h>> + +B<uint32_t TPMLIB_GetVersion(void);> + +=head1 DESCRIPTION + +The B<TPMLIB_GetVersion()> 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<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(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 <libtpms/tpm_types.h>> + +B<#include <libtpms/tpm_library.h>> + +B<#include <libtpms/tpm_error.h>> + +B<TPM_RESULT TPMLIB_MainInit(void);> + +B<TPM_RESULT TPMLIB_Terminate(void);> + +=head1 DESCRIPTION + +The B<TPMLIB_MainInit()> and B<TPMLIB_Terminate()> functions are used +to initialize and terminate the TPM respectively. The B<TPMLIB_MainInit()> +function must be called before the TPM processes any TPM command. +The B<TPMLIB_Terminate()> 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<TPMLIB_MainInit()> +function can then be called again. + +Use B<TPMLIB_RegisterCallbacks()> to set callback functions for +initialization and writing and restoring the internal state in a +portable format. + +=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 <stdio.h> + + #include <libtpms/tpm_types.h> + #include <libtpms/tpm_library.h> + #include <libtpms/tpm_error.h> + + 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<TPMLIB_Process>(3), B<TPMLIB_RegisterCallbacks>(3), B<TPMLIB_GetVersion>(3) +B<TPMLIB_GetTPMProperty>(3), B<TPMLIB_DecodeBlob>(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 <libtpms/tpm_library.h>> + +B<#include <libtpms/tpm_error.h>> + +B<TPM_RESULT TPMLIB_Process(unsigned char> **I<respbuffer>B<, + uint32_t> *I<resp_size>B<, + uint32_t> *I<respbufsize>B<, + unsigned char> *I<command>B<, + uint32_t> I<command_size>B<);> + +=head1 DESCRIPTION + +The B<TPMLIB_Process()> function is used to send TPM commands to the TPM +and receive the results. + +The I<command> parameter provides the buffer for the TPM command and +the I<command_size> the number of valid TPM command bytes within that buffer. + +The I<respbuffer> is a pointer to a buffer where the TPM will return its +result. If no buffer is given (I<respbuffer> is NULL), the TPM will +allocate a buffer. The parameter I<resp_size> 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<TPMLIB_GetTPMProperty()> API and parameter I<TPMPROP_TPM_BUFFER_MAX> for +getting the maximum size. +The user must indicate the size of a provided buffer with the I<respbufsize> +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<respbufsize>. The returned buffer is only subject to size restrictions +as explained for I<TPM_Malloc()>. + +=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 <stdio.h> + + #include <libtpms/tpm_types.h> + #include <libtpms/tpm_library.h> + #include <libtpms/tpm_error.h> + + 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<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3), B<TPMLIB_RegisterCallbacks>(3) +B<TPMLIB_GetTPMProperty>(3), B<TPMLIB_Malloc>(3), B<TPMLIB_Realloc>(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 <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 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 <libtpms/tpm_library.h>> + +B<uint32_t TPMLIB_SetBufferSize(uint32_t, uint32_t *, uint32_t *);> + +=head1 DESCRIPTION + +The B<TPMLIB_SetBufferSize()> 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<TPMLIB_ChooseTPMVersion()> has +been called. It should not be called after B<TPMLIB_MainInit()> has +been called but can again be called once B<TPMLIB_Terminate()> has +been called. + +=head1 SEE ALSO + +B<TPMLIB_ChooseTPMVersion>(3), B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(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 <libtpms/tpm_library.h>> + +B<uint32_t TPMLIB_SetDebugFD(int fd);> + +B<uint32_t TPMLIB_SetDebugLevel(unsigned int level);> + +B<uint32_t TPMLIB_SetDebugPrefix(const char *prefix);> + +=head1 DESCRIPTION + +B<TPMLIB_SetDebugFD()> allows to set the file descriptor +to send the debug output to. + +B<TPMLIB_SetDebugLevel()> 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<TPMLIB_SetDebugPrefix()> 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 <libtpms/tpm_library.h>> + +B<TPM_RESULT TPMLIB_SetState(enum TPMLIB_StateType st, + const unsigned char *buffer, uint32_t buflen);> + +B<TPM_RESULT TPMLIB_GetState(enum TPMLIB_StateType st, + unsigned char **buffer, uint32_t *buflen);> + +=head1 DESCRIPTION + +The B<TPMLIB_SetState()> 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<TPM_MainInit()>. 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<TPMLIB_ChooseTPMVersion()> +has been called. All state blobs are cleared when a different version of TPM is +chosen using B<TPMLIB_ChooseTPMVersion> or when a call to B<TPMLIB_SetState()> +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<TPMLIB_GetState()> 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<TPMLIB_SetState()> or the state is read from a file. +Once the TPM has been start the state of the running TPM is returned. + +The B<TPMLIB_STATE_SAVE_STATE> (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<TPMLIB_ChooseTPMVersion>(3), B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(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 <libtpms/tpm_library.h>> + +B<uint32_t TPMLIB_ValidateState(TPMLIB_StateType st, + unsigned int flags); +> + +=head1 DESCRIPTION + +The B<TPMLIB_ValidateState()> function allows to validate the +state blobs that the TPM would read upon B<TPMLIB_MainInit()> 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<tpmlib_state> parameter can be a logical 'or' of one or +multiple of of the following: B<TPMLIB_STATE_PERMANENT>, +B<TPMLIB_STATE_VOLATILE>, or B<TPMLIB_STATE_SAVE_STATE>. +The B<flags> 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<TPMLIB_MainInit()> is invoked. + +=head1 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(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 <libtpms/tpm_library.h>> + +B<#include <libtpms/tpm_error.h>> + +B<TPM_RESULT TPMLIB_VolatileAll_Store(unsigned char **buffer, + uint32_t *buflen);> + +=head1 DESCRIPTION + +The B<TPMLIB_VolatileAll_Store()> function is used to get the volatile +state of the TPM. The function will allocate a I<buffer> and return +the number of bytes of state information in the I<buflen> variable. + +=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 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3), B<TPMLIB_RegisterCallbacks>(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 <libtpms/tpm_types.h>> + +B<#include <libtpms/tpm_tis.h>> + +B<#include <libtpms/tpm_error.h>> + +B<TPM_RESULT TPM_IO_Hash_Start(void);> + +B<TPM_RESULT TPM_IO_Hash_Data(const unsigned char> *I<data>B<, + uint32_t> I<data_length>B<);> + +B<TPM_RESULT TPM_IO_Hash_End(void);> + +=head1 DESCRIPTION + +The B<TPM_IO_Hash_Start()> 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<TPM_IO_Hash_Data()> function is used to send the data to be hashed to +the TPM. +The B<TPM_IO_Hash_End()> 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<TPM_SUCCESS> + +The function completed successfully. + +=item B<TPM_FAIL> + +General failure. + +=item B<TPM_INVALID_POSTINIT> + +The B<TPM_IO_Hash_Start()> function was called before the TPM received +a TPM_Startup command. + +=item B<TPM_SHA_THREAD> + +The B<TPM_IO_Hash_Data()> or B<TPM_IO_Hash_End()> functions were called before +the B<TPM_IO_Hash_Start()> function. + +=back + +For a complete list of TPM error codes please consult the include file +B<libtpms/tpm_error.h> + +=head1 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3), B<TPMLIB_RegisterCallbacks>(3), +B<TPMLIB_Process>(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 <libtpms/tpm_types.h>> + +B<#include <libtpms/tpm_tis.h>> + +B<#include <libtpms/tpm_error.h>> + +B<TPM_RESULT TPM_IO_TpmEstablished_Get(TPM_BOOL> *I<tpmEstablished>B<);> + +B<TPM_RESULT TPM_IO_TpmEstablished_Reset(void);> + +=head1 DESCRIPTION + +The B<TPM_IO_TpmEstablished_Get()> function returns the value of the +TPMEstablished flag of the TPM's permanent data. + +The B<TPM_IO_TpmEstablished_Reset()> function resets the TPMEstablished +flag. + +=head1 ERRORS + +=over 4 + +=item B<TPM_SUCCESS> + +The function completed successfully. + +=item B<TPM_FAIL> + +General failure. + +=item B<TPM_BAD_LOCALITY> + +The locality used for resetting the flags is wrong. + +=back + +For a complete list of TPM error codes please consult the include file +B<libtpms/tpm_error.h> + +=head1 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3), B<TPMLIB_RegisterCallbacks>(3), +B<TPMLIB_Process>(3), B<TPM_IO_Hash_Start>(3), B<TPM_IO_Hash_End>(3), +B<TPM_IO_Hash_Data>(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 <libtpms/tpm_types.h>> + +B<#include <libtpms/tpm_memory.h>> + +B<#include <libtpms/tpm_error.h>> + +B<TPM_RESULT TPM_Malloc(unsigned char> **I<buffer>B<, + uint32_t> I<size>B<);> + +B<TPM_RESULT TPM_Realloc(unsigned char> **I<buffer>B<, + uint32_t> I<size>B<);> + +B<void TPM_Free(unsigned char> *I<buffer>B<);> + +=head1 DESCRIPTION + +The B<TPM_Malloc()> function is used to allocate a buffer of the given size. +The allocated buffer will be returned in the I<buffer> parameter. + +The B<TPM_Realloc()> function is used to resize a buffer. The new size of +the buffer is given in the I<size> 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<TPM_ALLOC_MAX> (64k) bytes. This size is sufficient +for all buffers needed by the TPM. + +Upon successful completion, the functions return B<TPM_SUCCESS>. In case the +requested buffer exceeds the limit, B<TPM_SIZE> will be returned. See further +possible error codes below. + +The B<TPM_Free()> function frees the memory previously allocated using +either B<TPM_Malloc()> or B<TPM_Realloc()>. + +=head1 ERRORS + +=over 4 + +=item B<TPM_SUCCESS> + +The function completed successfully. + +=item B<TPM_SIZE> + +The size of the requested buffer exceeds the limit or the +system is out of memory. + +=item B<TPM_FAIL> + +Requested buffer is of size 0. + +=back + +For a complete list of TPM error codes please consult the include file +B<libtpms/tpm_error.h> + +=head1 SEE ALSO + +B<TPMLIB_MainInit>(3), B<TPMLIB_Terminate>(3) +B<TPMLIB_Process>(3), B<TPMLIB_RegisterCallbacks>(3), B<TPMLIB_GetVersion>(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 |