-->

The Microsoft Azure Attestation (MAA) service is a unified solution for remotely verifying the trustworthiness of a platform and integrity of the binaries running inside it. The service supports attestation of the platforms backed by Trusted Platform Modules (TPMs) alongside the ability to attest to the state of Trusted Execution Environments (TEEs) such as Intel® Software Guard Extensions (SGX) enclaves and Virtualization-based Security (VBS) enclaves.

Rust SGX SDK v0.9.0 is coming up as a beta version of the future v1.0.0, with the most desired sgx::tstd as well as many new features! Then you can use this script (or run the commands one-by-one), which was tested on Ubuntu 20.04 with SGX driver/sdk version 2.10 intended for Ubuntu 18.04: Install SGX SDK + Driver #! /bin/bash UBUNTUVERSION=$ (lsbrelease -r -s cut -d '.' -f 1) if (($UBUNTUVERSION. The Intel SGX SDK is required to develop SGX enclaves and applications. It contains Intel custom libc and cryptographic libraries, each with 2 versions (debug & release). It also has tools such as sgxedger8r to generate glue code (we will discuss this in the enclave tutorial) and sgxsign to sign enclaves with development key.

Attestation is a process for demonstrating that software binaries were properly instantiated on a trusted platform. Remote relying parties can then gain confidence that only such intended software is running on trusted hardware. Azure Attestation is a unified customer-facing service and framework for attestation.

Azure Attestation enables cutting-edge security paradigms such as Azure Confidential computing and Intelligent Edge protection. Customers have been requesting the ability to independently verify the location of a machine, the posture of a virtual machine (VM) on that machine, and the environment within which enclaves are running on that VM. Azure Attestation will empower these and many additional customer requests.

Azure Attestation receives evidence from compute entities, turns them into a set of claims, validates them against configurable policies, and produces cryptographic proofs for claims-based applications (for example, relying parties and auditing authorities).

NOTE: This is a preview SDK for the Microsoft Azure Attestation service. It provides all the essential functionality to access the Azure Attestation service, it should be considered 'as-is' and is subject to changes in the future which may break compatibility with previous versions.

Source code | Package (NuGet) | API reference documentation | Product documentation

Getting started

Prerequisites

• An Azure subscription. To use Azure services, including the Microsoft Azure Attestation service, you'll need a subscription. If you do not have an existing Azure account, you may sign up for a free trial or use your Visual Studio Subscription benefits when you create an account.
• An existing Azure Attestation Instance, or you can use the 'shared provider' available in each Azure region. If you need to create an Azure Attestation service instance, you can use the Azure Portal or Azure CLI.

Install the package

Install the Microsoft Azure Attestation client library for .NET with NuGet:

Authenticate the client

In order to interact with the Microsoft Azure Attestation service, you'll need to create an instance of the Attestation Client or Attestation Administration Client class. You need a attestation instance url, which you may see as 'DNS Name' in the portal,and client secret credentials (client id, client secret, tenant id) to instantiate a client object.

Client secret credential authentication is being used in this getting started section but you can find more ways to authenticate with Azure identity. To use the DefaultAzureCredential provider shown below,or other credential providers provided with the Azure SDK, you should install the Azure.Identity package:

Create/Get credentials

Use the Azure CLI snippet below to create/get client secret credentials.

• Create a service principal and configure its access to Azure resources:

  Output:

• Take note of the service principal objectId

  Output:

• Use the returned credentials above to set AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (password), and AZURE_TENANT_ID (tenant) environment variables. The following example shows a way to do this in Powershell:

For more information about the Azure Identity APIs and how to use them, see Azure Identity client library

Key concepts

There are four major families of functionality provided in this preview SDK:

• Attestation policy management certificate management (yes, policy management management).

The Microsoft Azure Attestation service runs in two separate modes: 'Isolated' and 'AAD'. When the service is running in 'Isolated' mode, the customer needs toprovide additional information beyond their authentication credentials to verify that they are authorized to modify the state of an attestation instance.

