anjuna-check-attestation

Verifies Intel® SGX attestation quotes and files attested by the quotes.

Description

The anjuna-check-attestation tool verifies that an attestation quote was generated by an Intel® SGX Secure Enclave, and can help you decide whether the attestation quote is coming from software that you trust, which is running in that enclave. The tool can also verify, via the attestation quote, that a specific object was indeed generated by that enclave. Read more about attestation quotes in the Identifying the software in Intel® SGX section of the Anjuna documentation.

Use case #1: Validating the provisioning tool output

One of the options of the Anjuna Runtime (anjuna-runtime and anjuna-sgxrun) is the --provision option, as described under Providing Secrets to the Enclave in the anjuna-sgxrun section of the Anjuna documentation.

When using this option, the user will get the public key file and the attestation quote that proves that the public key was generated in this specific enclave.

You can use the anjuna-check-attestation tool to verify that the public key is indeed coming from a trusted enclave, using the attestation quote.

Synopsis

anjuna-check-attestation --quote-file <quote-file> <public-key-file>

Returns a value that indicates whether the public key file is coming from the enclave, which is identified by the attestation quote. See more about the return values in the dedicated section of this document.

Options

-q, --quote-file <quote-file> <public-key-file>

Filename of the Intel® SGX attestation quote and the filename of a public RSA key that was generated by the enclave that generated the attestation quote.

Example

$ anjuna-check-attestation --quote-file provision/python.quote.bin provision/python.pubkey

Use case #2: Attested files

You can configure an Anjuna enclave to generate attested files for some of the files that the application writes.
For the application running in the enclave, reading and writing to the files remains the same as it was before. The difference is that when the application closes the file, the Anjuna Runtime code will prefix a header before the file content.
The file content is the actual content that the application wrote into the file.
The file header contains an attestation quote to prove that the file content was produced by this specific enclave.

Configure attested files in the manifest template as follows:

attested_files:
  - path: python3.py

Applications may specify the same file as both attested and encrypted to attest encrypted files. In this case, the cleartext content is encrypted and then attested:

attested_files:
  - path: attested-encrypted-private.bin
encrypted_files:
  - path: attested-encrypted-private.bin
  ...

With the attested file, you can use the anjuna-check-attestation tool to verify that a file comes from a specific enclave before using it.
For example: anjuna-check-attestation attested_file.txt

You can extract the content file from the attested file when you want to use the file or share it with another user or application by using the -o, --output option.

Synopsis

anjuna-check-attestation <file> [--output <output-file>]

Returns a value that indicates whether the file is coming from a trusted enclave. See more about the return values in the dedicated section of this document.

Options

-o, --output <output-file>

Filename for where to extract/write the attested content (without the attestation quote).
(If the output contains an encrypted file, you can decrypt it using the anjuna-decrypt tool.)

Examples

$ anjuna-check-attestation attested_file.txt

$ anjuna-check-attestation attested_file.txt --output file.txt

Additional parameters

The anjuna-check-attestation tool has several additional parameters available as described below, which can be used in addition to the parameters mentioned above.

--MRENCLAVE and --MRSIGNER

-e, --mrenclave <MRENCLAVE-value>
MRENCLAVE in the attestation quote must match this value.

-s, --mrsigner <MRSIGNER value>
MRSIGNER in the attestation quote must match this value.

If you know the identity of the enclave (MRSIGNER/MRENCLAVE), the anjuna-check-attestation tool accepts the expected identity of the enclave as a command line parameter, and compares it with the actual identity returned by the quote as shown in the following examples:

Examples for --MRENCLAVE and --MRSIGNER

$ anjuna-check-attestation --quote-file provision/python.quote.bin --mrenclave 3dc36a2411cf8e5da934ecbd3c207bbbf3c035be9c2f516228a1842e0de6769c --mrsigner c0566a320edb50671e19dc3f05f62d04b6d7d3e25abeda5713df5ebc0258e3ac

$ anjuna-check-attestation attested_file.txt --mrenclave 3dc36a2411cf8e5da934ecbd3c207bbbf3c035be9c2f516228a1842e0de6769c --mrsigner c0566a320edb50671e19dc3f05f62d04b6d7d3e25abeda5713df5ebc0258e3ac

