Azure::Security::Attestation::AttestationClient Class Reference

#include <attestation_client.hpp>

Public Member Functions
virtual	~AttestationClient ()=default
	Destructor. More...
	AttestationClient (AttestationClient const &attestationClient)=default
	Construct a new Attestation Client object from an existing attestation client. More...
std::string const	Endpoint () const
Response< Models::OpenIdMetadata >	GetOpenIdMetadata (Azure::Core::Context const &context=Azure::Core::Context::ApplicationContext) const
Response< Models::TokenValidationCertificateResult >	GetTokenValidationCertificates (Azure::Core::Context const &context=Azure::Core::Context{}) const
	Retrieve the attestation signing certificates for this attestation instance. More...
Response< Models::AttestationToken< Models::AttestationResult > >	AttestSgxEnclave (std::vector< uint8_t > const &sgxQuoteToAttest, AttestSgxEnclaveOptions options=AttestSgxEnclaveOptions{}, Azure::Core::Context const &context=Azure::Core::Context{}) const
	Attest an SGX enclave, returning an attestation token representing the result of the attestation operation. More...
Response< Models::AttestationToken< Models::AttestationResult > >	AttestOpenEnclave (std::vector< uint8_t > const &openEnclaveReportToAttest, AttestOpenEnclaveOptions options=AttestOpenEnclaveOptions{}, Azure::Core::Context const &context=Azure::Core::Context{}) const
	Attest an OpenEnclave report, returning an attestation token representing the result of the attestation operation. More...
Response< Models::TpmAttestationResult >	AttestTpm (AttestTpmOptions const &options, Azure::Core::Context const &context=Azure::Core::Context{}) const
	Perform a single leg. More...

Static Public Member Functions
static AttestationClient	Create (std::string const &endpoint, std::shared_ptr< Core::Credentials::TokenCredential const > credential, AttestationClientOptions const &options=AttestationClientOptions{}, Azure::Core::Context const &constext=Azure::Core::Context{})
	Construct a new Attestation Client object. More...
static AttestationClient	Create (std::string const &endpoint, AttestationClientOptions options=AttestationClientOptions{}, Azure::Core::Context const &constext=Azure::Core::Context{})
	Construct a new anonymous Attestation Client object. More...

Detailed Description

The AttestationAsyncClient implements the functionality required by the "Attest" family of APIs.

An enclave (or Trusted Execution Environment) is a chunk of code that is isolated from the host (think: "encrypted VM" or "encrypted container"). But there's one key attribute of the enclave: It is encrypted.That means that if data is sent from the enclave, there is no way of knowing that the data came from the enclave. And even worse, there is no way of securely communicating with the enclave (since the enclave is fully isolated from the host, all information passed into the enclave has to go through its host first).

To solve the communication problem, the Attest API can be used to facilitate what is known as the "Secure Key Release" (SKR) protocol.

There are 4 parties involved in an attestation operation:

• The host (which hosts the enclave)
• The enclave (which is the enclave :) - encrypted, nobody can see what goes on inside it),
• The "verifier" which verifies the evidence from the enclave (this is the attestation service) and generates a token which can be received by a relying party, and
• The "relying party" which will interpret the token from the service. For the Secure Key Release Protocol, this is the entity which wishes to communicate with the enclave.

It's possible that all these parties are on the same computer, it's possible they're on multiple computers.
It's possible that the host is also the relying party. It's possible that the relying party is a component like Azure Managed HSM.

There are three primary pieces of data received by the service for the Attest family of APIs. All of them are arrays of bytes, and all of them originate from code running in the enclave (thus they need to be treated as opaque arrays of bytes by the SDK):

1. Evidence. For Intel SGX enclaves, this has two forms, either an SGX 'Quote' or an OpenEnclave 'Report'. It is required for attestation operations.
2. InitTimeData - This is data which is specified at Initialization Time. It is optional (and not currently supported on all enclave types in Azure)
3. RunTimeData - this is data which is specified at the time the quote is generated (at "runtime"). It is optional, but required for the Secure Key Release protocol.

