| 1 | What is libtpms?
|
|---|
| 2 | ----------------
|
|---|
| 3 |
|
|---|
| 4 | Libtpms is a library that targets the integration of TPM functionality
|
|---|
| 5 | into hypervisors, primarily into Qemu. Libtpms provides a very narrow
|
|---|
| 6 | public API for this purpose so that integration is possible. Only the
|
|---|
| 7 | minimum of necessary APIs are made publicly available.
|
|---|
| 8 |
|
|---|
| 9 | It is assumed that the user of libtpms is familiar with the concepts
|
|---|
| 10 | of the Trusted Platform Module (TPM). For the interaction with libtpms
|
|---|
| 11 | it is necessary to know how to construct valid TPM commands and to
|
|---|
| 12 | be able to parse their results. It is not within the scope of libtpms's
|
|---|
| 13 | documentation to provide background on this. See the section on references
|
|---|
| 14 | below.
|
|---|
| 15 |
|
|---|
| 16 |
|
|---|
| 17 | What files does the libtpms package provide?
|
|---|
| 18 | --------------------------------------------
|
|---|
| 19 |
|
|---|
| 20 | The main libtpms package provides the following files:
|
|---|
| 21 |
|
|---|
| 22 | /usr/lib64/libtpms.so.0
|
|---|
| 23 | /usr/lib64/libtpms.so.0.5.1
|
|---|
| 24 | /usr/share/doc/libtpms-0.5.1
|
|---|
| 25 | /usr/share/doc/libtpms-0.5.1/CHANGES
|
|---|
| 26 | /usr/share/doc/libtpms-0.5.1/LICENSE
|
|---|
| 27 | /usr/share/doc/libtpms-0.5.1/README
|
|---|
| 28 |
|
|---|
| 29 | Applications can link with -ltpms.
|
|---|
| 30 |
|
|---|
| 31 |
|
|---|
| 32 | What files does the libtpms development package provide?
|
|---|
| 33 | --------------------------------------------------------
|
|---|
| 34 |
|
|---|
| 35 | The libtpms development package (libtpms-devel) provides the following
|
|---|
| 36 | include files for applications to use:
|
|---|
| 37 |
|
|---|
| 38 | tpm_error.h
|
|---|
| 39 | tpm_library.h
|
|---|
| 40 | tpm_memory.h
|
|---|
| 41 | tpm_nvfilename.h
|
|---|
| 42 | tpm_tis.h
|
|---|
| 43 | tpm_types.h
|
|---|
| 44 |
|
|---|
| 45 | These files contain the data structures, data types and API calls supported
|
|---|
| 46 | by libtpms. It is recommended to not use any other API calls than those
|
|---|
| 47 | provided in these include files.
|
|---|
| 48 |
|
|---|
| 49 | All APIs are described in man pages. The man pages are part of the libtpms
|
|---|
| 50 | development package as well:
|
|---|
| 51 |
|
|---|
| 52 | TPMLIB_DecodeBlob
|
|---|
| 53 | TPMLIB_GetTPMProperty
|
|---|
| 54 | TPMLIB_GetVersion
|
|---|
| 55 | TPMLIB_MainInit
|
|---|
| 56 | TPMLIB_Process
|
|---|
| 57 | TPMLIB_RegisterCallbacks
|
|---|
| 58 | TPMLIB_Terminate
|
|---|
| 59 | TPMLIB_VolatileAll_Store
|
|---|
| 60 | TPM_Free
|
|---|
| 61 | TPM_IO_Hash_Data
|
|---|
| 62 | TPM_IO_Hash_End
|
|---|
| 63 | TPM_IO_Hash_Start
|
|---|
| 64 | TPM_IO_TpmEstablished_Get
|
|---|
| 65 | TPM_Malloc
|
|---|
| 66 | TPM_Realloc
|
|---|
| 67 |
|
|---|
| 68 |
|
|---|
| 69 | How to contribute?
|
|---|
| 70 | ------------------
|
|---|
| 71 | The mailing list for libtpms is libtpms@googlegroups.com.
|
|---|
| 72 |
|
|---|
| 73 | For patch submissions, please use a Signed-off-by: <your email> to indicate
|
|---|
| 74 | agreement to the DCO1.1.txt.
|
|---|
| 75 |
|
|---|
| 76 |
|
|---|
| 77 | Fuzzing
|
|---|
| 78 | -------
|
|---|
| 79 | Initial fuzzing is possible with clang & libfuzzer.
|
|---|
| 80 |
|
|---|
| 81 | You have to configure the project with --enable-fuzzer
|
|---|
| 82 | (--enable-sanitizer can also help spot more issues). Then you can
|
|---|
| 83 | build fuzz and run it with the testing corpus.
|
|---|
| 84 |
|
|---|
| 85 | Fuzz testing is known to work with Fedora 28 or later. It requires that the
|
|---|
| 86 | 'clang' package is installed.
|
|---|
| 87 |
|
|---|
| 88 | Ex:
|
|---|
| 89 | $ ./configure --with-openssl --with-tpm2 --enable-sanitizers --enable-fuzzer \
|
|---|
| 90 | CC=clang CXX=clang++
|
|---|
| 91 | $ make && make -C tests fuzz
|
|---|
| 92 | $ tests/run-fuzzer.sh
|
|---|
| 93 |
|
|---|
| 94 | oss-fuzz builds with its own fuzzer flags, and set $LIB_FUZZING_ENGINE
|
|---|
| 95 | to be linked with. The script run by oss-fuzz is tests/oss-fuzz.sh.
|
|---|
| 96 |
|
|---|
| 97 | Maintainers
|
|---|
| 98 | -----------
|
|---|
| 99 | libtpms is currently being maintained by Stefan Berger <stefanb@us.ibm.com>.
|
|---|
| 100 |
|
|---|
| 101 | References:
|
|---|
| 102 | -----------
|
|---|
| 103 |
|
|---|
| 104 | Documentation about the Trusted Platform Module (TPM) can be downloaded
|
|---|
| 105 | from the Trusted Computing Group's website at
|
|---|
| 106 |
|
|---|
| 107 | http://www.trustedcomputinggroup.org
|
|---|