If the expected identity of the enclave matches the identity of the enclave that produced the quote, the anjuna-check-attestation tool will return a successful value. Otherwise it will return an error.

-l, --log-level

-l, --log-level error | warn | info | debug | trace

Set the logging level: error, warn, info, debug, or trace.
The log level is configurable. The debug level (default) shows the essential attributes of the Intel® SGX quote. To see a full low-level dump of the quote as JSON, use --log-level=trace.
You can also set log-level: trace in your configuration file.
If the log-level parameter is not specified, or if the value is not set in the configuration file, the default log level used will be the debug log level.

Examples for --log-level

$ anjuna-check-attestation --log-level debug --quote-file provision/python.quote.bin provision/python.pubkey

$ anjuna-check-attestation --log-level debug attested_file.txt

Following is an example of logged information that is output when using the anjuna-check-attestation command:

$ anjuna-check-attestation --log-level debug --allow-debug-enclaves --quote-file provision/python.quote.bin
DEBUG Quote Structure Version: 2
DEBUG Quote Sign Type: 1
DEBUG Quote is from debug enclave: true
DEBUG Quote SPID: 0x8D7EB3671F71E409D29409EB159FA791
DEBUG Report MRSIGNER: 0xC0566A320EDB50671E19DC3F05F62D04B6D7D3E25ABEDA5713DF5EBC0258E3AC
DEBUG Report MRENCLAVE: 0x19F9EC0A0B6FCE2DDA68C7C094AB6C14421EF6CA1F11046AF4A4CACB3F4D00D3
DEBUG Report CPU SVN: 0x0809FFFFFF0200000000000000000000
DEBUG Report ISV PRODID: 12345
DEBUG Report ISV SVN: 12345
INFO Report Data: 0xF8CC4E09C5012A4604EA6438626C38DAC4CCA6A8F065855F1189F0D506F9B75E8390CD8A0B610AA85B93347BF0C7AAF970857FAC3C6A6A09978793BC7FDBCC20
DEBUG Attestation complete

By inspecting the attributes of a quote, you can assess whether to trust an application. As a convenience, optional command line parameters can be passed to simplify the validation, such as the --mrsigner and --mrenclave parameters that are described above.

-a, --allow-debug-enclaves

-a, --allow-debug-enclaves
Allow verifying attestation quotes created by enclaves running in debug mode. (Enclaves running with the --debug attribute.)

If you are experimenting with debug enclaves, set the flag --allow-debug-enclaves or add allow-debug-enclaves: true to your configuration file.

Examples for --allow-debug-enclaves

$ anjuna-check-attestation --allow-debug-enclaves --quote-file provision/python.quote.bin provision/python.pubkey

$ anjuna-check-attestation --allow-debug-enclaves attested_file.txt

Verify quotes generated on EPID and DCAP hosts

Intel® SGX Enhanced Privacy ID (EPID) and Intel® SGX Data Center Attestation Primitives (DCAP) are external services that help creating and verifying attestation quotes.

With EPID, to do this verification you need to access Intel’s attestation service. With DCAP, you can use caching services such as Intel’s or Azure’s services, or you can create your own caching server by using the Provisioning Certification Caching Service (PCCS).

EPID service

In the case where you are using an EPID service for creating and verifying attestation quotes, you need to provide the anjuna-check-attestation additional parameters as described below.

Options for EPID

--epid-server prod | dev
Use prod or dev IAS APIs to attest EPID quotes (default prod - if not specifying the --epid-server parameter).
You can also set epid-server: prod | dev in your configuration file.

--epid-api-key <EPID-API-key> API key needed to verify quotes generated on EPID hosts. You can also set epid-api-key: <EPID-API-key> in your configuration file.

Example for EPID

$ anjuna-check-attestation --epid-server dev --epid-api-key EPID_API_KEY attested_file.txt

DCAP service

In the case where you are using a DCAP service for creating and verifying attestation quotes, you need to provide the anjuna-check-attestation additional parameters as described below.

Anjuna provides three options for the DCAP attestation service:

  • Intel Provisioning Certification service (non caching)

  • Azure DCAP service

  • Local Intel PCCS service