Finally, each region in which the Microsoft Azure Attestation service is available supports a 'shared' instance, whichcan be used to attest SGX enclaves which only need verification against the azure baseline (there are no policies applied to the shared instance). TPM attestation is not available in the shared instance.While the shared instance requires AAD authentication, it does not have any RBAC policies - any customer with a valid AAD bearer token can attest using the shared instance.

Attestation

SGX or TPM attestation is the process of validating evidence collected froma trusted execution environment to ensure that it meets both the Azure baseline for that environment and customer defined policies applied to that environment.

Attestation service token signing certificate discovery and validation

One of the core operational guarantees of the Azure Attestation Service is that the service operates 'operationally out of the TCB'. In other words, there is no way that a Microsoft operator could tamper with the operation of the service, or corrupt data sent from the client. To ensure this guarantee, the core of the attestation service runs in an Intel(tm) SGX enclave.

To allow customers to verify that operations were actually performed inside the enclave, most responses from the Attestation Service are encoded in a JSON Web Token, which is signed by a key held within the attestation service's enclave.

This token will be signed by a signing certificate issued by the MAA service for the specified instance.

If the MAA service instance is running in a region where the service runs in an SGX enclave, thenthe certificate issued by the server can be verified using the oe_verify_attestation_certificate API.

The AttestationResponse object contains two main properties: Token and Value. The Token property contains the complete token returned by the attestation service, the Value property contains the body of the JSON Web Token response.

Policy Management

Each attestation service instance has a policy applied to it which defines additional criteria which the customer has defined.

For more information on attestation policies, see Attestation Policy

Policy Management certificate management

When an attestation instance is running in 'Isolated' mode, the customer who created the instance will have provideda policy management certificate at the time the instance is created. All policy modification operations require that the customer signthe policy data with one of the existing policy management certificates. The Policy Management Certificate Management APIs enableclients to 'roll' the policy management certificates.

Isolated Mode and AAD Mode

Each Microsoft Azure Attestation service instance operates in either 'AAD' mode or 'Isolated' mode. When an MAA instance is operating in AAD mode, it means that the customer which created the attestation instance allows Azure Active Directory and Azure Role Based Access control policies to verify access to the attestation instance.

AttestationType

The Microsoft Azure Attestation service supports attesting different types of evidence depending on the environment.Currently, MAA supports the following Trusted Execution environments:

• OpenEnclave - An Intel(tm) Processor running code in an SGX Enclave where the attestation evidence was collected using the OpenEnclave oe_get_report or oe_get_evidence API.
• SgxEnclave - An Intel(tm) Processor running code in an SGX Enclave where the attestation evidence was collected using the Intel SGX SDK.
• Tpm - A Virtualization Based Security environment where the Trusted Platform Module of the processor is used to provide the attestation evidence.

Runtime Data and Inittime Data

RuntimeData refers to data which is presented to the Intel SGX Quote generation logic or the oe_get_report/oe_get_evidence APIs. The Azure Attestation service will validate that the first 32 bytes of the report_data field in the SGX Quote/OE Report/OE Evidence matches the SHA256 hash of the RuntimeData.

InitTime data refers to data which is used to configure the SGX enclave being attested.

Note that InitTime data is not supported on Azure DCsv2-Series virtual machines.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options |Accessing the response |Long-running operations |Handling failures |Diagnostics |Mocking |Client lifetime

Examples

Create client instance

Creates an instance of the Attestation Client at uri endpoint.

Get attestation policy

The GetPolicy method retrieves the attestation policy from the service.Attestation Policies are instanced on a per-attestation type basis, the AttestationType parameter defines the type to retrieve.

Set an attestation policy for a specified attestation type

If the attestation service instance is running in Isolated mode, the SetPolicy API needs to provide a signing certificate (and private key) which can be used to validate that the caller is authorized to modify policy on the attestation instance. If the service instance is running in AAD mode, then the signing certificate and key are optional.

