azure.security.attestation package

exception azure.security.attestation.AttestationTokenValidationException(message)[source]

Thrown when an attestation token validation fails.

Parameters

message (str) – Message for caller describing the reason for the failure.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
class azure.security.attestation.AttestationClient(credential: TokenCredential, instance_url: str, **kwargs: Any)[source]
An AttestationClient object enables access to the Attestation family of APIs provided

by the attestation service.

Parameters

  • instance_url (str) – base url of the service

  • credential (TokenCredential) – Credentials for the caller used to interact with the service.

Keyword Arguments

  • pipeline (Pipeline) – If omitted, the standard pipeline is used.

  • policies (list[HTTPPolicy]) – If omitted, the standard pipeline is used.

  • transport (HttpTransport) – If omitted, the standard pipeline is used.

For additional client creation configuration options, please see https://aka.ms/azsdk/python/options.

attest_open_enclave(report: bytes, inittime_data: Optional[azure.security.attestation._models.AttestationData] = None, runtime_data: Optional[azure.security.attestation._models.AttestationData] = None, **kwargs: Dict[str, Any]) → azure.security.attestation._models.AttestationResponse[azure.security.attestation._models.AttestationResult][source]

Attests the validity of an Open Enclave report.

Parameters
Keyword Arguments

draft_policy (str) – “draft” or “experimental” policy to be used with this attestation request. If this parameter is provided, then this policy document will be used for the attestation request. This allows a caller to test various policy documents against actual data before applying the policy document via the set_policy API.

Returns

Attestation service response encapsulating an AttestationResult.

Return type

azure.security.attestation.AttestationResponse[azure.security.attestation.AttestationResult]

Example: Simple OpenEnclave attestation.

Attesting an open_enclave report for an SGX enclave.
print()
print('Attest Open enclave using ', self.shared_url)
with self._create_client(self.shared_url) as attest_client:
    response = attest_client.attest_open_enclave(
        oe_report, runtime_data=AttestationData(runtime_data))

    print("Issuer of token is: ", response.value.issuer)

Example: Simple OpenEnclave attestation with draft attestation policy.

Attesting using a draft attestation policy.
draft_policy="""
version= 1.0;
authorizationrules
{
    [ type=="x-ms-sgx-is-debuggable", value==false ] &&
    [ type=="x-ms-sgx-product-id", value==1 ] &&
    [ type=="x-ms-sgx-svn", value>= 0 ] &&
    [ type=="x-ms-sgx-mrsigner", value=="2c1a44952ae8207135c6c29b75b8c029372ee94b677e15c20bd42340f10d41aa"]
        => permit();
};
issuancerules {
    c:[type=="x-ms-sgx-mrsigner"] => issue(type="My-MrSigner", value=c.value);
};
"""
print('Attest Open enclave using ', self.shared_url)
print('Using draft policy:', draft_policy)
with self._create_client(self.shared_url) as attest_client:
    response = attest_client.attest_open_enclave(
        oe_report, runtime_data=AttestationData(runtime_data, is_json=False),
        draft_policy=draft_policy)

    print("Token algorithm", response.token.algorithm)
    print("Issuer of token is: ", response.value.issuer)

Note

Note that if the draft_policy parameter is provided, the resulting attestation token will be an unsecured attestation token.

For additional request configuration options, please see Python Request Options.

attest_sgx_enclave(quote: bytes, inittime_data: Optional[azure.security.attestation._models.AttestationData] = None, runtime_data: Optional[azure.security.attestation._models.AttestationData] = None, **kwargs: Dict[str, Any]) → azure.security.attestation._models.AttestationResponse[azure.security.attestation._models.AttestationResult][source]

Attests the validity of an SGX quote.

Parameters
Keyword Arguments

draft_policy (str) – “draft” or “experimental” policy to be used with this attestation request. If this parameter is provided, then this policy document will be used for the attestation request. This allows a caller to test various policy documents against actual data before applying the policy document via the set_policy API