Options for DCAP

--dcap-api intel | azure | pccs
Verify DCAP quotes using intel or azure or pccs (default intel - if not specifying the --dcap-api parameter).
You can also set dcap-api: intel | azure | pccs in your configuration file.

--dcap-api-key <DCAP-API-key>
API key needed to verify quotes generated on DCAP hosts.
You can also set dcap-api-key: <DCAP-API-key> in your configuration file.

Examples for DCAP

$ anjuna-check-attestation --dcap-api-key DCAP_API_KEY --dcap-api azure attested_file.txt

Using a local PCCS service

PCCS is a web application server written by Intel in NodeJS that caches data relevant for generating and verifying Intel® SGX attestation quotes. This could be a solution for an air-gapped environment, where you can deploy an instance of a PCCS server in your network, cache all the needed data into it, and serve the local clients. Intel provides administrative tools for downloading the needed data from Intel servers and uploading this data to the local PCCS server. This cached data is signed by an Intel rooted certificate.

This Intel® SGX guide provides information on how to set up PCCS. It is possible that a newer version is available.

The options below describe how you can connect to a PCCS service from the anjuna-check-attestation tool to verify an attestation quote.

These are additional parameters when you are using the --dcap-api pccs option:

Options for PCCS

--pccs-ca-cert <PEM-certificate-file>
PEM certificate(s) file used as root of trust to verify a PCCS server’s TLS certs.
This is the CA certificate file for verifying the TLS certificate used by the PCCS server (optional). You can omit this if the server is using certs generated by a well-known CA.
You can set pccs-ca-cert: <PEM-certificate-file> in your configuration file.

--pccs-url <DCAP-quote>
This is the URL of the PCCS server. If you set it up locally and use the defaults, the URL will be https://localhost:8081.
You can set pccs-url: <DCAP-quote> in your configuration file.

Example for PCCS

$ anjuna-check-attestation --dcap-api pccs --pccs-ca-cert PEM_CERT_FILE --pccs-url PCCS_QUOTE attested_file.txt

Additional parameter for EPID and DCAP hosts

-n, --local-checks-only

Perform all checks that can be done locally without accessing external servers. If --local-checks-only is specified, all remote configuration options for EPID or DCAP will be ignored.

Examples for --local-checks-only

$ anjuna-check-attestation --local-checks-only --quote-file provision/python.quote.bin provision/python.pubkey

$ anjuna-check-attestation --local-checks-only attested_file.txt

Configuration file

Most of the above command line options can, alternatively, be specified in a configuration file:

$HOME/.anjuna/check-attestation/conf.yaml

or

/etc/anjuna/check-attestation/conf.yaml

In the configuration file, use the long-form flag names without leading dashes as shown in the example below.
If both configuration files exist, only the configuration file located in the HOME directory will be referenced.
When an option is specified both on the command line and in the configuration file, the command line option takes precedence.

Example config file:

# Values: error, warn, info, debug, or trace (default "debug")
log-level: debug

# Allows validation of non-secure DEBUG enclaves. (default: false)
# Should be 'false' in production
allow-debug-enclaves: true

# Putting API keys here in a config file is preferable to giving
# them on the command line.
epid-api-key: API_KEY_GOES_HERE

# If you are verifying quotes generated on Flexible Launch Control
# (FLC) hosts running the Intel® SGX DCAP driver:
dcap-api-key: API_KEY_GOES_HERE

# CA certificate file for verifying the TLS certificate used by the PCCS server (optional).
pccs-ca-cert: PEM_CERT_FILE

# URL of the PCCS server.
pccs-url: DCAP-QUOTE

Exit status

  • 0 on success

  • 1 if the quote failed to verify

  • 128 if the quote otherwise verified but can’t be fully trusted because configuration is needed on the generating host to secure it; having hyper-threading enabled is a common reason for this error

  • 129 if the quote otherwise verified but can’t be fully trusted because the TCB level of the generating host has known vulnerabilities; check to see if microcode or BIOS updates are available

  • 130 if the quote otherwise verified but the TCB level of the generating host has known vulnerabilities and also needs configuration to secure it (DCAP only, EPID quotes will report 129)