Under the covers, the SetPolicy APIs create a JSON Web Token based on the policy document and signing information which is sent to the attestation service.

Clients need to be able to verify that the attestation policy document was not modified before the policy document was received by the attestation service's enclave.

There are two properties provided in the PolicyResult that can be used to verify that the service received the policy document:

• PolicySigner - if the SetPolicy call included a signing certificate, this will be the certificate provided at the time of the SetPolicy call. If no policy signer was set, this will be null.
• PolicyTokenHash - this is the hash of the JSON Web Token sent to the service.

To verify the hash, clients can generate an attestation token and verify the hash generated from that token:

Attest SGX Enclave

Use the AttestSgxEnclave method to attest an SGX enclave.

One of the core challenges customers have interacting with encrypted environments is how to ensure that you can reliably communicate with the code running in the environment ('enclave code').

One solution to this problem is what is known as 'Secure Key Release', which is a pattern that enables this kind of communication with enclave code.

To implement the 'Secure Key Release' pattern, the enclave code generates an ephemeral asymmetric key. It then serializes the public portion of the key to some format (possibly a JSON Web Key, or PEM, or some other serialization format).

The enclave code then calculates the SHA256 value of the public key and passes it as an input to code which generates an SGX Quote (for OpenEnclave, that would be the oe_get_evidence or oe_get_report).

The client then sends the SGX quote and the serialized key to the attestation service. The attestation service will validate the quote and ensure that the hash of the key is present in the quote and will issue an 'Attestation Token'.

The client can then send that Attestation Token (which contains the serialized key) to a 3rd party 'relying party'. The relying party then validates that the attestation token was created by the attestation service, and thus the serialized key can be used to encrypt some data held by the 'relying party' to send to the service.

This example shows one common pattern of calling into the attestation service to retrieve an attestation token associated with a request.

This example assumes that you have an existing AttestationClient object which is configured with the base URI for your endpoint. It also assumes that you have an SGX Quote (binaryQuote) generated from within the SGX enclave you are attesting, and 'Runtime Data' (runtimeData) which is referenced in the SGX Quote.

Additional information on how to perform attestation token validation can be found in the MAA Service Attestation Sample.

Retrieve Token Certificates

Use GetSigningCertificatesAsync to retrieve the certificates which can be used to validate the token returned from the attestation service.

Troubleshooting

Most Attestation service operations will throw a RequestFailedException on failure with helpful ErrorCodes. Many of these errors are recoverable.

Additional troubleshooting information for the MAA service can be found here

Next steps

For more information about the Microsoft Azure Attestation service, please see our documentation page.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit the Contributor License Agreement site.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

See CONTRIBUTING.md for details on building, testing, and contributing to these libraries.

Graphene project uses SGX to securely run software. SGX isa complicated topic, which may be hard to learn, because the documentationis scattered through official/reference documentation, blogposts and academicpapers. This page is an attempt to curate a dossier of available readingmaterial.

SGX is an umbrella name of technology that comprises several parts:

• CPU/platform hardware features: the new instruction set, newmicroarchitecture with the PRM (EPC) memory region and somenew MSRs and some new logic in the MMU and so on;
• the SGX Remote Attestationinfrastructure, online services providedby Intel and/or third parties (see DCAP);
• SDK and assorted software.

SGX is still being developed. The current (March 2020) version of CPU featuresis referred to as “SGX1” or simply “SGX” and is more or less finalized. Allnew/changed instructions from original SGX are informally referred to as“SGX2”.

Features which might be considered part of SGX2:

• EDMM (Enclave Dynamic Memory Management) is part of SGX2
• FLC (Flexible Launch Control), not strictly part of SGX2, but was notpart of original SGX hardware either

As of now there is hardware support (on a limited set of CPUs) for FLC and(on an even more limited set of CPUs) SGX2/EDMM. Most of the literatureavailable (especially introduction-level) concerns original SGX1 only.