The Evidence is cryptographically signed by a known authority (for Intel SGX Quotes or OpenEnclave reports, this is a key owned by Intel which represents that the SGX enclave is valid and can be trusted).
The core idea for all attestation operations is to take advantage of a region within the Evidence which is controlled by enclave. For SGX Enclaves, this is the 64 bytes of "user data" contained within SGX quote.

For the Secure Key Release protocol, code inside the enclave generates an asymmetric key and serializes the public key into a byte buffer. It then calculates the SHA256 hash of the serialized key and creates a quote containing that SHA256 hash. We now have a cryptographically validated indication that the contents of the byte buffer was known inside the enclave.

The enclave then hands the byte buffer and the quote to its host. The host sends the quote and byte buffer as the "RunTime Data" to the via the AttestationClient.AttestSgxEnclave or AttestationClient.AttestOpenEnclave} API. Assuming the byte buffer and quote are valid, and the quote contains the hash of the byte buffer, the attestation service responds with an AttestationToken signed by the attestation service, whose body is an AttestationResult.

The token generated also includes the contents of the InitTimeData and/or RunTimeData if it was provided in the Attest API call.

The host then sends the token to the relying party. The relying party verifies the token and verifies the claims within the token indicate that the enclave is the correct enclave. It then takes the key from the token and uses it to encrypt the data to be sent to the enclave and sends that back to the host, which passes it into the enclave.

That completes the secure key release protocol.

When the Attestation Token is generated by the attestation service, as mentioned, it contains the InitTime and RunTime data.

There are two possible representations for RunTime Data in the attestation token, depending on the requirements of the relying party:
The first is as JSON formatted data. That can be convenient if the relying party expects to receive its public key as a JSON Web Key The second is as a binary blob of data. That is needed if either the data sent by the enclave isn't a JSON object - for instance, if the RunTime data contained an asymmetric key which is formatted as a PEM encoded key, it should be interpreted as a binary blob

If you ask for the RunTime data to be included in the token as binary, then it will be base64url encoded in the "x-ms-maa-enclavehelddata" claim in the output token (the AttestationResult::EnclaveHeldData property).

If you ask for the RunTime data to be included in the token as JSON, then it will be included in the "x-ms-maa-runtimeClaims" claim in the output token (the AttestationResult::RunTimeClaims property).

In addition to the Attest APIs, the AttestationClient object also contains helper APIs which can be used to retrieve the OpenId Metadata document and signing keys from the service.

The OpenId Metadata document contains properties which describe the attestation service.

The Attestation Signing Keys describe the keys which will be used to sign tokens generated by the attestation service. All tokens emitted by the attestation service will be signed by one of the certificates listed in the attestation signing keys.

Constructor & Destructor Documentation

~AttestationClient()

virtual Azure::Security::Attestation::AttestationClient::~AttestationClient ( )

virtualdefault

AttestationClient()

Azure::Security::Attestation::AttestationClient::AttestationClient ( AttestationClient const &  attestationClient )

default

Parameters

attestationClient

An existing attestation client.

Member Function Documentation

AttestOpenEnclave()

Azure::Response< AttestationToken< AttestationResult > > AttestationClient::AttestOpenEnclave	(	std::vector< uint8_t > const &	openEnclaveReportToAttest,
		AttestOpenEnclaveOptions	options = AttestOpenEnclaveOptions{},
		Azure::Core::Context const &	context = Azure::Core::Context{}
	)		const

Parameters

openEnclaveReportToAttest	- OpenEnclave Report to be validated by the attestation service.
options	- Options to the attestation request (runtime data, inittime data, etc).
context	- Context for the operation.

Returns

Response<AttestationToken<AttestationResult>> - The result of the attestation operation

