Contents

Tool Reference

Auditee is a small tool to assist the task of auditing an SGX enclave.

Given the following 3 pieces of data:

  • a signed enclave binary file (Enclave.signed.so),

  • the source code that was used to compile the enclave binary, and

  • an attestation verification report signed by Intel for this enclave binary

an auditor, would like to verify that the signed enclave binary can be reproduced from the source code, and more particularly that the MRENCLAVE of the signed enclave matches that of the reproduced binary, and also matches the MRENCLAVE found in the report, signed by Intel. If the MRENCLAVE is the same for all three, then an auditor can link the different observations from auditing the source code, to the signed enclave binary and to its deployment, to which the attestation report corresponds.

auditee.tool

Main module for auditee tool.

auditee.enclave.build(source_code, *, docker_build_progress=False)[source]

Build an enclave binary for the given source code.

The source code is expected to contain a file .auditee.yml, which instructs how to build the enclave. The supported builders are nix-build and docker.

Parameters

source_code (str) – Local file path to the source code where the enclave to be built is located.

Raises

IOError: – If the .auditee.yml file is not found.

Returns

File path to the enclave binary that was built.

Return type

str

auditee.enclave.sign(unsigned_enclave, enclave_config, *, signed_enclave='/tmp/enclave.signed.so', signing_key=None)[source]

Sign the given enclave.

Parameters

  • unsigned_enclave (str) – Local file path to the unsigned enclave binary.

  • enclave_config (str) – Local file path to the enclave configuration file.

  • signed_enclave (str, optional) – Local file path where the signed enclave should be written to. Defaults to /tmp/enclave.signed.so.

  • signing_key (str, optional) – Local file path to a signing key with which to sign the enclave. When signing an enclave just for test purposes, such as verifying the reproducibility of an enclave, one can fall back on the default which is a key file that is packaged with auditee.

Raises

SGXSignError – If something wrong happen when invoking the sgx_sign tool.

Returns

File path where the signed enclave was written to.

Return type

str

auditee.enclave.verify_ias_report(report, signed_enclave)[source]

Verify whether the MRENCLAVE in the given IAS report matches against the MRENCLAVE of the given signed enclave.

Parameters

  • report (str) – Local file path to the IAS report, in json format.

  • signed_enclave (str) – Path to the signed enclave file.

Returns

True if the MRENCLAVEs match, False otherwise.

Return type

bool

Examples

>>> from auditee.enclave import verify_ias_report
>>> verify_ias_report('ias_report.json', 'enclave.signed.so')
Succeed.
- Provided enclave MRENCLAVE:           b7af1907e21b4eb240d3c3c6880e3892e45af383196d7aa326c35e2a8c71ef63
- IAS report MRENCLAVE:                 b7af1907e21b4eb240d3c3c6880e3892e45af383196d7aa326c35e2a8c71ef63
MRENCLAVES match!
True
auditee.enclave.verify_mrenclave(source_code, signed_enclave, *, ias_report=None, signing_key=None, docker_build_progress=False)[source]

Given some source code, a signed enclave, and optionally, a remote attestation verification report from Intel’s attestation service (IAS), verify whether the signed enclave binary can be reproduced from the given source code, and whether the IAS report corresponds to the given signed enclave.

Parameters

  • source_code (str) – Local file path to the source code where the enclave to be built is located.

  • signed_enclave (str) – Path to the signed enclave file.

  • ias_report (str, optional) – Local file path to the IAS report, in json format.

  • signing_key (str, optional) – Local file path to a signing key with which to sign the enclave. When signing an enclave just for test purposes, such as verifying the reproducibility of an enclave, one can fall back on the default which is a key file that is packaged with auditee.

Raises

SGXSignError – If something wrong happen when invoking the sgx_sign tool.

Returns

True if the MRENCLAVEs match, False otherwise.

Return type

bool

Examples

>>> from auditee.enclave import verify_mrenclave
>>> verify_mrenclave('sgx-iot/', 'enclave.signed.so', ias_report='ias_report.json')
# ...
Reproducibility Report
----------------------
- Signed enclave MRENCLAVE:                     b7af1907e21b4eb240d3c3c6880e3892e45af383196d7aa326c35e2a8c71ef63
- Built-from-source enclave MRENCLAVE:          b7af1907e21b4eb240d3c3c6880e3892e45af383196d7aa326c35e2a8c71ef63
- IAS report MRENCLAVE:                         b7af1907e21b4eb240d3c3c6880e3892e45af383196d7aa326c35e2a8c71ef63
# ...
MRENCLAVES match!
# ...
Report data
-----------
The following REPORT DATA contained in the remote attestation verification report CAN be trusted.
6e979bd31dd119faf99a423e97563e67dc7937944347c8a98f59977b76dd55cd911a8be4420bec78116e4e51f47def30c72c631556e960378e39e3aab7ccbe08
>>> True

auditee.sgx

Wrapper around sgx_sign command. Invokes the command via subprocess.

auditee.sgx.SGX_SDK = '/opt/sgxsdk'

Directory where the Linux SGX SDK is installed.

It can be set via the environment variable SGX_SDK. Defaults to /opt/sgxsdk.

Type

str

auditee.sgx.SGX_SIGN_CMD = '/opt/sgxsdk/bin/x64/sgx_sign'

Location of the sgx_sign tool.

Defaults to /opt/sgxsdk/bin/x64/sgx_sign.

Type

str

auditee.sgx.sign(enclave, *, key, out, config)[source]

Sign the given enclave with the given key.

This function invokes the Linux SGX SDK sgx_sign tool, using Python’s subprocess module.

Attention

The SGX SDK must be installed on the system where this function is invoked.

The path to the sgx_sign tool can be set via the environment variable SGX_SDK. It defaults to /opt/sgxsdk/bin/x64/sgx_sign.

Parameters

  • enclave (str) – Local file path to the unsigned enclave binary.

  • key (str) – Local file path to a signing key with which to sign the enclave.

  • out (str) – Local file path where the signed enclave should be written to.

  • config (str) – Local file path to the enclave configuration file.

Raises

SGXSignError – If something wrong happen when invoking the sgx_sign tool.

Returns

Signed enclave bytes.

Return type

bytes

Examples

from auditee import sgx
sgx.sign('enclv.so', key='key.pem', out='enclv.sig.so', config='config.xml')

The above is equivalent to invoking the sgx_sign tool in a shell:

$ sgx_sign sign -enclave enclv.so -key key.pem -out enclv.sig.so -config config.xml

auditee.errors

Classes for auditee-specific errors.

exception auditee.errors.AuditeeError[source]

Base class for auditee errors.

exception auditee.errors.SGXSignError[source]

Error stemming from calling the sgx_sign tool.

previous

Configuration

next

Background