· 06/12/2024 ·
Faithful Verification tool
The Faithful Verification (FV) tool is a Linux command-line utility that can be used to verify the fidelity of an Intel® Trust Authority token. This is an optional tool that helps an attester or relying party verify the integrity of the Intel Trust Authority environment.
Faithful Verification
A token is "faithful" when it is generated by authentic Intel Trust Authority services in an attested trusted execution environment (TEE). Intel Trust Authority includes a self-monitoring feature called Faithful Verification. All Intel Trust Authority microservices involved in generating an attestation token run in a TEE. When a TEE-protected microservice starts, attestation-related artifacts such as TEE quotes, TCB collaterals, current policy requirements, and service IDs are collected and saved in a ledger-backed database.
All token generation processing occurs in these TEEs, and protected assets are released only to microservice instances that meet the TEE policy requirements. The attestation information for each of these microservices is referenced in the verifier_instance_ids section in every Intel Trust Authority token generated.
These ledger references in an Intel Trust Authority attestation token can be used to validate the specific microservice instances that produced the token, and to retrieve their TEE attestation information. When Intel Trust Authority receives a valid token audit request, such as POST TokenAuditReport, it generates a token audit report based on the contents of the validation ledger. The Faithful Verification tool gets a token audit report for the given token, and then independently validates the TEE quotes. In this way an Intel Trust Authority user can audit the secure processing of attestation tokens, and check that the Intel Trust Authority microservices and TEEs are valid. The Faithful Verification tool can audit attestation tokens for up to two years following the token issuance date.
Downloading the Faithful Verification tool
The Faithful Verification tool is a downloadable executable found on the downloads page of the Intel Trust Authority portal.
Signature Verification
To verify the signature of the Faithful Verification tool, perform the following steps.
Extract the executable binary, signature and the certificate from the downloaded .zip file.
Extract the public key from the certificate.
$ openssl x509 -in <certificate>.cer -pubkey -noout > public_key.pem
- Create a hash of the binary.
$ openssl dgst -out binaryHashOutput -sha512 -binary <Signed binary file to be verified>
- Verify the signature using the hash of the binary.
$ openssl pkeyutl -verify -pubin -inkey public_key.pem -sigfile <signature_file>.sig -in binaryHashOutput -pkeyopt digest:sha512 -pkeyopt rsa_padding_mode:pss
Prerequisites
- Ubuntu 20.04 LTS (Focal) or Ubuntu 22.04 LTS (Jammy)
- Intel® SGX DCAP (Data Center Attestation Primitives) is required for quote verification. Intel SGX DCAP must be installed on the host system where the FV tool will run.
- The host system must have access to Intel® SGX PCCS (Provisioning Certificate Caching Service) for SGX collaterals.
Note
Valid characters include: numbers 0 through 9, upper and lowercase English characters, underscore (_), colon (;), period (.), slash (/), dash (-), and a space ( ).
Installing Intel SGX DCAP libraries
To add the Intel SGX repository and install the Intel SGX DCAP library packages, run the following commands for Ubuntu 20.04. If you are using Ubuntu 22.04, you must change the word focal to jammy in the first line.
echo 'deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main' > /etc/apt/sources.list.d/intel-sgx.list
wget -qO - https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | apt-key add -
apt-get update
apt-get install -y libsgx-urts libsgx-dcap-quote-verify-dev libsgx-dcap-default-qpl
After installation, edit /etc/sgx_default_qcnl.conf as follows to point Intel SGX DCAP to use PCCS at https://api.trustedservices.intel.com/sgx/certification/v3/.
{
// *** ATTENTION : This file is in JSON format so the keys are case sensitive. Don't change them.
//PCCS server address
"pccs_url": "https://api.trustedservices.intel.com/sgx/certification/v3/",
// To accept insecure HTTPS certificate, set this option to false
"use_secure_cert": true,
Use the following command to check that the system can connect to Intel PCCS.
curl -v -X GET "https://api.trustedservices.intel.com/sgx/certification/v3/qe/identity"
If this command returns a 200 OK with PCS added identity content, DCAP should be able to connect.
Verifying an attestation token
The Faithful Verification tool requires an Intel Trust Authority attestation token. Save the token to a file (for example, token.jwt) on the system where Faithful Verification will run.
Create an answer file (fv.env in this example) to configure FV, replacing the API_KEY value with an attestation API key:
# fv.env
TRUSTAUTHORITY_BASE_URL=https://api.trustauthority.intel.com
API_KEY=U123JtvpeE6JB12396bKx3iZ91t123c84GsKd123
Note
If you are in the European Union (EU) region, use the following Intel Trust Authority URL:
TRUSTAUTHORITY_BASE_URL=https://api.eu.trustauthority.intel.com
Configure the Faithful Verification tool using the config command.
./faithful-verifier config -v fv.env
Run the verify command, providing the attestation token to verify:
./faithful-verifier verify -t token.jwt
The Faithful Verification tool does this by independently validating the Intel SGX quotes for each of the quoted services using the Intel SGX DCAP libraries and TCB requirements from the Intel SGX PCS server. Quotes are validated without using any Intel Trust Authority attestation resources. In this way, the "faithfulness" of the Intel Trust Authority token can be verified without relying only on Intel Trust Authority's assertion.
Note
Verification depends on the Intel SGX DCAP libraries communicating to the public Intel PCS server to attest the Intel SGX quotes from the faithfulness report. If this communication is blocked, such as by a proxy configuration, the Faithful Verification tool may appear to "hang" until manually stopped.
Sample output
The following is a sample command-line output showing the result for a token that passed verification without errors:
{
"052335ca-7c5c-4dbc-b373-d0f7774392f6": [
"Service record quote for appraisal-service with id: 052335ca-7c5c-4dbc-b373-d0f7774392f6 is valid",
"appraisal-service with id: 052335ca-7c5c-4dbc-b373-d0f7774392f6 passed verification against permitlist",
"appraisal-service with id: 052335ca-7c5c-4dbc-b373-d0f7774392f6 is faithful"
],
"cb8452ac-9f7f-4212-a061-f93f3aad9281": [
"Service record quote for quote-verification-service with id: cb8452ac-9f7f-4212-a061-f93f3aad9281 is valid",
"quote-verification-service with id: cb8452ac-9f7f-4212-a061-f93f3aad9281 passed verification against permitlist",
"quote-verification-service with id: cb8452ac-9f7f-4212-a061-f93f3aad9281 is faithful"
],
"ceb6e9a3-b555-47e9-b92c-034fb6005429": [
"Service re for tee-caching-service with id: ceb6e9a3-b555-47e9-b92c-034fb6005429 is valid",
"tee-caching-service with id: ceb6e9a3-b555-47e9-b92c-034fb6005429 passed verification against permitlist",
"tee-caching-service with id: ceb6e9a3-b555-47e9-b92c-034fb6005429 is faithful"
]
}
This output includes comparisons of each faithful service against the permit list, as well as an independent verification of the microservice Intel SGX quotes. If both tests return true, the service is reported as "faithful." For an example of what happens when services do not pass verification, see Failed verification.
The Faithful Verification report retrieved from the Intel Trust Authority for verification can optionally be saved to a file using the -r flag. This report contains the full Intel SGX quotes for each microservice along with references to the "permitlist" policy requirements valid at the time of microservice registration:
./faithful-verifier verify -t token.jwt -r report.json
Sample content of the report:
{
"report": {
"service_records": {
"052335ca-7c5c-4dbc-b373-d0f7774392f6": {
"service_id": "052335ca-7c5c-4dbc-b373-d0f7774392f6",
"name": "appraisal-service",
"quote": "<SGX quote>",
"registration_date": "2023-02-02T16:19:17.6587Z",
"permitlist_version": "v0.3.0-66f6bcd",
"fmspc": "00606A000000",
"ca": "platform"
},
"cb8452ac-9f7f-4212-a061-f93f3aad9281": {
"service_id": "cb8452ac-9f7f-4212-a061-f93f3aad9281",
"name": "quote-verification-service",
"quote": "<SGX quote>",
"registration_date": "2023-02-02T16:18:10.743747Z",
"permitlist_version": "v0.3.0-66f6bcd",
"fmspc": "00606A000000",
"ca": "platform"
},
"ceb6e9a3-b555-47e9-b92c-034fb6005429": {
"service_id": "ceb6e9a3-b555-47e9-b92c-034fb6005429",
"name": "tee-caching-service",
"quote": "<SGX quote>",
"registration_date": "2023-02-02T16:18:12.925546Z",
"permitlist_version": "v0.3.0-66f6bcd",
"fmspc": "00606A000000",
"ca": "platform"
}
},
"permit_lists": [
{
"version": "v0.3.0-66f6bcd",
"measurements": {
"appraisal-service": {
"mrenclave": "A2Ew...",
"mrsigner": "Y9q...",
"semver": "v0.5.3-b3027a6-5132d8f"
},
"fv-controller": {
"mrenclave": "xh68...",
"mrsigner": "Y9qJ...",
"semver": "v0.3.2-f5161aa-29c7eed"
},
"maa-adaptor-service": {
"mrenclave": "fDT...",
"mrsigner": "Y9qJ...",
"semver": "v0.1.3-f5161aa-8b6276b"
},
"policy-provisioner": {
"mrenclave": "PESo...",
"mrsigner": "Y9qJ...",
"semver": "v0.4.2-f5161aa-8b6276b"
},
"quote-verification-service": {
"mrenclave": "Hd+9...",
"mrsigner": "Y9qJ...",
"semver": "v0.5.2-f5161aa-8b6276b"
},
"tee-caching-service": {
"mrenclave": "zLI2...",
"mrsigner": "Y9qJ...",
"semver": "v0.5.2-f5161aa-8b6276b"
}
}
}
],
"date": "2023-02-07T19:50:16.40252Z",
"nonce": "<nonce value>",
"sgx_collaterals": [
{
"collection_date": "2023-01-10T21:08:02.835329Z",
"fmspc": "00606A000000",
"ca": "platform",
"sgx_collaterals": {
"pck_crl_issuer_chain": "<pck cert info>",
"root_ca_crl": "<root ca info>",
"pck_crl": "<pck_crl>",
"tcb_info_issuer_chain": "<TCB issuer cert info>",
"tcb_info": "<TCB info>",
"qe_identify_issuer_chain": "<Quoting enclave certificate info>",
"qe_identity": "<Quoting enclave identity>"
}
}
]
},
"user_data": "<SGX user_data for the service that issues FV reports>",
"report_quote": "<SGX quote for the service that issues FV reports>"
}
Important
Some security advisories for Intel SGX require mitigation in software that cannot be reflected in the evidence contained in an SGX quote. The result of attesting an enclave subject to such a security advisory will include a SW_HARDENING_NEEDED message indicating that additional mitigation is needed to be made in software. Intel Trust Authority has implemented the applicable software mitigation required for SW_HARDENING_NEEDED security advisories listed on the Intel SGX Attestation Technical Details page.
Failed verification
When the FV tool detects services that have failed verification, output similar to the following will occur, and one or more errors are returned.
./faithful-verifier verify -t token.jwt
Successfully verified FV token audit report quote
Verification completed with non-terminal result: SW_HARDENING_NEEDED
Failed to verify service record quote for appraisal-service with id: 280c2180-518b-45bb-bd64-28f3f0ef0782, error: sgx_qv_verify_quote failed with error code: 0xe022
Failed to verify service record quote for quote-verification-service with id: c991a8bd-c4e5-4384-9010-627c6fc6b9d1, error: sgx_qv_verify_quote failed with error code: 0xe022
Failed to verify service record quote for tee-caching-service with id: 740da594-a0ec-4193-bfeb-257ab991961d, error: sgx_qv_verify_quote failed with error code: 0xe022{
"280c2180-518b-45bb-bd64-28f3f0ef0782": [
"Failed to verify service record quote for appraisal-service with id: 280c2180-518b-45bb-bd64-28f3f0ef0782, message: : sgx_qv_verify_quote failed with error code: 0xe022",
"appraisal-service with id: 280c2180-518b-45bb-bd64-28f3f0ef0782 passed verification against permitlist",
"appraisal-service with id: 280c2180-518b-45bb-bd64-28f3f0ef0782 is not faithful"
],
"740da594-a0ec-4193-bfeb-257ab991961d": [
"Failed to verify service record quote for tee-caching-service with id: 740da594-a0ec-4193-bfeb-257ab991961d, message: : sgx_qv_verify_quote failed with error code: 0xe022",
"tee-caching-service with id: 740da594-a0ec-4193-bfeb-257ab991961d passed verification against permitlist",
"tee-caching-service with id: 740da594-a0ec-4193-bfeb-257ab991961d is not faithful"
],
"c991a8bd-c4e5-4384-9010-627c6fc6b9d1": [
"Failed to verify service record quote for quote-verification-service with id: c991a8bd-c4e5-4384-9010-627c6fc6b9d1, message: : sgx_qv_verify_quote failed with error code: 0xe022",
"quote-verification-service with id: c991a8bd-c4e5-4384-9010-627c6fc6b9d1 passed verification against permitlist",
"quote-verification-service with id: c991a8bd-c4e5-4384-9010-627c6fc6b9d1 is not faithful"
]
}
FV CLI commands
Faithful Verifier CLI is used for getting and verifying TrustAuthority faithful services
Usage:
faithful-verifier [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
config Setup configuration for Faithful Verifier, saves the configuration in current user home directory as .faithful-verifier-config
help Help about any command
verify Verifies the faithful verification report
version Print the faithful verifier version
Flags:
-h, --help help for faithful-verifier
Use "faithful-verifier [command] --help" for more information about a command.
Usage:
faithful-verifier verify [flags]
Flags:
-t, --attestation-token string JWT token created by Intel Trust Authority.
-r, --export-token-audit-report string Intel Trust Authority FV Controller token audit report path to be exported (default: current directory)
-h, --help help for verify
-i, --request-id string Request id to be associated with request
-o, --results string Faithful Verifier result file path (default: current directory)
--skip-tls-verify skips verifying tls certificates when talking to Intel Trust Authority