AttestSgxEnclave()

Azure::Response< AttestationToken< AttestationResult > > AttestationClient::AttestSgxEnclave	(	std::vector< uint8_t > const &	sgxQuoteToAttest,
		AttestSgxEnclaveOptions	options = AttestSgxEnclaveOptions{},
		Azure::Core::Context const &	context = Azure::Core::Context{}
	)		const

Parameters

sgxQuoteToAttest	- SGX Quote to be validated by the attestation service.
options	- Options to the attestation request (runtime data, inittime data, etc).
context	- Context for the operation.

Returns

Response<AttestationToken<AttestationResult>> - The result of the attestation operation.

AttestTpm()

Azure::Response< TpmAttestationResult > AttestationClient::AttestTpm	(	AttestTpmOptions const &	options,
		Azure::Core::Context const &	context = Azure::Core::Context{}
	)		const

Processes attestation evidence from a VBS enclave, producing an attestation result.

The TPM attestation protocol is defined here

Unlike OpenEnclave reports and SGX enclave quotes, TPM attestation is implemented using JSON encoded strings.

The client formats a string serialized JSON request to the service, which responds with a JSON response. The serialized JSON object exchange continues until the service responds with a JSON string with a property named

"report" 

, whose value will be an attestation result token.

Parameters

options

sent to the service for Trusted Platform Module (TPM) attestation.

Returns

attestation response for Trusted Platform Module (TPM) attestation.

Create() [1/2]

Azure::Security::Attestation::AttestationClient AttestationClient::Create ( std::string const &  endpoint, AttestationClientOptions  options = AttestationClientOptions{}, Azure::Core::Context const &  context = Azure::Core::Context{}  )

static

Constructs a new anonymous (unauthenticated) attestation client. Follows the factory pattern in C++ Core Guidelines C.50

Parameters

endpoint	The URL address where the client will send the requests to.
options	The options to customize the client behavior.

Returns

The newly created attestation client.

Note

TPM attestation requires an authenticated attestation client.

Parameters

endpoint	The URL address where the client will send the requests to.
options	The options to customize the client behavior.

Note

TPM attestation requires an authenticated attestation client.

Create() [2/2]

Azure::Security::Attestation::AttestationClient AttestationClient::Create ( std::string const &  endpoint, std::shared_ptr< Core::Credentials::TokenCredential const >  credential, AttestationClientOptions const &  options = AttestationClientOptions{}, Azure::Core::Context const &  context = Azure::Core::Context{}  )

static

Constructs a new attestation client. Follows the factory pattern in C++ Core Guidelines C.50

Parameters

endpoint	The URL address where the client will send the requests to.
credential	The authentication method to use (required for TPM attestation). If the credential parameter is not supplied, the connection will be unauthenticated.
options	The options to customize the client behavior.

Returns

The newly created client.

Parameters

endpoint	The URL address where the client will send the requests to.
credential	The authentication method to use (required for TPM attestation).
options	The options to customize the client behavior.

GetOpenIdMetadata()

Azure::Response< OpenIdMetadata > AttestationClient::GetOpenIdMetadata

(

Azure::Core::Context const &

context = Azure::Core::Context::ApplicationContext

)

const

Retrieves metadata about the attestation signing keys in use by the attestation service.

Retrieve the OpenID metadata for this attestation service instance..

Returns

an Models::AttestationOpenIdMetadata object containing metadata about the specified service instance.

GetTokenValidationCertificates()

Azure::Response< TokenValidationCertificateResult > AttestationClient::GetTokenValidationCertificates

(

Azure::Core::Context const &

context = Azure::Core::Context{}

)

const

Returns

A Models::AttestationSigningCertificateResult containing a list of certificates one of which will be used to validate tokens received by the attestation service.

---

The documentation for this class was generated from the following files:

• inc/azure/attestation/attestation_client.hpp
• src/attestation_client.cpp