README

   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