Introductory reading¶

• Quarkslab’s two-part “Overview of Intel SGX”:
• MIT’s deep dive in SGX architecture.
• Intel’s whitepapers:
  • Slides from ISCA 2015(actual slides [PDF])

Official Documentation¶

• SDK for Linux(download of both the binaries and the documentation)

Academic Research¶

• Intel’s collection of academic papers,likely the most comprehensive list of references

Installation Instructions¶

Linux kernel drivers¶

For historical reasons, there are three SGX drivers currently (January 2021):

• https://github.com/intel/linux-sgx-driver – old one, does not support DCAP,deprecated

• https://github.com/intel/SGXDataCenterAttestationPrimitives/tree/master/driver– new one, out-of-tree, supports both non-DCAP software infrastructure (withold EPID remote-attestation technique) and the new DCAP (with new ECDSA andmore “normal” PKI infrastructure).

• SGX support was upstreamed to the Linux mainline starting from 5.11.It currently supports only DCAP attestation. The driver is accessible through/dev/sgx_enclave and /dev/sgx_provision.

  The following udev rules are recommended for users to access the SGX node:

  Also it will not require IAS and kernel maintainers considernon-writable FLC MSRs as non-functional SGX:https://lore.kernel.org/lkml/20191223094614.GB16710@zn.tnic/

The chronicle of kernel patchset:

v1 (2016-04-25)

https://lore.kernel.org/lkml/1461605698-12385-1-git-send-email-jarkko.sakkinen@linux.intel.com/

v2

?

v3

?

v4 (2017-10-16)

https://lore.kernel.org/lkml/20171016191855.16964-1-jarkko.sakkinen@linux.intel.com/

v5 (2017-11-13)

https://lore.kernel.org/lkml/20171113194528.28557-1-jarkko.sakkinen@linux.intel.com/

v6 (2017-11-25)

https://lore.kernel.org/lkml/20171125193132.24321-1-jarkko.sakkinen@linux.intel.com/

v7 (2017-12-07)

https://lore.kernel.org/lkml/20171207015614.7914-1-jarkko.sakkinen@linux.intel.com/

v8 (2017-12-15)

https://lore.kernel.org/lkml/20171215202936.28226-1-jarkko.sakkinen@linux.intel.com/

v9 (2017-12-16)

https://lore.kernel.org/lkml/20171216162200.20243-1-jarkko.sakkinen@linux.intel.com/

v10 (2017-12-24)

https://lore.kernel.org/lkml/20171224195854.2291-1-jarkko.sakkinen@linux.intel.com/

v11 (2018-06-08)

https://lore.kernel.org/lkml/20180608171216.26521-1-jarkko.sakkinen@linux.intel.com/

v12 (2018-07-03)

https://lore.kernel.org/lkml/20180703182118.15024-1-jarkko.sakkinen@linux.intel.com/

v13 (2018-08-27)

https://lore.kernel.org/lkml/20180827185507.17087-1-jarkko.sakkinen@linux.intel.com/

v14 (2018-09-25)

https://lore.kernel.org/lkml/20180925130845.9962-1-jarkko.sakkinen@linux.intel.com/

v15 (2018-11-03)

https://lore.kernel.org/lkml/20181102231320.29164-1-jarkko.sakkinen@linux.intel.com/

v16 (2018-11-06)

https://lore.kernel.org/lkml/20181106134758.10572-1-jarkko.sakkinen@linux.intel.com/

v17 (2018-11-16)

https://lore.kernel.org/lkml/20181116010412.23967-2-jarkko.sakkinen@linux.intel.com/

v18 (2018-12-22)

https://lore.kernel.org/linux-sgx/20181221231134.6011-1-jarkko.sakkinen@linux.intel.com/

v19 (2019-03-20)

https://lore.kernel.org/lkml/20190320162119.4469-1-jarkko.sakkinen@linux.intel.com/

v20 (2019-04-17)