Returns

Attestation service response encapsulating an AttestationResult.

Return type

azure.security.attestation.AttestationResponse[azure.security.attestation.AttestationResult]

Note

Note that if the draft_policy parameter is provided, the resulting attestation token will be an unsecured attestation token.

Example:

Attesting an SGX Enclave
print()
print('Attest SGX enclave using ', self.shared_url)
with self._create_client(self.shared_url) as attest_client:
    response = attest_client.attest_sgx_enclave(
        quote, runtime_data=AttestationData(runtime_data, is_json=False))

    print("Issuer of token is: ", response.value.issuer)

For additional request configuration options, please see Python Request Options.

attest_tpm(request: azure.security.attestation._models.TpmAttestationRequest, **kwargs: Any) → azure.security.attestation._models.TpmAttestationResponse[source]

Attest a TPM based enclave.

See the TPM Attestation Protocol Reference for more information.

Parameters

request (azure.security.attestation.TpmAttestationRequest) – Incoming request to send to the TPM attestation service.

Returns

A structure containing the response from the TPM attestation.

Return type

azure.security.attestation.TpmAttestationResponse

close() → None[source]
get_openidmetadata(**kwargs: Dict[str, Any]) → Any[source]

Retrieves the OpenID metadata configuration document for this attestation instance.

Returns

OpenID metadata configuration

Return type

Any

get_signing_certificates(**kwargs: Any) → list[AttestationSigner][source]

Returns the set of signing certificates used to sign attestation tokens.

Returns

A list of azure.security.attestation.AttestationSigner objects.

Return type

list[azure.security.attestation.AttestationSigner]

For additional request configuration options, please see Python Request Options.

class azure.security.attestation.AttestationAdministrationClient(credential: TokenCredential, instance_url: str, **kwargs: Any)[source]

Provides administrative APIs for managing an instance of the Attestation Service.

Parameters

  • instance_url (str) – base url of the service

  • credential (TokenCredential) – Credentials for the caller used to interact with the service.

Keyword Arguments

  • pipeline (Pipeline) – If omitted, the standard pipeline is used.

  • transport (HttpTransport) – If omitted, the standard pipeline is used.

  • policies (list[HTTPPolicy]) – If omitted, the standard pipeline is used.

add_policy_management_certificate(certificate_to_add: bytes, signing_key: azure.security.attestation._models.AttestationSigningKey, **kwargs: Any) → azure.security.attestation._models.AttestationResponse[azure.security.attestation._models.PolicyCertificatesModificationResult][source]

Adds a new policy management certificate to the set of policy management certificates for the instance.

Parameters

  • certificate_to_add (bytes) – DER encoded X.509 certificate to add to the list of attestation policy management certificates.

  • signing_key (azure.security.attestation.AttestationSigningKey) – Signing Key representing one of the existing attestation signing certificates.

Returns

Attestation service response encapsulating the status of the add request.

Return type

azure.security.attestation.AttestationResponse[azure.security.attestation.PolicyCertificatesModificationResult]

The PolicyCertificatesModificationResult response to the add_policy_management_certificate() API contains two attributes of interest.

The first is certificate_resolution, which indicates whether the certificate in question is present in the set of policy management certificates after the operation has completed, or if it is absent.

The second is the thumbprint of the certificate added. The thumbprint for the certificate is the SHA1 hash of the DER encoding of the certificate.

close() → None[source]
get_policy(attestation_type, **kwargs)[source]

Retrieves the attestation policy for a specified attestation type.

Parameters

attestation_type (azure.security.attestation.AttestationType) – azure.security.attestation.AttestationType for which to retrieve the policy.

Returns

Attestation service response encapsulating a string attestation policy.

Return type

azure.security.attestation.AttestationResponse[str]

Raises

azure.security.attestation.AttestationTokenValidationException – Raised when an attestation token is invalid.

get_policy_management_certificates(**kwargs: Any) → AttestationResponse[list[list[bytes]]][source]

