anjuna-check-attestation

Verifies Intel SGX® attestation quotes.

SYNOPSIS

    anjuna-check-attestation OPTIONS...

DESCRIPTION

anjuna-check-attestation validates that a trusted enclave generated a given attestation quote. An attestation quote is a certificate signed by an enclave which attests to the attributes of the platform and the identity of the executed application. It also contains a Report Data field that enables an application to attest to a wide range of statements.

Use this tool in the following cases:

To establish trust with a remote enclave before provisioning secrets to the application (keys, credentials, data).
To verify whether some output was generated by a trusted application executed in an enclave.

The log level is configurable. The default level (debug) shows the essential attributes of the SGX quote. To see a full low-level dump of the quote as JSON, use --log-level=trace or set log-level: trace in your configuration file.

If you are experimenting with enclaves that have the DEBUG attribute set (not for production of course!), you’ll want to set the flag --allow-debug-enclaves or place allow-debug-enclaves: true in your configuration file.

Unfortunately, Intel’s APIs for DCAP and EPID quotes use separate API keys. You’ll need one or both keys usually in your configutation file. dcap-api-key: … if you will be verifying quotes generated on Flexible Launch Control (FLC) hosts running the Intel DCAP SGX driver or epid-api-key: … if not using the DCAP driver.

    $ 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, a client can assess whether an application should be trusted. As a convenience, optional command line parameters can be passed to simplify the validation.

For example, if the client knows 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. The following example shows how :

$ anjuna-check-attestation --quote-file provision/python.quote.bin --mrsigner <expected mrsigner> --mrenclave <expected mrenclave>

If the expected identity of the enclave does not match the identity of the enclave that produced the quote, the anjuna-check-attestation tool returns an error to indicate that the enclave should not be trusted.

The anjuna-check-attestation tool has built-in support for the RSA key produced during provisioning using the --rsa-key-file flag. The SHA512 hash of the RSA key (after conversion to its binary DER format) is taken and compared with the report data of an enclave quote file. If attestation succeeds, a genuine enclave created the key and only this specific enclave can access the matching private key. Files can be encrypted for the enclave using the verified RSA public key and no other enclave can decrypt the data.

OPTIONS

  -a, --allow-debug-enclaves   Don't fail quotes created by enclaves with the DEBUG attribute
      --dcap-api-key string    API key needed to verify quotes generated on DCAP hosts
      --epid-api-key string    API key needed to verify quotes generated on EPID hosts
  -l, --log-level string       Set logging level: trace, debug, info, warn, error (default "debug")
  -e, --mrenclave string       MRENCLAVE in the quote must match this value if given
  -s, --mrsigner string        MRSIGNER in the quote must match this value if given
  -n, --no-ias                 Dry run without connecting to Intel servers
  -q, --quote-file string      Filename with SGX quote inside it
  -r, --report-data string     Hex string to compare with report data in quote
  -k, --rsa-key-file string    Filename of public RSA key (PEM) being attested

CONFIGURATION FILE

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

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

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

The keynames in the configuration file are the long-form flag names used on the command line, but without leading dashes. When an option is specified both on the command line and in the config file, the command line value takes precendence.

Example config file:

 # Values: trace, debug, info, warn, or error (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

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 know vulnerabilities and also needs configuration to secure it (DCAP only, EPID quotes will report 129)

When anjuna-check-attestation returns an error, the enclave that produced the attestation quote should not be trusted.

EXAMPLE

To check whether it is safe to provision an enclave that produced the file provision/python.quote.bin by using the public RSA key provision/python.pubkey, run the following command:

$ {TOOL_ATTEST} --debug --quote-file provision/python.quote.bin --rsa-key-file provision/python.pubkey

DCAP CERTIFICATE CACHE

Using the Intel® SGX DCAP (Data Center Attestation Primitive) driver gives the ability to verify quotes without constant access to the internet by setting up a certificate caching service. Multiple solutions provide a certificate caching service for DCAP, including setting up a locally managed certificate caching service.

The Anjuna SGX Runtime installer installs the package az-dcap-client provided by Azure. It creates a local certificate cache service based on Azure’s certificate cache service. The certificates obtained by az-dcap-client are valid for 24 hours, meaning that an internet connection must be present every 24 hours.