Skip to content

installation_notes

Jump to bottom
iadgovuser26 edited this page Aug 26, 2024 · 30 revisions

This page describes downloading, installing, setting up, and using the open source elements of the HIRS framework.

Supported Platforms

The HIRS Attestation Certificate Authority (ACA) supports HIRS ACA currently supports package based installation on

  • Redhat OS versions 8 (latest) and 9
  • Rocky OS versions 8 (latest) and 9
  • Ubuntu 22 LTS with limited support

The HIRS_Provisioner.NET currently supports package based installation on

  • Redhat OS versions 8 (latest) and 9
  • Rocky OS versions 8 (latest) and 9
  • Ubuntu 22 LTS with limited support
  • Windows 10 (latest)
  • Windows 11

Before You Begin

Confirm that the target environments for both the ACA and the Provisioner (which may be the same) meet the below requirements:

  1. The OS must be installed and configured for networking prior to installation. This should include:

    1. An administrative account that will be used for installing HIRS.
    2. A Fully Qualified Domain Name (FQDN) be assigned to the server running the ACA and
    3. A DNS system will resolve the name to an address. The certificate verification will not be able to complete successfully if the FQDN is not resolvable by DNS.

  2. The hardware must meet the HIRS minimum requirements.

    1. HIRS ACA may be a virtual machine or physical device
      1. A Supported OS (see list above)
      2. 50GB HD space
      3. 6GB RAM
    2. The Client device must have a TPM 2.0. The TPM must be enabled in the BIOS/UEFI setup (typically enabled by default). The BIOS/UEFI setup application is specific the platform hosting the TPM. Refer to the server/desktop user manuals for instruction on how to enable/clear the TPM.

  3. The Provisioner will need connectivity to the ACA. Check that any firewalls between the ACA server and Provisioner have port 8443 enabled.

  4. Setup an OS repository for the device. The HIRS installation package will attempt to install its dependencies for the system local software repository if they are not currently installed. It is highly suggested that an repository be setup prior to avoid dependency issues.

Installing the ACA

There are several options for installing and running a HIRS ACA:

Prerequisite libraries

There are several prerequisites required to run the ACA (Note: this section is no required when running an ACA docker image). To install the prerequisites: On RHEL based systems:

sudo dnf install java-1.17.0 wget tpm2-tools mariadb

On Debian based systems

sudo apt-get install openjdk-17-jdk git tpm2-tools

Using the ACA Docker Image

An ACA Docker image is now automatically created for each release. This is the preferred way to run/test an ACA. See the packages page for a complete list of published ACA docker images.

To download and run the ACA image (can take several minutes):

docker run --name=aca -p 8443:8443 ghcr.io/nsacyber/hirs/aca:latest

To check the container is running:

docker ps

To pull updated aca images:

docker pull ghcr.io/nsacyber/hirs/aca:latest

Use the following URL for viewing the ACA Portal:

https:localhost:8443/

Installing HIRS release packages

RHEL

To install the ACA on a Redhat or Rocky Linux download the latest rpm from the release page then run the command

sudo dnf install HIRS_AttestationCA*.rpm

Debian

To install the ACA on a Ubuntu Linux download the latest rpm from the release page then run the command

sudo apt-get install ./HIRS_AttestationCA*.deb

Install using packages created from Source

Follow the instructions from the HIRS build guide to build the HIRS ACA package. When built the ACA install packages can be found in HIRS_AttestationPortal\build\distributions.

Navigate to the HIRS project folder. Run the following command:

sudo dnf install HIRS_AttestationPortal\build\distributions\HIRS_AttestationCA*.rpm

Installing the Provisioner

To install the HIRS_Provisioner.NET on a Redhat or Rocky Linux download the latest rpm package from the release page then open a terminal and run the command

sudo dnf install HIRS_Provisioner.NET.*.rpm

To install the HIRS_Provisioner.NET on Ubuntu Linux download the latest deb package from the release page then open a terminal and run the command

sudo apt-get install ./HIRS_Provisioner.NET.*.deb

To install the HIRS_Provisioner.NET on Windows download the latest msi package from the release page then open a powershell windows as an administrator then run the command

msiexec /package HIRS_Provisioner.NET.*.msi /quiet

Then follow the instructions for setting up the HIRS_provisioner.NET in the HIRS_Provisioner.NET Readme.

Testing the install:

Open the ACA Portal

In your browser, navigate to the ACA Portal URL: https://<ACAserveraddress>:8443/HIRS_AttestationCAPortal

On installation, the ACA creates an SSL certificate chain. This may produce a warning in your browser. Once you acknowledge the warning, and perhaps configure an exception, the following page should appear: ACA_Default_Page Note that there may be delay after installing the ACA RPM as it starts up for the first time. The ACA portal will shortly be available via the browser.

Trigger a provision

On Linux: To kick off a provision on the client, open a terminal and run the command

sudo tpm_aca_provision

On Windows: Open a powershell terminal as an administrator and enter the command

tpm_aca_provision

Refresh the ACA and view the validation reports page:

https://<ACAserveraddress>:8443/HIRS_AttestationCAPortal/portal/validation-reports

The status on the page will reflect the ACA policy settings. Please refer to the Getting Started guide for further details on using the ACA and the ACA policy settings.

Clone this wiki locally