Retrieves the set of policy management certificates for the instance.

The list of policy management certificates will only be non-empty if the attestation service instance is in Isolated mode.

Returns

Attestation service response encapsulating a list of DER encoded X.509 certificate chains.

Return type

azure.security.attestation.AttestationResponse[list[list[bytes]]]

remove_policy_management_certificate(certificate_to_add: bytes, signing_key: azure.security.attestation._models.AttestationSigningKey, **kwargs: Any) → azure.security.attestation._models.AttestationResponse[azure.security.attestation._models.PolicyCertificatesModificationResult][source]

Removes a new policy management certificate to the set of policy management certificates for the instance.

Parameters

  • certificate_to_add (bytes) – DER encoded X.509 certificate to add to the list of attestation policy management certificates.

  • signing_key (azure.security.attestation.AttestationSigningKey) – Signing Key representing one of the existing attestation signing certificates.

Returns

Attestation service response encapsulating a list of DER encoded X.509 certificate chains.

Return type

azure.security.attestation.AttestationResponse[azure.security.attestation.PolicyCertificatesModificationResult]

The PolicyCertificatesModificationResult response to the remove_policy_management_certificate() API contains two attributes of interest.

The first is certificate_resolution, which indicates whether the certificate in question is present in the set of policy management certificates after the operation has completed, or if it is absent.

The second is the thumbprint of the certificate added. The thumbprint for the certificate is the SHA1 hash of the DER encoding of the certificate.

reset_policy(attestation_type: AttestationType, signing_key: Optional[AttestationSigningKey] = None, **kwargs: dict[str, Any]) → AttestationResponse[PolicyResult][source]

Resets the attestation policy for the specified attestation type to the default value.

Parameters
Returns

Attestation service response encapsulating a PolicyResult.

Return type

azure.security.attestation.AttestationResponse[azure.security.attestation.PolicyResult]

Raises

azure.security.attestation.AttestationTokenValidationException – Raised when an attestation token is invalid.

Note

If the attestation instance is in Isolated mode, then the signing_key parameter MUST be a signing key containing one of the certificates returned by get_policy_management_certificates().

If the attestation instance is in AAD mode, then the signing_key parameter does not need to be provided.

set_policy(attestation_type: azure.security.attestation._generated.models._azure_attestation_rest_client_enums.AttestationType, attestation_policy: str, signing_key: Optional[azure.security.attestation._models.AttestationSigningKey] = None, **kwargs: Any) → azure.security.attestation._models.AttestationResponse[azure.security.attestation._models.PolicyResult][source]

Sets the attestation policy for the specified attestation type.

Parameters
Returns

Attestation service response encapsulating a PolicyResult.

Return type

azure.security.attestation.AttestationResponse[azure.security.attestation.PolicyResult]

Raises

azure.security.attestation.AttestationTokenValidationException – Raised when an attestation token is invalid.

Note

If the attestation instance is in Isolated mode, then the signing_key parameter MUST be a signing key containing one of the certificates returned by get_policy_management_certificates().

If the attestation instance is in AAD mode, then the signing_key parameter does not need to be provided.

class azure.security.attestation.AttestationType[source]

An enumeration.

OPEN_ENCLAVE = 'OpenEnclave'

OpenEnclave extensions to SGX.

SGX_ENCLAVE = 'SgxEnclave'

Intel Software Guard eXtensions.

TPM = 'Tpm'

Edge TPM Virtualization Based Security.

class azure.security.attestation.AttestationToken(**kwargs)[source]

Represents a token returned from the attestation service.

Keyword Arguments

  • body (Any) – The body of the newly created token, if provided.

  • signer (azure.security.attestation.AttestationSigningKey) – If specified, the key used to sign the token. If the signer property is not specified, the token created is unsecured.

  • token (str) – If no body or signer is provided, the string representation of the token.

  • body_type (Type) – The underlying type of the body of the ‘token’ parameter, used to deserialize the underlying body when parsing the token.

