From 3b703a76871ff464531762ee2f1e73ba190b79b8 Mon Sep 17 00:00:00 2001 From: Imran Desai Date: Wed, 17 Jun 2020 10:22:26 -0700 Subject: [PATCH] doc: Move necessary information from wiki Part of process to de-feature the wiki pages to avoid stale information remaining posted. Signed-off-by: Imran Desai --- README.md | 3 +- doc/Dependency-Matrix.md | 65 ++++++++++++++++++ doc/Getting-Started.md | 143 +++++++++++++++++++++++++++++++++++++++ doc/INSTALL.md | 2 +- doc/RELEASE.md | 3 +- 5 files changed, 212 insertions(+), 4 deletions(-) create mode 100644 doc/Dependency-Matrix.md create mode 100644 doc/Getting-Started.md diff --git a/README.md b/README.md index 77035e7015..b815046fa8 100644 --- a/README.md +++ b/README.md @@ -19,8 +19,7 @@ for information on how to submit those. ## Resources -The tpm2-tools wiki: - +Reference the tutorials at [tpm2-software.github.io](https://tpm2-software.github.io). TPM 2.0 specifications can be found at [Trusted Computing Group](http://www.trustedcomputinggroup.org/). diff --git a/doc/Dependency-Matrix.md b/doc/Dependency-Matrix.md new file mode 100644 index 0000000000..e3d263b855 --- /dev/null +++ b/doc/Dependency-Matrix.md @@ -0,0 +1,65 @@ +# Dependency Version Matrix + +tpm2-tools has an intricate dependency on the tpm2-tss project and the +tpm2-abrmd project. so below is a list tracking the dependencies of each +release/tag of tpm2-tools. + +**NOTE: tpm2-abrmd is an optional but suggested component** + +| tpm2-tools version | tpm2-tss version | tpm2-abrmd version| +|--------------------|------------------|-------------------| +|[master](https://github.com/01org/tpm2-tools)|[master](https://github.com/01org/tpm2-tss)|[master](https://github.com/01org/tpm2-abrmd)| +|[4.2](https://github.com/tpm2-software/tpm2-tools/releases/tag/4.2)|[>=2.4.0](https://github.com/tpm2-software/tpm2-tss/releases/tag/2.4.0)|[>=2.3.1](https://github.com/tpm2-software/tpm2-abrmd/releases/tag/2.3.1) +|[4.1.1](https://github.com/tpm2-software/tpm2-tools/releases/tag/4.1.1)|[>=2.3.1](https://github.com/tpm2-software/tpm2-tss/releases/tag/2.3.1)|[>=2.3.0](https://github.com/tpm2-software/tpm2-abrmd/releases/tag/2.3.0) +|[4.1](https://github.com/tpm2-software/tpm2-tools/releases/tag/4.1)|[>=2.3.1](https://github.com/tpm2-software/tpm2-tss/releases/tag/2.3.1)|[>=2.3.0](https://github.com/tpm2-software/tpm2-abrmd/releases/tag/2.3.0) +|[4.0](https://github.com/tpm2-software/tpm2-tools/releases/tag/4.0)|[>=2.3.1](https://github.com/tpm2-software/tpm2-tss/releases/tag/2.3.1)|[>=2.2.0](https://github.com/tpm2-software/tpm2-abrmd/releases/tag/2.2.0) +|[3.2.0](https://github.com/tpm2-software/tpm2-tools/releases/tag/3.2.0-rc0)|[2.0.0](https://github.com/tpm2-software/tpm2-tss/releases/tag/2.0.0)|[2.0.0](https://github.com/tpm2-software/tpm2-abrmd/releases/tag/2.0.0) +|[3.1.0](https://github.com/tpm2-software/tpm2-tools/releases/tag/3.1.0)|[2.0.0](https://github.com/tpm2-software/tpm2-tss/releases/tag/2.0.0)|[2.0.0](https://github.com/tpm2-software/tpm2-abrmd/releases/tag/2.0.0) +|[3.0.2](https://github.com/intel/tpm2-tools/releases/tag/3.0.2)|[1.3.0](https://github.com/intel/tpm2-tss/releases/tag/1.3.0)|[1.2.0](https://github.com/intel/tpm2-abrmd/releases/tag/1.2.0)| +|[3.0.1](https://github.com/intel/tpm2-tools/releases/tag/3.0.1)|[1.3.0](https://github.com/intel/tpm2-tss/releases/tag/1.3.0)|[1.2.0](https://github.com/intel/tpm2-abrmd/releases/tag/1.2.0)| +|[3.0](https://github.com/intel/tpm2-tools/releases/tag/3.0)|[1.3.0](https://github.com/intel/tpm2-tss/releases/tag/1.3.0)|[1.2.0](https://github.com/intel/tpm2-abrmd/releases/tag/1.2.0)| +|[2.1.0](https://github.com/01org/tpm2-tools/releases/tag/2.1.0)|[1.2.0](https://github.com/01org/tpm2-tss/releases/tag/1.2.0)|[1.1.1](https://github.com/01org/tpm2-abrmd/releases/tag/1.1.1)| +|[df751ae](https://github.com/01org/tpm2.0-tools/tree/df751ae5bea0bb057c9ee4cb0c1176c48ff68492)(master)|[1.1.0](https://github.com/01org/TPM2.0-TSS/releases/tag/1.1.0)|[1.0.0](https://github.com/01org/tpm2-abrmd/releases/tag/1.0.0)| +|[v2.0.0](https://github.com/01org/tpm2.0-tools/releases/tag/2.0.0)|[1.0](https://github.com/01org/TPM2.0-TSS/releases/tag/1.0)|old resourcemgr| +|[v1.1.0](https://github.com/01org/tpm2.0-tools/releases/tag/v1.1.0)|[1.0](https://github.com/01org/TPM2.0-TSS/releases/tag/1.0)|old resourcemgr| +|[v1.1-beta_1](https://github.com/01org/tpm2.0-tools/releases/tag/v1.1-beta_1)|[1.0-beta_1](https://github.com/01org/TPM2.0-TSS/releases/tag/1.0-beta_1)|old resourcemgr| +|[v1.1-beta_0](https://github.com/01org/tpm2.0-tools/releases/tag/v1.1-beta_0)|[v1.0-beta_0](https://github.com/01org/TPM2.0-TSS/releases/tag/v1.0-beta_0)|old resourcemgr| +|[14a7ff5](https://github.com/01org/tpm2.0-tools/tree/14a7ff527bc0411c215bd9d575f2866e1f2e71cf)|[210b770](https://github.com/01org/TPM2.0-TSS/tree/210b770c1dff47b11be623e1d1e7ffb02298fca5)|old resourcemgr| +|[4b4cbea](https://github.com/01org/tpm2.0-tools/tree/4b4cbeafe30430f42826592dee2abafec818385f)|[d4f23cc](https://github.com/01org/TPM2.0-TSS/tree/d4f23cc25c4c0fb66dd36897d2fad8e1e37c6443)|old resourcemgr| +|[e8150e4](https://github.com/01org/tpm2.0-tools/tree/e8150e48dd47f761dff10583631b2a0a30ee4d90)|[60ec042](https://github.com/01org/TPM2.0-TSS/tree/60ec04237b5344666435e129bd85f7496a6a9985)|old resourcemgr| +|[84d5f26](https://github.com/01org/tpm2.0-tools/tree/84d5f262f281556c57f7ec2fba06eda3acadd26c)|[371fdbc](https://github.com/01org/TPM2.0-TSS/tree/371fdbc638c55b9ac8a0eaec9375dbca0412861c)|old resourcemgr| +|[v1.0.1](https://github.com/01org/tpm2.0-tools/releases/tag/v1.0.1)|[1.0-alpha_0](https://github.com/01org/TPM2.0-TSS/releases/tag/1.0-alpha_0)|old resourcemgr| + +# Release Lifecycle + +General information can be found in the [RELEASE.md](https://github.com/tpm2-software/tpm2-tools/blob/master/RELEASE.md) +file. However, it doesn't really describe the overall life cycle of releases. +The tpm2-tools project has a bit of a BC/AD like split. Anything before 4.0 is +considered legacy and is or will be reaching end of life. Releases greater than +4.0 will always **will be backwards compatible**. Thus, based on the semver.org +rules outlined, pretty much dictates we will never be off of a 4.X version +number. Because of this, master will always be the *next* release, and bugfix +only releases can be branched off of *master* as needed. These patch level +branches will be supported on an as needed bases, since we don't have dedicated +stable maintainers. The majority of development will occur on *master* with +tagged release numbers following semver.org recommendations. This page +explicitly does not formalize an LTS support timeline, and that is intentional. +The release schedules and required features are driven by community involvement +and needs. However, milestones will be created to outline the goals, bugs, +issues and timelines of the next release. + +# End Of Life versions +- [1.X](https://github.com/tpm2-software/tpm2-tools/tree/1.X) +- [2.X](https://github.com/tpm2-software/tpm2-tools/tree/2.X) +- [3.0.X](https://github.com/tpm2-software/tpm2-tools/tree/3.0.X) + +# Near End of Life +- [3.0.X](https://github.com/tpm2-software/tpm2-tools/tree/3.0.X): EOL after +3.2.1 release. + +## OpenSSL + +tpm2-tools relies heavily on OpenSSL. OpenSSL will be EOL'ing 1.0.2 at the end +of 2019, see: https://www.openssl.org/blog/blog/2018/05/18/new-lts/. When this +occurs, we will remove OSSL 1.0.2 support from the tpm2-tools repository as +supporting an EOL crypto library is not a good idea. \ No newline at end of file diff --git a/doc/Getting-Started.md b/doc/Getting-Started.md new file mode 100644 index 0000000000..921b7d3287 --- /dev/null +++ b/doc/Getting-Started.md @@ -0,0 +1,143 @@ +# Introduction +Since you're here, I will assume you want to get started playing around with a +version 2.0 TPM. We will use a TPM simulator, so this will work for those +without hardware support. + +For those unfamiliar, the TPM provides out-of-band general cryptographic, +storage, policy and key management operations (among other things). + +There are generally 5 components when using a TPM. +1. The TPM itself, this can be a firmware TPM, a discreet TPM chip or a + simulator. +2. The optional but recommended resource manager (RM), which manages object + life cycles in the TPM. Examples of this are the userspace RM called abrmd + and the in-linux-kernel abrmd in the tpm driver itself. RMs implement the + same interface as a TPM. +3. The low-level system api called sapi. +4. The transmission interface library called tcti +5. A client using sapi, like the tpm2-tools project. + +When wishes to access the TPM, it will: +1. Create a tcti context. This is how it sends data to and from a TPM or + Resource Manager(RM). +2. Provide that tcti context when initializes the sapi. +3. Use the sapi interfaces to send commands to the TPM. + * The sapi builds command arrays and send them via the tcti to the TPM or RM. + * The sapi then parses the response array for error codes and other response + information. + +The tools are clients, that perform those three steps. + +# Installing + +Start off by satisfying all dependencies. Depending on what +version of the tpm2-tools is being used, you may need different +versions. Please consult the [dependency matrix](https://github.com/tpm2-software/tpm2-tools/doc/Dependency-Matrix). + +please install: + - [tss](https://github.com/tpm2-software/tpm2-tss) + - (optional) [pandoc](https://pandoc.org/) (required for manpage generation) + - (optional) lcov (required for configure option: --enable-code-coverage) + - (optional) [abrmd](https://github.com/tpm2-software/tpm2-abrmd) (required for abrmd) + +For example, on ubuntu, installing the master version of everything: +``` +# install package manager deps for tools +sudo apt-get install lcov pandoc autoconf-archive + +# install package manage deps for tss +sudo apt-get install liburiparser-dev + +# install package manager deps for abrmd +# Note: the dbus-x11 dependency is for dbus-launch not for abrmd itself. +sudo apt-get install libdbus-1-dev libglib2.0-dev dbus-x11 + +# install TSS itself +git clone https://github.com/tpm2-software/tpm2-tss.git +cd tpm2-tss +./bootstrap +./configure --enable-unit +make check +sudo make install + +# Install abrmd itself +git clone https://github.com/tpm2-software/tpm2-abrmd.git +cd tpm2-abrmd +./bootstrap +./configure --enable-unit --with-dbuspolicydir=/etc/dbus-1/system.d +dbus-launch make check +sudo make install + +# Install tools itself +git clone https://github.com/tpm2-software/tpm2-tools.git +cd tpm2-tools +./bootstrap +./configure --enable-unit +make check +sudo make install +``` +Note: we added **--enable-unit** to **configure** and **check** to **make**, +so that one can observe the unit tests passing. + +Now that you have the tss, abrmd and the tools installed, we can run hello world. + +## TPM Dependency +If you have a hardware TPM, that's great. If you don't, don't fret, there is a +simulator available. + +We don't recommend testing, development or learning against a real TPM. +For example, you could inadvertently lock something in NV ram that is very +difficult/impossible to erase or wear out NV ram with too many write cycles. We +recommend using the simulator, and hello world will expect it and abrmd to be in +place. + +### Installing the TPM2.0 Simulator: +``` +wget https://downloads.sourceforge.net/project/ibmswtpm2/ibmtpm974.tar.gz +mkdir ibmtpm974 +cd ibmtpm974 +tar -xavf ../ibmtpm974.tar.gz +cd src +make +``` +### Starting the TPM2.0 Simulator: +Now, while still in the src directory from section +*Installing the TPM2.0 Simulator* + +``` +./tpm_server & +TPM command server listening on port 2321 +Platform server listening on port 2322 +``` +That command will start the server listening on tcp/ip ports 2321 and 2322. + +Now that we have a TPM to send commands too, we need a resource manager (RM). +TPMs have very limited resources, so RM's are like virtual memory managers, and +help multiple clients use the TPM without stepping on each others toes. There +are caveats with RMs, but we won't discuss those here, and instead focus on the +basics. + +With that said, lets start the RM: +``` +tpm2-abrmd --allow-root --tcti=mssim +``` +abrmd is designed by default to connect to a hardware TPM, hwoever we need it to +connect to the `tpm_server` that was started previously, so pass the +`--tcti=mssim` option to tell it to do so. + +# Hello World + +With the `tpm_server` and the abrmd running, we can run a tool to get the pcr +values of a tpm. Running the ```tpm2_pcrread``` command should yield a result +like below: +``` +tpm2_pcrread +sha1 : + 0 : 0000000000000000000000000000000000000003 + 1 : 0000000000000000000000000000000000000000 + 2 : 0000000000000000000000000000000000000000 + 3 : 0000000000000000000000000000000000000000 + 4 : 0000000000000000000000000000000000000000 + 5 : 0000000000000000000000000000000000000000 + +``` diff --git a/doc/INSTALL.md b/doc/INSTALL.md index 816177ecf3..79beec9878 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -106,7 +106,7 @@ $ sudo dnf builddep tpm2-tools The package installed above contains all the dependencies for tpm2-tools included the projects mentioned at the beginning of this section (tpm2-tss and tpm2-abrmd) For more detailed information about the dependencies of tpm2-tss and tmp2-abrmd, please consult the corresponding links for each project. You can find these links in -the [Dependency-Matrix](https://github.com/tpm2-software/tpm2-tools/wiki/Dependency-Matrix) +the [Dependency-Matrix](https://github.com/tpm2-software/tpm2-tools/doc/Dependency-Matrix) ## Building diff --git a/doc/RELEASE.md b/doc/RELEASE.md index d6eac01e9d..bec0173a8b 100644 --- a/doc/RELEASE.md +++ b/doc/RELEASE.md @@ -99,7 +99,8 @@ The steps, in order, required to make a release. that release as the message for the GitHub release. **Add the dist tarball and signature file to the release**. -- Update the version matrix in the wiki ensuring that the CI is building against a released version of: +- Update the [dependency-matrix](https://github.com/tpm2-software/tpm2-tools/doc/Dependency-Matrix.md) + ensuring that the CI is building against a released version of: - [tpm2-abrmd](https://github.com/tpm2-software/tpm2-abrmd) - [tpm2-tss](https://github.com/tpm2-software/tpm2-tss)