Package: azure-security-attestation
Azure Attestation client library for PythonThe 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(tm) Software Guard Extensions (SGX) enclaves and Virtualization-based Security (VBS) enclaves.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).This package has been tested with Python 2.7, 3.6 to 3.9.For a more complete view of Azure libraries, see theAzure SDK for Python release page.Source code|Package (PyPI)|API reference documentation|Product documentationGetting startedPrerequisitesAn Azure subscription.  To use Azure services, including the Azure Attestation service, you'll need a subscription.  If you do not have an existing Azure account, you may sign up for afree trialor use yourVisual Studio Subscriptionbenefits when youcreate 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 orAzure CLI.Install the packageInstall the Azure Attestation client library for Python withPyPI:pipinstallazure-security-attestationAuthenticate the clientIn order to interact with the Azure Attestation service, you'll need to create an instance of theAttestation ClientorAttestation Administration Clientclass. You need anattestation endpoint, which you may see as "Attest URI" in the portal,
andclient credentials (client id, client secret, tenant id)to instantiate a client object.Client secret credentialauthentication is being used in this getting started section but you can find more ways to authenticate with theAzure identity package. To use theDefaultAzureCredentialprovider shown below,
or other credential providers provided with the Azure SDK, you should install the azure-identity package:pipinstallazure-identityCreate/Get credentialsUse theAzure CLIsnippet below to create/get client secret credentials.Create a service principal and configure its access to Azure resources:azadspcreate-for-rbac-n<your-application-name>--skip-assignmentOutput:{"appId":"generated-app-ID","displayName":"dummy-app-name","name":"http://dummy-app-name","password":"random-password","tenant":"tenant-ID"}Take note of the service principal objectIdazadspshow--id<appId>--queryobjectIdOutput:"<your-service-principal-object-id>"Use the returned credentials above to setAZURE_CLIENT_ID(appId),AZURE_CLIENT_SECRET(password), andAZURE_TENANT_ID(tenant) environment variables. The following example shows a way to do this in Powershell:$Env:AZURE_CLIENT_ID="generated-app-ID"$Env:AZURE_CLIENT_SECRET="random-password"$Env:AZURE_TENANT_ID="tenant-ID"For more information about the Azure Identity APIs and how to use them, seeAzure Identity client libraryKey conceptsThere are four major families of functionality provided in this preview SDK:SGX and TPM enclave attestation.MAA Attestation Token signing certificate discovery and validation.Attestation Policy management.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 to
provide 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 Azure Attestation service is available supports a "shared" instance, which
can 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.AttestationSGX or TPM attestation is the process of validating evidence collected from
a 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 validationOne 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 aJSON 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, then
the certificate issued by the server can be verified using theoe_verify_attestation_certificate API.Policy ManagementEach attestation service instance has a policy applied to it which defines additional criteria which the customer has defined.For more information on attestation policies, seeAttestation PolicyPolicy Management certificate managementWhen an attestation instance is running in "Isolated" mode, the customer who created the instance will have provided
a policy management certificate at the time the instance is created. All policy modification operations require that the customer sign
the policy data with one of the existing policy management certificates. The Policy Management Certificate Management APIs enable
clients to "roll" the policy management certificates.Isolated Mode and AAD ModeEach 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.AttestationTypeThe 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 OpenEnclaveoe_get_reportoroe_get_evidenceAPI.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 DataRuntimeData refers to data which is presented to the Intel SGX Quote generation logic or theoe_get_report/oe_get_evidenceAPIs. If the caller to the attest API provided aruntime_dataattribute, The Azure Attestation service will validate that the first 32 bytes of thereport_datafield in the SGX Quote/OE Report/OE Evidence matches the SHA256 hash of theruntime_data.InitTime data refers to data which is used to configure the SGX enclave being attested.Note that InitTime data is not supported on AzureDCsv2-Seriesvirtual machines.Additional conceptsExamplesCreate an attestation client instanceAttest an SGX enclaveGet attestation policyRetrieve token validation certificatesCreate an attestation client instanceCreate client instanceCreates an instance of the Attestation Client at uriendpoint.attest_client=AttestationClient(endpoint=base_uri,credential=DefaultAzureCredential())Get attestation policyTheset_policymethod retrieves the attestation policy from the service.
Attestation Policies are instanced on a per-attestation type basis, theAttestationTypeparameter defines the type to retrieve.policy,token=attest_client.get_policy(AttestationType.SGX_ENCLAVE)print('Instance SGX policy: ',policy)print('Token: ',token)Set an attestation policy for a specified attestation typeIf the attestation service instance is running in Isolated mode, the set_policy 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 aJSON Web Tokenbased on the policy document and signing information which is sent to the attestation service.policy_set_response=attest_client.set_policy(AttestationType.SGX_ENCLAVE,attestation_policy,signing_key=key,signing_certificate=signing_certificate)new_policy,_=attest_client.get_policy(AttestationType.SGX_ENCLAVE)# `new_policy` will equal `attestation_policy`.If the service instance is running in AAD mode, the call to set_policy can be
simplified:policy_set_response=attest_client.set_policy(AttestationType.SGX_ENCLAVE,attestation_policy)# Now retrieve the policy which was just set.new_policy,_=attest_client.get_policy(AttestationType.SGX_ENCLAVE)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 thePolicyResultthat can be used to verify that the service received the policy document:policy_signer- if theset_policycall included a signing certificate, this will be the certificate provided at the time of theset_policycall. If no policy signer was set, this will be null.policy_token_hash- this is the hash of theJSON Web Tokensent to the service.To verify the hash, clients can generate an attestation policy token and verify the hash generated from that token:fromcryptography.hazmat.primitivesimporthashesexpected_policy=AttestationPolicyToken(attestation_policy,signing_key=key,signing_certificate=signing_certificate)hasher=hashes.Hash(hashes.SHA256())hasher.update(expected_policy.serialize().encode('utf-8'))expected_hash=hasher.finalize()# `expected_hash` will exactly match `policy_set_response.policy_token_hash`Attest SGX EnclaveUse theattest_sgx_enclavemethod to attest an SGX enclave.One of the core challenges customers have interacting with encrypted environments is how to ensure that you can securely 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 secure 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 theoe_get_evidenceoroe_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 existingAttestationClientobject which is configured with the base URI for your endpoint. It also assumes that you have an SGX Quote (quote) generated from within the SGX enclave you are attesting, and "Runtime Data" (runtime_data) which is referenced in the SGX Quote.response,token=attest_client.attest_sgx_enclave(quote,runtime_data=runtime_data)At this point, the enclave_held_data attribute in the attestationResult
will hold the input binary runtime_data.The token is now passed to the "relying party". The relying party will
validate that the token was issued by the Attestation Service. It then
extracts the asymmetric key from the EnclaveHeldData field. The relying
party will then Encrypt its "key" data using the asymmetric key and
transmits it back to the enclave.encrypted_data=send_token_to_relying_party(attestationResult.Token)Now the encrypted data can be passed into the enclave which can decrypt that data.Additional information on how to perform attestation token validation can be found in theMAA Service Attestation Sample.Retrieve Token CertificatesUseget_signing_certificatesto retrieve the certificates which can be used to validate the token returned from the attestation service.signers=attest_client.get_signing_certificates()forsignerinsigners:fromcryptography.hazmat.backendsimportdefault_backendcert=cryptography.x509.load_pem_x509_certificate(signer.certificates[0].encode('ascii'),backend=default_backend())print('Cert  iss:',cert.issuer,'; subject:',cert.subject)TroubleshootingMost Attestation service operations will raise exceptions defined inAzure Core. The attestation service APIs will throw aHttpResponseErroron failure with helpful error codes. Many of these errors are recoverable.try:response,_=attest_client.attest_sgx_enclave(quote,runtime_data=AttestationData(runtime_data,is_json=False))exceptHttpResponseErrorasex:# Ignore invalid quote errors.ifex.error=="InvalidParameter":pass}Additional troubleshooting information for the MAA service can be foundhereNext stepsFor more information about the Microsoft Azure Attestation service, please see ourdocumentation page.ContributingThis 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, visitthe 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 theMicrosoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contactopencode@microsoft.comwith any additional questions or comments.SeeCONTRIBUTING.mdfor details on building, testing, and contributing to these libraries.Provide FeedbackIf you encounter any bugs or have suggestions, please file an issue in theIssuessection of the project.Release History1.0.0 (2021-07-06)Features AddedSample cleanup - instead of usingClientSecretCredentials, the samples now use
DefaultAzureCredential.Breaking ChangesTPM attestation takes a JSON string parameter and returns a JSON string parameter.TPMAttestationRequestandTPMAttestationResponsetype were removed.confirmationattribute removed fromAttestationResulttype.TheAttestationSigningKeytype was removed, replaced with asigning_keyandsigning_certificatekwargs parameter.All certificates and keys accepted and returned by the SDK are now PEM encoded
strings instead of DER encoded arrays of bytes for easier manipulation and
interoperability.RemovedAttestationResponsetype, token value merged intoAttestationResult,PolicyResult, etc.RemovedTokenValidationOptionstype and merged the validation options into
keyword arguments on the APIs which validate returned tokens. Those keyword
arguments can also be specified on the Client classes to simplify individual
API invocations.Renamedinstance_urlparameter to the constructors toendpoint.Many optional fields inAttestationResultwere made non-optional.AttestationToken._validate_tokenis made internal-only, and now returnsNone.The caller providedvalidation_callbacknow must throw exceptions on invalid
tokens rather than returningFalse.Removed theAttestationDatatype, instead theattest_xxxAPIs take two sets
of parameters:inittime_dataandinittime_jsonandruntime_dataandruntime_json.
if the_jsonvalue is set, the value of the parameter is an array of UTF8 encoded
JSON values, if the_datavalue is set, the value of the parameter is an array
of bytes.Theget_policyAPI now returns aTuple[str, AttestationToken]to simplify
the consumption experience.Theget_policy_management_certificatesAPI also returns aTuple[list[list[string]], AttestationToken]to simplify the consumption experience. Note that each of the entries
in the list is a PEM encoded X.509 certificate.To call into the attest APIs if you care about the attestation policy and token,
you can write:policy,token=attest_client.get_policy(AttestationType.SGX_ENCLAVE)If you only care about the policy, you can write any of the following:policy,_=attest_client.get_policy(AttestationType.SGX_ENCLAVE)orpolicy=attest_client.get_policy(AttestationType.SGX_ENCLAVE)[0]orresponse=attest_client.get_policy(AttestationType.SGX_ENCLAVE)policy=response[0]TheAttestationTokenclass no longer inherits fromGeneric.Theattest_sgx_enclave, andattest_openenclaveAPIs now return a tuple ofAttestationResult,AttestationToken, similar to theget_policyAPI.Theset_policy,reset_policy,add_policy_management_certificate, andremove_policy_management_certificateAPIs all return a tuple.TheAttestationToken.get_body()API was renamedAttestationToken.body()Several time related properties were renamed to be consistent with the usage from
keyvault:Theexpiration_timeproperty onAttestationTokenwas renamed toexpires.Theissuance_timeproperty onAttestationTokenwas renamed toissued_on.Thenot_before_timeproperty onAttestationTokenwas renamed tonot_before.TheStoredAttestationPolicymodel type has been removed. To validate the attestation policy hash, use theAttestationPolicyTokenmodel object instead.Theget_openidmetadataAPI has been renamedget_open_id_metadata.1.0.0b4 (2021-06-08)Features AddedAdded reset_policy API.Added models.Documentation cleanup.Breaking ChangesCreating theStoredAttestationPolicymodel type means that theattestation_policykwargs parameter for the constructor has been replaced with a positionalpolicyparameter. As a result of this change, this code:StoredAttestationPolicy(attestation_policy=str(attestation_policy).encode('utf-8')))changes to:StoredAttestationPolicy(attestation_policy)Several parameters for theAttestationResulttype have been renamed, and
several parameters which were shared withAttestationTokenhave been
removed. In general, the naming changes removed some protocol specific
elements and replaced them with friendlier names. Finally, the deprecated
attributes have been removed from theAttestationResultFull set of changes:issrenamed toissuercnfrenamed toconfirmationjtirenamed tounique_identifieriatremovedexpremovednbfremoveddeprecated_versionremoveddeprecated_is_debuggableremoveddeprecated_sgx_collateralremoveddeprecated_enclave_held_dataremoveddeprecated_enclave_held_data2removeddeprecated_product_idremoveddeprecated_mr_enclaveremoveddeprecated_mr_signerremoveddeprecated_svnremoveddeprecated_teeremoveddeprecated_policy_signerremoveddeprecated_policy_hashremoveddeprecated_rp_dataremovedIf customers need to access the removed or renamed fields directly, they can
use theget_bodymethod of theAttestationResponseobject:ifresponse.token.get_body().deprecated_tee!='sgx':print("Unexpected tee claim in token")1.0.0b2 (2021-05-11)Features AddedPreliminary implementation of a Track 2 SDK for the attestation service.Breaking ChangesComplete reimplementation of the API surface, follows the API patterns already
established for the attestation service.1.0.0b1 (2021-01-15)Initial early preview release for MAA Data Plane SDK
Demonstrates use of the machine generated MAA APIs.Initial Release