get_body() → T[source]

Returns the body of the attestation token as an object.

Return type

T

serialize() → str[source]

Returns a string serializing the JSON Web Token

Return type

str

validate_token(options: TokenValidationOptions = None, signers: list[AttestationSigner] = None) → bool[source]
Validate the attestation token based on the options specified in the

TokenValidationOptions.

Parameters
Return bool

Returns True if the token successfully validated, False otherwise.

Raises

azure.security.attestation.AttestationTokenValidationException

property algorithm

Json Web Token Header “alg”.

See RFC 7515 Section 4.1.1 for details.

If the value of algorithm is “none” it indicates that the token is unsecured.

property certificate_sha256_thumbprint

The “thumbprint” of the certificate used to sign the request generated using the SHA256 algorithm.

RFC 7515 Section 4.1.8 for details.

property certificate_thumbprint

The “thumbprint” of the certificate used to sign the request.

RFC 7515 Section 4.1.7 for details.

property content_type

Json Web Token Header “content type”.

See RFC 7515 Section 4.1.10 for details.

property critical

Json Web Token Header “Critical”.

See RFC 7515 Section 4.1.11 for details.

property expiration_time

Expiration time for the token.

property issuance_time

Time when the token was issued.

property issuer

Json Web Token “iss” claim.

RFC 7519 Section 4.1.1 for details.

property key_id

Json Web Token Header “kid”.

See RFC 7515 Section 4.1.4 for details.

property key_url

Json Web Token Header “Key URL”.

See RFC 7515 Section 4.1.2 for details.

property not_before_time

Time before which the token is invalid.

property type

Json Web Token Header “typ”.

RFC 7515 Section 4.1.9 for details.

property x509_certificate_chain

An array of Base64 encoded X.509 certificates which represent a certificate chain used to sign the token.

See RFC 7515 Section 4.1.6 for details.

property x509_url

Json Web Token Header “X509 URL”.

See RFC 7515 Section 4.1.5 for details.

class azure.security.attestation.AttestationSigner(certificates: list[bytes], key_id: str, **kwargs: Any)[source]

Represents a signing certificate returned by the Attestation Service.

Parameters

  • certificates (list[bytes]) – A list of Base64 encoded X.509 Certificates representing an X.509 certificate chain. The first of these certificates will be used to sign an AttestationToken.

  • key_id (str) – A string which identifies a signing key, See RFC 7517 Section 4.5

class azure.security.attestation.AttestationResponse(token, value)[source]

Represents a response from the attestation service.

Parameters
class azure.security.attestation.AttestationResult(**kwargs: Dict[str, Any])[source]

An AttestationResult represents the claims returned from the attestation service as a result of a call to azure.security.attestation.AttestationClient.attest_sgx(), or AttestationClient.attest_open_enclave().

Keyword Arguments

  • issuer (str) – Entity which issued the attestation token.

  • confirmation (dict) – Confirmation claim for the token.

  • unique_identifier (str) – Unique identifier for the token.

  • nonce (str) – Returns the input nonce attribute passed to the attest API.

  • version (str) – Version of the token. Must be “1.0”

  • runtime_claims (dict) – Runtime claims passed in from the caller of the attest API.

  • inittime_claims (dict) – Inittime claims passed in from the caller of the attest API.

  • enclave_held_data (bytes) – Runtime data passed in from the caller of the attest API.

  • policy_claims (dict) – Attestation claims issued by policies.

  • verifier_type (str) – Verifier which generated this token.

  • policy_signer (azure.security.attestation.AttestationSigner) – If the policy which processed the request is signed, this will be the certificate which signed the policy.

  • policy_hash (str) – The hash of the policy which processed the attestation evidence.

  • is_debuggable (bool) – True if the SGX enclave being attested is debuggable.

  • product_id (int) – Product ID for the SGX enclave being attested.

  • mr_enclave (str) – MRENCLAVE value for the SGX enclave being attested.

  • mr_signer (str) – MRSIGNER value for the SGX enclave being attested.

  • svn (int) – Security version number for the SGX enclave being attested.

  • sgx_collateral (dict) – Collateral which identifies the collateral used to create the token.

