Verifier is a Java library responsible for performing FPGA attestation. It is able to retrieve measurements (evidence) from the FPGA device and compare it with reference integrity manifest (RIM). It also retrieves and validates signature and chain of certificates to confirm authenticity and integrity of the measurements.

Workload is a sample application that triggers Verifier's interface.

During attestation, communication is done via Hard Processor System (HPS), thus a listening TCP server (FCS Server) must be enabled on HPS, which can be found here.

After FCS Server is up and running, note down the #HOST# (hostname or ip address of HPS) and #PORT# (of FCS Server).

Stratix10

Agilex

Stratix10

Agilex

1. Java 11

2. FCS Server should be up and running on HPS, with TCP traffic enabled

3. Configure network for outgoing communication on port 443 (HTTPS) and TCP communication to #HOST#:#PORT# of the FCS Server

4. Prepare Product Owner Root Signing Key (root_private.pem), chain (root.qky) and quartus_sign tool must be available to be used during initialization step. Below links to official Quartus Prime user guide:

   1. Stratix10
   2. Agilex

5. (Recommended) Set up Java Cryptography Extension (JCE) Provider of your choice (Gemalto Luna SA HSM, nCipher etc.) (Default) Alternatively, built-in BouncyCastle (link and repository) library can be used with no additional configuration

6. Generate Reference Integrity Manifest (RIM) file for your board design using quartus_pfg tool

   quartus_pfg -c "my_design.rbf" stratix10.rim

Build and deploy project using gradle:

./gradlew clean build deploy

WARNING Task deploy will overwrite the content of out/ directory.

In command line set strong password to security provider in environment variable env:VERIFIER_SECURITY_PROVIDER_PASSWORD

export VERIFIER_SECURITY_PROVIDER_PASSWORD=

Output libraries are located under out/ directory together with Verifier's config file config.properties.

Run workload sample application (which is a fat jar already containing the Verifier lib) with basic arguments

java -jar ./out/workload.jar -i "" -c HEALTH

The output during first run shall be the instruction how to configure the library with chosen security provider. Edit the config.properties and use quartus_sign tool with private key root_private.pem and chain root_chain.qky to sign the pubkey and complete the first run process.

WARNING By default BouncyCastle security provider is used. It creates a file in /tmp directory. This /tmp directory might be cleaned after machine reboot. Edit security-provider-params.security.input-stream-param in config.properties to change this directory. For enhanced security it is recommended to use a stronger security provider.

Note

This is only one-time operation. Clear the verifier-key-params.key-name parameter from config.properties in case it has to be repeated or a new Signing Key must be created.

After the library with security provider is configured run the workload sample app again, this time providing #HOST# and #PORT# of the FCS Server running on HPS.

The command will verify the connection and return the device id (chip id) of FPGA

java -jar ./out/workload.jar -i "host:#HOST#; port:#PORT#" -c HEALTH

e.g.,

java -jar ./out/workload.jar -i "host:localhost; port:50001" -c HEALTH

Provide #PUF_TYPE# identifier and #CONTEXT# (hex string up to 28 bytes)

java -jar ./out/workload.jar -i “host:#HOST#; port:#PORT#” -c CREATE --puf-type #PUF_TYPE# --context #CONTEXT#

where:

• PUF_TYPE is an integer identifier of enum:

  0 - IID, 1 - INTEL, 2 - UDS_EFUSE, 3 - IIDUSER, 4 - INTEL_USER

• CONTEXT is random hex value provided as seed to SDM FW and cached by Verifier, max 28 bytes length

e.g.,

java -jar ./out/workload.jar -i “host:localhost; port:50001” -c CREATE --puf-type 2 --context 01020304050607080A0B0C0D0E0F0F112233445566778899AABBCC

Provide #PATH# to generated .rim file:

java -jar ./out/workload.jar -i “host:#HOST#; port:#PORT#” -c GET --ref-measurement #PATH#

e.g.,

java -jar ./out/workload.jar -i “host:localhost; port:50001” -c GET --ref-measurement ./stratix10.rim

Verifier uses an EC 384 private key which must be protected in a security provider. Security provider is a choice of the user, however it must implement Java Cryptography Extension (JCE) interface.

By default, built-in file-based BouncyCastle library is used. It creates a file in location specified in config.properties under security-provider-params.security.input-stream-param parameter. The file is encrypted with the master key specified by user:

1. (recommended) either in environment variable env:VERIFIER_SECURITY_PROVIDER_PASSWORD
2. or in config.properties under security-provider-params.security.password

Other settings under security-provider-params are already filled in and are specific to BouncyCastle.

For other providers, user must provide a path to the provider's jar to application classpath and update config.properties with values specific for that provider.

Run the below command providing path to provider's jar:

Linux

java -cp workload.jar:[PATH_TO_PROVIDER_JAR] com.intel.bkp.workload.WorkloadApp ...

Windows

java -cp [PATH_TO_PROVIDER_JAR];workload.jar com.intel.bkp.workload.WorkloadApp ...

Example

java -cp workload.jar:/opt/libs-ext/OtherSecurityProvider.jar com.intel.bkp.workload.WorkloadApp -i "host:localhost; port:50001" -c HEALTH

Verifier can also be integrated in User’s sample workload application. To do this, invoke a below command providing path to the library jar file. The Workload from out/ directory is not used in this case. Verifier API is described in Attestation Software Architecture Specification (SAS) and interface can be found in Verifier/src/main/java/com/intel/bkp/verifier/interfaces/VerifierExchange.java.

Linux:

java -cp sample-app.jar:Verifier.jar com.example.SampleApp ...

Windows:

java -cp "Verifier.jar;sample-app.jar" com.example.SampleApp ...

Verifier iterates over each block of RIM json file and checks whether all expected data is present in response from device, i.e.:

• in measurement response for Stratix10,

• in measurement response and certificate chain for Agilex.

Note

In case of Stratix10 device, layer 1 measurement (FW CMF descriptor hash) cannot be trusted, therefore it is not parsed from response. Including this measurement block in RIM for S10 will always cause attestation to fail.

Application logs are presented in the console output and saved to file:

./log/workload.%d{yyyy-MM-dd}.log

By default INFO level is set. To change it to more detailed add parameter --log-level when running Workload:

java workload.jar (…) --log-level TRACE

All possible options are presented when called without any parameters:

OFF, ERROR, WARN, INFO, DEBUG, TRACE

Configuration file config.properties contains parameters that will be parsed by Verifier, not the workload sample app.

Workload application possible return codes:

During first run or when Verifier Signing Key needs to be rotated, clear the verifier-key-params.key-name from config.properties. In next run, a new key will be created, follow the instruction in the log to complete the process.

Additionally, you may clear the verifier-key-params.verifier-root-qky-chain.single-chain-path and verifier-key-params.verifier-root-qky-chain.multi-chain-path parameters. If not cleared, during next run the existing files in those locations will be backed up with a new name:

existing_chain.qky.backup_<timestamp_millis>_<random_hex_value>

e.g.,

existing_chain.qky.backup_9918285401_AABBCCDD