https://lore.kernel.org/lkml/20190417103938.7762-1-jarkko.sakkinen@linux.intel.com/

v21 (2019-07-13)

https://lore.kernel.org/lkml/20190713170804.2340-1-jarkko.sakkinen@linux.intel.com/

v22 (2019-09-03)

https://lore.kernel.org/lkml/20190903142655.21943-1-jarkko.sakkinen@linux.intel.com/

v23 (2019-10-28)

https://lore.kernel.org/lkml/20191028210324.12475-1-jarkko.sakkinen@linux.intel.com/

v24 (2019-11-30)

https://lore.kernel.org/lkml/20191129231326.18076-1-jarkko.sakkinen@linux.intel.com/

v25 (2020-02-04)

https://lore.kernel.org/lkml/20200204060545.31729-1-jarkko.sakkinen@linux.intel.com/

v26 (2020-02-09)

https://lore.kernel.org/lkml/20200209212609.7928-1-jarkko.sakkinen@linux.intel.com/

v27 (2020-02-23)

https://lore.kernel.org/lkml/20200223172559.6912-1-jarkko.sakkinen@linux.intel.com/

v28 (2020-04-04)

https://lore.kernel.org/lkml/20200303233609.713348-1-jarkko.sakkinen@linux.intel.com/

v29 (2020-04-22)

https://lore.kernel.org/lkml/20200421215316.56503-1-jarkko.sakkinen@linux.intel.com/

v30 (2020-05-15)

https://lore.kernel.org/lkml/20200515004410.723949-1-jarkko.sakkinen@linux.intel.com/

SGX terminology¶

Architectural Enclaves (AEs) are a set of “system” enclaves concernedwith starting and attesting other enclaves. Intel provides referenceimplementations of these enclaves, though other companies may write theirown implementations.

See also

Todo

TBD

Attestation is a mechanism to prove the trustworthiness of the SGX enclaveto a local or remote party. More specifically, SGX attestation proves thatthe enclave runs on a real hardware in an up-to-date TEE with the expectedinitial state. There are two types of the attestation:Local Attestation and Remote Attestation. For localattestation, the attesting SGX enclave collects attestation evidence inthe form of an SGX Report using the EREPORT hardware instruction.For remote attestation, the attesting SGX enclave collects attestationevidence in the form of an SGX Quote using the QuotingEnclave (and the Provisioning Enclave if required). The enclavethen may send the collected attestation evidence to the local or remoteparty, which will verify the evidence and confirm the correctness of theattesting enclave. After this, the local or remote party trusts theenclave and may establish a secure channel with the enclave and sendsecrets to it.

See also

A software infrastructure provided by Intel as a referenceimplementation for the new ECDSA/PCS-based remote attestation.Relies on the Flexible Launch Control hardware feature. Inprinciple this is a special version of SDK/PSW thathas a reference launch enclave and is backed by the DCAP-enabled SGXdriver.

This allows for launching enclaves without Intel’s remote infrastructure.But this requires deployment of own infrastructure, so is operationallymore complicated. Therefore it is intended for server environments (whereyou control all the machines).

See also

Orientation Guide

https://download.01.org/intel-sgx/dcap-1.0.1/docs/Intel_SGX_DCAP_ECDSA_Orientation.pdf

EPID

A way to launch enclaves with Intel’s infrastructure, intendedfor client machines.

Todo

TBD

Todo

short description

Contrary to DCAP, EPID may be understood as “opinionated”, with mostmoving parts fixed and tied to services provided by Intel. This isintended for client enclaves and deprecated for server environments.

See also

DCAP

A way to launch enclaves without relying on the Intel’sinfrastructure.

Hardware (CPU) feature that allows substituting Launch Enclave forone not signed by Intel. A change in SGX’s EINIT logic to not requirethe EINITTOKEN from the Intel-based Launch Enclave. An MSR, which canbe locked at boot time, keeps the hash of the public key of the“launching” entity.