property confirmation

Returns the confirmation claim for the attestation token.

If present, the confirmation property can be used to identify a proof of possession of a key.

See RFC 7800 Section 3.1 for details.

Return type

str or None

property enclave_held_data

Returns the value of the runtime_data field specified as an input to the azure.security.attestation.AttestationClient.attest_sgx() or azure.security.attestation.AttestationClient.attest_open_enclave() API.

Note

The enclave_held_data prperty will only be populated if the runtime_data parameter to the Attest API is marked as not being JSON.

Return type

bytes or None

property inittime_claims

Returns the inittime claims in the token.

This value will match the input inittime_data property to the azure.security.attestation.AttestationClient.attest_sgx() or azure.security.attestation.AttestationClient.attest_open_enclave() API.

Return type

dict[str, Any] or None

Note

The inittime_claims property will only be populated if the inittime_data parameter to the Attest API is marked as being JSON.

property is_debuggable

Returns “True” if the source evidence being attested indicates that the TEE has debugging enabled.

Return type

bool or None

property issuer

Returns the issuer of the attestation token.

The issuer for the token MUST be the same as the instance_uri associated with the azure.security.attestation.AttestationClient object. If it is not, then the token should be rejected.

See RFC 7519 Section 4.1.1 for details.

Return type

str or None

property mr_enclave

Returns HEX encoded mr-enclave value of the SGX enclave being attested.

Return type

str or None

property mr_signer

Returns HEX encoded mr-signer value of the SGX enclave being attested.

Return type

str or None

property nonce

Returns the value of the “nonce” input to the attestation request.

Return type

str or None

property policy_claims

Returns the claims for the token generated by attestation policy.

Return type

dict[str, Any] or None

property policy_hash

Returns the base64url encoded SHA256 hash of the Base64Url encoded attestation policy which was applied when generating this token.

Return type

str or None

property policy_signer

Returns the signing certificate which was used to sign the policy which was applied when the token was generated.

Return type

azure.security.attestation.AttestationSigner or None

property product_id

Returns the product id associated with the SGX enclave being attested.

Return type

float or None

property runtime_claims

Returns the runtime claims in the token.

This value will match the input runtime_data property to the azure.security.attestation.AttestationClient.attest_sgx() or azure.security.attestation.AttestationClient.attest_open_enclave() API.

Return type

dict[str, Any] or None

Note

The runtime_claims property will only be populated if the runtime_data parameter to the Attest API is marked as being JSON.

property sgx_collateral

Returns a set of information describing the complete set of inputs to the oe_verify_evidence

Return type

dict[str, Any] or None

property svn

Returns the svn value of the SGX enclave being attested.

Return type

int or None

property unique_id

Returns a unique ID claim for the attestation token.

If present, the unique_id property can be used to distinguish between different attestation tokens.

See RFC 7519 Section 4.1.7 for details.

Return type

str or None

property verifier_type

Returns the verifier which generated this attestation token.

Return type

str or None

property version

Returns the version of the information returned in the token.

Return type

str or None

class azure.security.attestation.AttestationData(data: bytes, is_json: Optional[bool] = None)[source]

AttestationData represents an object passed as an input to the Attestation Service.

AttestationData comes in two forms: Binary and JSON. To distinguish between the two, when an AttestationData object is created, the caller provides an indication that the input binary data will be treated as either JSON or Binary.

If the is_json parameter is not provided, then the AttestationData constructor will probe the data parameter to determine whether the data should be treated as JSON.

The AttestationData is reflected in the generated AttestationResult in two possible ways. If the AttestationData is Binary, then the AttestationData is reflected in the AttestationResult.enclave_held_data claim. If the AttestationData is JSON, then the AttestationData is expressed as JSON in the AttestationResult.runtime_claims or AttestationResult.inittime_claims claim.

