-
Notifications
You must be signed in to change notification settings - Fork 58
Hirs build guide
This guide is designed to provide a developer with the information and resources needed to build the HIRS Attestation Certificate Authority (ACA) Server, Trusted Platform Module (TPM) v1.2 and v2.0 Client Provisioners, and the TPM_Module command line tool. In particular, it will cover development environment setup, general instructions for building and packaging the ACA, Provisioners, and TPM_Module, as well as attempting to note any pitfalls that may be encountered.
- ACA Server and TPM v1.2 Client Provisioner
- TPM v2.0 Client Provisioner
- TPM_Module
- General HIRS Packaging
- Installing Packages
Most of the HIRS project is written in Java and is built using the Gradle build tool. Each of the sub-projects can be built individually using simple Gradle commands.
(NOTE: These projects are also referred to as HIRS_AttestationCA and HIRS_Provisioner, respectively.)
A number of tools should be installed before attempting to build any of the Java-based HIRS sub-projects. Specific instruction is provided regarding Gradle as it pertains to this project.
The Gradle Build Tool is used to generate platform-dependent build files, run tests, and manage deployment packaging. In particular, the HIRS project relies on the Gradle Wrapper to maintain consistent versioning for Gradle across all developers. Presently, the target Gradle version is 2.10, and it is expected that any updates to Gradle files be checked against the Wrapper or, at the very least, the 2.10 version of Gradle to ensure that no change in minimum Gradle version has occurred.
- JDK Version 8+
- Protobuf Compiler
- RPM Build (RHEL-based environments)
- Build-essential (Debian-based environments)
- Devscripts (Debian-based environments)
- Lintian (Debian-based environments)
- Debhelper (Debian-based environments)
Due to the nature of Java build tools, Gradle manages all of the dependencies and sub-dependencies needed to build the various Java-based HIRS sub-projects. When a build is performed, it will attempt to check the local Maven package repository. If the packages can't be found there, then it will attempt to reach out to the central Maven package repo and/or any other configured package repositories.
If additional repositories are required, then an update needs to be made to the root HIRS build.gradle file. Locate the repositories script block and add any new repositories as allowed by the Gradle RepositoryHandler.
The following commands have been provided to quickly install the necessary developer dependencies for known supported environments.
sudo apt-get install openjdk-8-jdk protobuf-compiler build-essential devscripts lintian debhelper
sudo yum install java-1.8.0-openjdk-devel protobuf-compiler rpm-build
This project makes use of Java 8 coding conventions/features, so any version of Java prior to version 8 is unsupported.
Please ensure the dependencies referenced in the previous section are installed before attempting to build.
Two procedures for building with Gradle are described below.
(NOTE: This assumes Gradle to be installed as a plugin in the local IntelliJ installation.)
- Import the root directory as a project into the IntelliJ IDE. It should detect that it's a Gradle Project and that there's a Gradle Wrapper.
- Click
Build>Build Project
Only a few Gradle commands are necessary for building HIRS and its sub-projects. As mentioned in the previous section on Gradle, a Gradle Wrapper is provided and should be preferred when building the project. It's easily spotted as the gradlew and gradlew.bat files. The following commands use the wrapper. They can be used with Gradle directly, but this is discouraged.
- Navigate to the root of the HIRS project directory.
- Run the following command to build and test the project:
./gradlew clean build
No sub-project specific packaging has been provided for the ACA or TPM v1.2 Provisioner. Please refer to the section on General HIRS Packaging for more details.
As one of only two C++ components of the project, it is the only sub-project that is built using CMake. As such, this can be built entirely independently of Gradle, but does have a Gradle task that allows for Gradle to manage the CMake build process.
(NOTE: This sub-project is also referred to as HIRS_ProvisionerTPM2.)
A number of developer dependencies and tools should be installed before attempting to build this provisioner. Specific instruction is provided regarding CMake as it pertains to this project.
(NOTE: Some of these dependencies are not available in the base package repositories of the Host OS. It may be necessary to consult the docs for your corresponding environment to determine if/which repositories manage these dependencies.)
The CMake cross-platform development tool suite is used to generate platform-dependent build files, tests, and deployment packages. Currently supported development environments all contain, or have available for installation, the minimum version of CMake 2.8.12. If expansion into new development environments is desired, it must be ensured that this minimum version is installed accordingly. Furthermore, any updates to any of the project CMake files should be cross-referenced with the associated 2.8.12 documentation to ensure no change in the minimum version has occurred.
- Make
- Git
- Gcc-C++
- Doxygen
- GraphViz
- Protobuf Compiler
- CppCheck (Optional)
- Gradle (Optional)
- Python 2 (Optional)
- SSH2
- OpenSSL
- Log4CPlus
- Protobuf
- RE2
- Tpm2-Tss
In addition to the above libraries, there are several other dependencies managed by CMake, such that an active Internet connection is required to do a complete, clean build of the sub-project.
The optional dependencies listed above will be touched on under the Build process in the next section.
For further information regarding necessary versions of repositories known to host these packages, please consult the /docs section of the HIRS_ProvisionerTPM2 sub-project and find the corresponding development environment. If the Host OS being developed on is not listed, then you may attempt to reference the other guides for necessary minimum versions that must be supplied. Those should be consistent throughout.
The following commands have been provided to quickly install the necessary developer dependencies for known supported environments.
sudo apt-get install cmake make git g++ doxygen graphviz protobuf-compiler cppcheck liblog4cplus-dev libssl-dev libprotobuf-dev libre2-dev libsapi-dev
sudo yum install epel-release cmake make git gcc-c++ doxygen graphviz protobuf-compiler cppcheck python libssh2-devel openssl log4cplus-devel protobuf-devel re2-devel tpm2-tss-devel
This project makes use of C++11 coding conventions/features. Presently, only the gcc compiler is supported, and only if the version supports C++11; however, if an alternative is required, please consult the compiler support page to ensure compilation compatibility before attempting CMake integration.
Please ensure the dependencies referenced in the previous section are installed before attempting to build.
Two procedures for building the TPM 2.0 Provisioner with CMake and two with Gradle are described below.
- Import the root directory as a project into the CLion IDE.
- Click
Tools>CMake>Reset Cache and Reload Project - Click
Run>Build
- Navigate to the root of the project directory.
- Make a build folder.
- Navigate into the build folder.
- Run the following command to generate the appropriate make files:
cmake ../
- Run the following command to build the executable in the
bindirectory of the build folder:
make
(NOTE: This requires Gradle to be installed and placed on the path.)
- Navigate to the root of the entire HIRS project.
- Run the following command:
./gradlew :HIRS_ProvisionerTPM2:fullBuild
- Navigate to the root of the entire HIRS project.
- Run the following command:
./gradlew HIRS_ProvisionerTPM2:fullBuild
By default, each of these builds will gather additional third-party dependencies, run a style check with cpplint.py, run static analysis with cppcheck, run the unit test suite, and will generate code documentation (which is placed in the /docs directory of the HIRS_ProvisionerTPM2 sub-project.)
-
With regards to the optional dependencies, Python 2 is required for style checking. If Python 2 is not installed, set the
STYLE_CHECKoption toOFFas part of the CMake Command or in the rootCMakeLists.txtfile. -
Additionally,
cppcheckis used to provide static code analysis. To bypass the static analysis, set theSTATIC_ANALYSISoption toOFFas part of the CMake Command or in the rootCMakeLists.txtfile. -
CMake will fetch additional third-party dependencies from GitHub during a clean build. This will fail if these cannot be retrieved, so please ensure an active Internet connection before building.
-
If it is found that CMake is building in an unusual/undesired directory, it's likely that CMake is using a cached target directory in lieu of an implicit target. At this point, look around the local project for a CMakeCache.txt file and delete it to force a cache refresh.
Two methods for packaging have been provided. These are for packaging only the HIRS_ProvisionerTPM2 sub-project. To package everything at once, see the section on General HIRS Packaging.
The CMakeLists is configured to package the project into an RPM using CPack. To build the RPM, navigate to the target build directory and run the following command:
cpack
This will create the package in the current build directory.
A shell script that does a clean build before packaging the project has been provided under the /package directory of the HIRS_ProvisionerTPM2 sub-project. To build/package in this fashion, simply run the following command:
./<path_to_HIRS_ProvisionerTPM2>/package/package.tpm2.<target_runtime_environment>.sh
For the above command, <path_to_HIRS_ProvisionerTPM2> and <target_runtime_environment> are left to be filled in by the user based on their personal development environment and target runtime environment.
Upon completion of the packaging step, it will move the newly created package to the corresponding package directory of the root HIRS project. For more information regarding the structure of the root package directory, see the section on Running the Packaging Scripts.
(NOTE: Packaging of the software for a given distribution should be done in the same environment as the target environment. Due to host-system specific, compilation-time targeting of certain system libraries and APIs, cross-platform compilation is not advised and could lead to package installation errors.)
(NOTE: The only supported runtime environment is currently CentOS 7. As more support is added, options for packaging in these same two fashions will be added to keep the packaging process consistent throughout.)
There is a sub-project within HIRS referred to as the TPM_Module. Aside from the TPM v2.0 Client Provisioner, this is the only other C++ component of the HIRS project. Like the TPM v2.0 Client Provisioner, this can be built entirely independently of Gradle, but does have a Gradle task that allows for Gradle to manage the build process. Unlike the TPM v2.0 Client Provisioner, however, it does not make use of CMake in any way and relies solely on the regular Make tool for building.
A number of developer dependencies and tools should be installed before attempting to build the TPM_Module.
- Make
- Gcc-C++
- RPM Build (RHEL-based environments)
- Build-essential (Debian-based environments)
- Devscripts (Debian-based environments)
- Lintian (Debian-based environments)
- Debhelper (Debian-based environments)
- TrouSerS
- Libtspi (Debian-based environments)
The following commands have been provided to quickly install the necessary developer dependencies for known supported environments.
sudo apt-get install make g++ build-essential devscripts lintian debhelper trousers libtspi-dev
sudo yum install make gcc-c++ rpm-build trousers-devel
The TPM_Module predates the TPM v2.0 Client Provisioner by a number of years, and, as such, it can be safely assumed that if the compiler being used matches the minimum C++ version for the TPM v2.0 Client Provisioner, then it is more than capable of building this sub-project.
Please ensure the dependencies referenced in the previous section are installed before attempting to build.
At this point, there is only one way to build the TPM_Module and that involves the Make tool. For this sub-project, there are only two targets for Make. One builds the sub-project, and the other cleans it.
- Navigate to the root of the HIRS project.
- Navigate into the
/tpm_moduledirectory - Run the following command:
make
When its done, there should be a tpm_module binary in the current directory.
No sub-project specific packaging has been provided for the TPM_Module. Please refer to the section on General HIRS Packaging for more details.
For convenience, several scripts have been provided to simplify packaging the HIRS sub-projects into various formats, such as .rpm or .deb. Aside from the, TPM v2.0 Client Provisioner, these scripts are the only quick means by which to package the HIRS sub-projects that doesn't require manual intervention.
These scripts have been written such that all sub-projects are first compiled, and then converted into the target environment's corresponding package format. Tests are ignored when packaging, so it is not recommended to skip the sub-projects' sections on building if new development has occurred.
(WARNING: Before attempting the following commands, please ensure all of the tools and developer libraries are installed as specified in each of the previous "Development Environment Setup" sections.)
The packaging scripts can be found under the /package directory at the root of the HIRS project. This allows for any of them to be run with the following command:
./<path_to_HIRS_root>/package/package.<target_runtime_environment>.sh
For the above command, <path_to_HIRS_root> and <target_runtime_environment> are left to be filled in by the user based on their personal development environment and target runtime environment.
Upon completion, the output of the package scripts can be found in the root /package directory under the sub-directory corresponding to the target runtime environment's package type. For example, package.centos.sh will produce a /package/rpm directory to house all of the artefacts produced from invoking that particular package script.
To further delineate between individual sub-projects, the package scripts will move the packages into directories indicating whether the sub-project was Java- or C++-based. For Java sub-projects, the packages are placed into the /noarch directory, and for C++ sub-projects, the packages can be found in their /x86_64 directory.
To clarify using the same package.centos.sh example, the complete path to one of the produced RPM files would be: /<root_HIRS_directory>/package/rpm/RPMS/x86_64/<rpm_name>.rpm.
To install any of the HIRS packages produced via this guide, please refer to the Installation Notes for more details.
(IMPORTANT: Runtime dependencies may differ from the developer dependencies and tools discussed herein. Please ensure that all of the dependencies specified in the Installation Notes are installed for the packages' corresponding runtime environments.)