With FLC, Launch Enclave can be written by other companies (otherthan Intel) and must be signed with the key corresponding to the onelocked in the MSR (a reference Launch Enclave simply allows allenclaves to run). The MSR can also stay unlocked and then it can bemodified at run-time by the VMM or the OS kernel.

Support for FLC can be detected using CPUID instruction, asCPUID.07H:ECX.SGX_LC[bit30]1 (SDM vol. 2A calls this “SGX LaunchControl”).

See also

https://software.intel.com/en-us/blogs/2018/12/09/an-update-on-3rd-party-attestation

Announcement

See also

In local attestation, the attesting SGX enclave collects attestationevidence in the form of an SGX Report using the EREPORT hardwareinstruction. This form of attestation is used to send the attestationevidence to a local party (on the same physical machine).

Internet service provided by Intel for “old” EPID-based remoteattestation. Enclaves send SGX quotes to the client/verifier who willforward them to IAS to check their validity.

See also

PCS

Provisioning Certification Service, another Internet serviceprovided by Intel.

Todo

TBD

Is There An Sgx Sdk

One of the Architectural Enclaves of the Intel SGX softwareinfrastructure. It is part of the SGX Platform Software. TheProvisioning Enclave is used in EPID based remote attestation.This enclave communicates with the Intel Provisioning Service(IPS) to perform EPID provisioning. The result of thisprovisioning procedure is the private EPID key securely accessed by theProvisioning Enclave. This procedure happens only during the firstdeployment of the SGX machine (or, in rare cases, to provision a new EPIDkey after TCB upgrade). The main user of the Provisioning Enclave is theQuoting Enclave.

See also

One of the Architectural Enclaves of the Intel SGX softwareinfrastructure. It is part of the SGX Platform Software andDCAP. The Provisioning Certification Enclave is used inDCAP based remote attestation. This enclave communicates with theIntel Provisioning Certification Service (PCS) to perform DCAPprovisioning. The result of this provisioning procedure is the DCAP/ECDSAattestation collateral (mainly the X.509 certificate chains rooted in awell-known Intel certificate and Certificate Revocation Lists). Thisprocedure happens during the first deployment of the SGX machine and thenperiodically to refresh the cached attestation collateral. Typically, toreduce the dependency on PCS, a cloud service provider introduces anintermediate caching service (Provisioning Certification Caching Service,or PCCS) that stores all the attestation collateral obtained from Intel.The main user of the Provisioning Certification Enclave is theQuoting Enclave.

New internet service provided by Intel for new ECDSA-based remoteattestation. Enclave provider creates its own internal Attestation Servicewhere it caches PKI collateral from Intel’s PCS, and the verifier gets thecertificate chain from the enclave provider to check validity.

See also

IAS

Intel Attestation Service, another Internet service.

One of the Architectural Enclaves of the Intel SGX softwareinfrastructure. It is part of the SGX Platform Software. TheQuoting Enclave receives an SGX Report and produces acorresponding SGX Quote. The identity of the Quoting Enclave ispublicly known (it signer, its measurement and its attributes) and isvetted by public companies such as Intel (in the form of the certificatechain ending in a publicly known root certificate of the company).

In remote attestation, the attesting SGX enclave collects attestationevidence in the form of an SGX Quote using the QuotingEnclave (and the Provisioning Enclave if required). This form ofattestation is used to send the attestation evidence to a remote party(not on the same physical machine).

See also

This refers to all new SGX instructions and other hardware features thatwere introduced after the release of the original SGX1.

Encompasses at least EDMM, but is still work in progress.

Todo

TBD

Is There An Sgx Sdk App

In context of SGX this has the usual meaning: the set of allcomponents that are critical to security. Any vulnerability in TCBcompromises security. Any problem outside TCB is not a vulnerability,i.e. should not compromise security.

In context of Graphene there is also a different meaning(Thread Control Block). Those two should not be confused.

Is There An Sgx Sdk File

Todo

Is There An Sgx Sdk Download

TBD