Skip to content

Latest commit

 

History

History
266 lines (220 loc) · 8.19 KB

INSTALL.md

File metadata and controls

266 lines (220 loc) · 8.19 KB
Raw

This file contains instructions to build and install the TSS libraries.

Dependencies

To build and install the tpm2-tss software the following software packages are required. In many cases dependencies are platform specific and so the following sections describe them for the supported platforms.

GNU/Linux:

  • GNU Autoconf
  • GNU Autoconf Archive, version >= 2019.01.06
  • GNU Automake
  • GNU Libtool
  • C compiler
  • C library development libraries and header files
  • pkg-config
  • doxygen
  • OpenSSL development libraries and header files, version >= 1.1.0
  • libcurl development libraries
  • Access Control List utility (acl)
  • JSON C Development library
  • Package libusb-1.0-0-dev

The following are dependencies only required when building test suites.

  • Integration test suite (see ./configure option --enable-integration):
  • Unit test suite (see ./configure option --enable-unit):
    • cmocka unit test framework, version >= 1.0
  • Code coverage analysis:
    • lcov

Most users will not need to install these dependencies.

Ubuntu

$ sudo apt -y update
$ sudo apt -y install \
  autoconf-archive \
  libcmocka0 \
  libcmocka-dev \
  procps \
  iproute2 \
  build-essential \
  git \
  pkg-config \
  gcc \
  libtool \
  automake \
  libssl-dev \
  uthash-dev \
  autoconf \
  doxygen \
  libjson-c-dev \
  libini-config-dev \
  libcurl4-openssl-dev \
  uuid-dev \
  libltdl-dev \
  libusb-1.0-0-dev \
  libftdi-dev

Note: In some Ubuntu versions, the lcov and autoconf-archive packages are incompatible with each other. It is recommended to download autoconf-archive directly from upstream and copy ax_code_coverage.m4 and ax_prog_doxygen.m4 to the m4/ subdirectory of your tpm2-tss directory.

Fedora

libtool automake autoconf and autoconf-archive should be installed:

$ sudo dnf install libtool automake autoconf autoconf-archive

There is a package already, so the package build dependencies information can be used to make sure that the needed packages to compile from source are installed:

$ sudo dnf builddep tpm2-tss

If you want to install a version from 4.0.0 and the default version of the release is lower than this version you have to install libuuid-devel additionally:

$ sudo dnf install libuuid-devel

Windows

Windows dlls are built using the LLVM (clang-cl) toolset. We have only tested using Visual Studio 2019, but Visual Studio 2022 should also be supported. Building should be as simple as loading the tpm2-tss solution (tpm2-tss.sln) with a compatible and properly configured version of Visual Studio 2019+ and pressing the 'build' button.

References

Visual Studio 2019+ with "Clang for Windows": https://learn.microsoft.com/en-us/cpp/build/clang-support-msbuild Universal CRT overview & setup instructions: https://docs.microsoft.com/en-us/cpp/porting/upgrade-your-code-to-the-universal-crt

Building From Source

Bootstrapping the Build

To configure the tpm2-tss source code first run the bootstrap script, which generates list of source files, and creates the configure script:

$ ./bootstrap

Any options specified to the bootstrap command are passed to autoreconf(1).

Configuring the Build

Then run the configure script, which generates the makefiles:

$ ./configure

Custom ./configure Options

In many cases you'll need to provide the ./configure script with additional information about your environment. Typically you'll either be telling the script about some location to install a component, or you'll be instructing the script to enable some additional feature or function. We'll cover each in turn.

Invoking the configure script with the --help option will display all supported options.

The default values for GNU installation directories are documented here: https://www.gnu.org/prep/standards/html_node/Directory-Variables.html

udev Rules

The typical operation for the tpm2-abrmd is for it to communicate directly with the Linux TPM driver using libtcti-device from the TPM2.0-TSS project. This requires that the user account that's running the tpm2-abrmd have both read and write access to the TPM device node /dev/tpm[0-9]. But users could also access the TPM directly so the udev rule is installed by tpm2-tss.

--with-udevrulesdir

This requires that udev be instructed to set the owner and group for this device node when its created. We provide such a udev rule that is installed to ${libdir}/udev/rules.d. If your distro stores these rules elsewhere you will need to tell the build about this location.

Using Debian as an example we can instruct the build to install the udev rules in the right location with the following configure option:

--with-udevrulesdir=/etc/udev/rules.d

--with-udevrulesprefix

It is common for Linux distros to prefix udev rules files with a numeric string (e.g. "70-"). This allows for the rules to be applied in a predictable order. This option allows for the name of the installed udev rules file to have a string prepended to the file name when it is installed.

Compiling the Libraries

Then compile the code using make:

$ make -j$(nproc)

Installing the Libraries

Once you've built the tpm2-tss software it can be installed with:

$ sudo make install

This will install the libraries to a location determined at configure time. See the output of ./configure --help for the available options. Typically you won't need to do much more than provide an alternative --prefix option at configure time, and maybe DESTDIR at install time if you're packaging for a distro.

Post-install

udev

Once you have this udev rule installed in the right place for your distro you'll need to instruct udev to reload its rules and apply the new rule. Typically this can be accomplished with the following command:

$ sudo udevadm control --reload-rules && sudo udevadm trigger

If this doesn't work on your distro please consult your distro's documentation for UDEVADM(8).

Users who should have access to the TPM and the FAPI keystore should be included in the tss group.

sudo usermod -aG tss <username>

ldconfig

It may be necessary to run ldconfig (as root) to update the run-time bindings before executing a program that links against libsapi or a TCTI library:

$ sudo ldconfig

Building In A Container

If you are having trouble installing the dependencies on your machine you can build in a container.

$ docker build -t tpm2 .
$ docker run --name temp tpm2 /bin/true
$ docker cp temp:/tmp/tpm2-tss tpm2-tss
$ docker rm temp

tpm2-tss is now in your working directory and contains all the built files.

To rebuild using your local changes mount your tpm2-tss directory as a volume.

$ docker run --rm -ti -v $PWD:/tmp/tpm2-tss tpm2-tss \
  sh -c 'make -j$(nproc) check'

Doxygen Documentation

To build Doxygen documentation files, first install package Doxygen. Then generate the documentation with:

$ ./configure --enable-doxygen-doc
$ make doxygen-doc

The generated documentation will appear here:

  • doxygen-doc/html HTML format (start with file doxygen-doc/html/index.html)
  • doxygen-doc/rtf/refman.rtf RTF format

Building for embedded

The libraries SYS, ESYS, MU, RC, tctildr, tcti-spi-helper, tcti-i2c-helper can also be build for embedded devices. The following is an example to build for cortex-m4:

./bootstrap
./configure \
        --disable-fapi \
        --disable-esys \
        --disable-policy \
        --disable-tcti-cmd \
        --disable-tcti-device \
        --disable-tcti-libtpms \
        --disable-tcti-mssim \
        --disable-tcti-pcap \
        --disable-tcti-spi-lt2go \
        --disable-tcti-spi-ftdi \
        --disable-tcti-swtpm \
        --disable-doxygen-doc \
        --enable-nodl \
        --host=arm-none-eabi \
        --prefix=/home/afuchs/tpm2-software/INSTALL.uC \
        CFLAGS='-mcpu=cortex-m4 -mfloat-abi=hard -mfpu=fpv4-sp-d16 -mthumb' \
        LDFLAGS='--specs=nosys.specs'
make

Test operating systems in the CI

  • ubuntu-20.04
  • fedora-32
  • opensuse-leap
  • ubuntu-22.04
  • alpine-3.15
  • FreeBSD