Parameters

  • data (bytes) – Input data to be sent to the attestation service.

  • is_json (bool) – True if the attestation service should treat the input data as JSON.

class azure.security.attestation.TokenValidationOptions(**kwargs: Any)[source]

Validation options for an Attestation Token object.

Keyword Arguments

  • validate_token (bool) – if True, validate the token, otherwise return the token unvalidated.

  • validation_callback (Callable[[AttestationToken, AttestationSigner], bool]) – Callback to allow clients to perform custom validation of the token.

  • validate_signature (bool) – if True, validate the signature of the token being validated.

  • validate_expiration (bool) – If True, validate the expiration time of the token being validated.

  • issuer (str) – Expected issuer, used if validate_issuer is true.

  • validate_issuer (bool) – If True, validate that the issuer of the token matches the expected issuer.

  • validate_not_before_time (bool) – If true, validate the “Not Before” time in the token.

class azure.security.attestation.StoredAttestationPolicy(policy: str)[source]

Represents an attestation policy in storage.

When serialized, the StoredAttestationPolicy object will Base64Url encode the UTF-8 representation of the policy value.

Parameters

policy (str) – Policy to be saved.

serialize(**kwargs: Any) → str[source]
class azure.security.attestation.PolicyResult(policy_resolution: azure.security.attestation._generated.models._azure_attestation_rest_client_enums.PolicyModification, policy_signer: azure.security.attestation._generated.models._models_py3.JSONWebKey, policy_token_hash: str)[source]

PolicyResult represents the result of a azure.security.attestation.AttestationAdministrationClient.set_policy() or azure.security.attestation.AttestationAdministrationClient.reset_policy() API call.

The PolicyResult class is returned as the body of an attestation token from the attestation service. It can be used to ensure that the attestation service received the policy object sent from the client without alteration.

Parameters
class azure.security.attestation.CertificateModification[source]

The result of the operation

IS_ABSENT = 'IsAbsent'

After the operation was performed, the certificate is no longer present in the set of certificates.

IS_PRESENT = 'IsPresent'

After the operation was performed, the certificate is in the set of certificates.

class azure.security.attestation.AttestationSigningKey(signing_key_der: bytes, certificate_der: bytes)[source]

Represents a signing key used by the attestation service.

Typically the signing key used by the service consists of two components: An RSA or ECDS private key and an X.509 Certificate wrapped around the public key portion of the private key.

Parameters

  • signing_key_der (bytes) – The RSA or ECDS signing key to sign the token supplied to the customer DER encoded.

  • certificate_der (bytes) – A DER encoded X.509 Certificate whose public key matches the signing_key’s public key.

class azure.security.attestation.TpmAttestationRequest(data)[source]

Represents a request for TPM attestation.

Parameters

data (bytes) – The data sent to the Attestation Service in the parameter to azure.security.attestation.AttestationClient.attest_tpm().

class azure.security.attestation.TpmAttestationResponse(data)[source]

Represents a request for TPM attestation.

Parameters

data (bytes) – The data received from the Attestation Service in response to a call to azure.security.attestation.AttestationClient.attest_tpm().

class azure.security.attestation.PolicyModification[source]

The result of the operation

REMOVED = 'Removed'

The specified policy object was removed.

UPDATED = 'Updated'

The specified policy object was updated.

class azure.security.attestation.PolicyCertificatesModificationResult(certificate_thumbprint: str, certificate_resolution: azure.security.attestation._generated.models._azure_attestation_rest_client_enums.CertificateModification)[source]

The result of a policy certificate modification.

Parameters

  • certificate_thumbprint (str) – Hex encoded SHA1 Hash of the binary representation certificate which was added or removed.

  • certificate_resolution (str or CertificateModification) – The result of the operation. Possible values include: “IsPresent”, “IsAbsent”.

Subpackages