AttestationAdministrationClient Class

Reference

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

The AttestationAdministrationClient object implements the policy management and policy certificate management functions.

If the signing_key and signing_certificate parameters are provided, they will be applied to the following APIs:

Note

The signing_key and signing_certificate parameters are a pair. If one

is present, the other must also be provided. In addition, the public key

in the signing_key and the public key in the signing_certificate must

match to ensure that the signing_certificate can be used to validate an

object signed by signing_key.

Tip

The validate_token, validation_callback, validate_signature,

validate_expiration, validate_not_before_time, validate_issuer, and

issuer keyword arguments are default values applied to each API call within

the AttestationAdministrationClient class. These values can be

overridden on individual API calls as needed.

For additional client creation configuration options, please see Python Request Options.

Inheritance: builtins.object

AttestationAdministrationClient

Constructor

AttestationAdministrationClient(endpoint: str, credential: TokenCredential, **kwargs: Any)

Parameters

Name	Description
endpoint Required	str The attestation instance base URI, for example https://mytenant.attest.azure.net.
credential Required	TokenCredential Credentials for the caller used to interact with the service.

Keyword-Only Parameters

Name	Description
signing_key	str PEM encoded signing key to be used for all operations.
signing_certificate	str PEM encoded X.509 certificate to be used for all operations.
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Methods

add_policy_management_certificate	Adds a new policy management certificate to the set of policy management certificates for the instance. The <xref:azure.security.attestation.AttestationPolicyCertificatesResult> 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
get_policy	Retrieves the attestation policy for a specified attestation type. Note The Azure Attestation Policy language is defined here
get_policy_management_certificates	Retrieves the set of policy management certificates for the instance. The list of policy management certificates will only have values if the attestation service instance is in Isolated mode.
remove_policy_management_certificate	Removes a policy management certificate from the set of policy management certificates for the instance. The AttestationPolicyCertificateResult 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	Resets the attestation policy for the specified attestation type to the default value. 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	Sets the attestation policy for the specified attestation type. 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.

add_policy_management_certificate

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

The <xref:azure.security.attestation.AttestationPolicyCertificatesResult> 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.

add_policy_management_certificate(*args: str, **kwargs: Any) -> Tuple[AttestationPolicyCertificateResult, AttestationToken]

Parameters

Name	Description
certificate_to_add Required	str Required. PEM encoded X.509 certificate to add to the list of attestation policy management certificates.

Keyword-Only Parameters

Name	Description
signing_key	str PEM encoded signing Key representing the key associated with one of the existing attestation signing certificates.
signing_certificate	str PEM encoded signing certificate which is one of the existing attestation signing certificates.
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Returns

Type	Description
Tuple[AttestationPolicyCertificateResult, AttestationToken]	AttestationPolicyCertificateResult object describing the status of the add request and the token sent from the service which contained the response.

Examples

Adding a policy management certificate.


   new_key = create_rsa_key()
   new_certificate = create_x509_certificate(new_key, u"NewCertificateName")

   # Add the new certificate to the list. Specify a validation slack of
   # 1.0 to test passing in validation parameters to this method.
   add_result, _ = admin_client.add_policy_management_certificate(
       new_certificate,
       signing_key=self.isolated_key,
       signing_certificate=self.isolated_certificate,
       validation_slack=1.0,
   )
   if add_result.certificate_resolution != CertificateModification.IS_PRESENT:
       raise Exception("Certificate was not added!")

close

close() -> None

Keyword-Only Parameters

Name	Description
signing_key	str PEM encoded signing Key representing the key associated with one of the existing attestation signing certificates.
signing_certificate	str PEM encoded signing certificate which is one of the existing attestation signing certificates.
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

get_policy

Retrieves the attestation policy for a specified attestation type.

Note

The Azure Attestation Policy language is defined here

get_policy(attestation_type: str | AttestationType, **kwargs: Any) -> Tuple[str, AttestationToken]

Parameters

Name	Description
attestation_type Required	Union[str, AttestationType] AttestationType for which to retrieve the policy.

Keyword-Only Parameters

Name	Description
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Returns

Type	Description
Tuple[str, AttestationToken]	A tuple containing the attestation policy and the token returned by the service..

Exceptions

Type	Description
AttestationTokenValidationException	Raised when an attestation token is invalid.

Examples

Getting the current policy document.


   with AttestationAdministrationClient(
       os.environ.get("ATTESTATION_AAD_URL"), DefaultAzureCredential()
   ) as admin_client:
       policy, _ = admin_client.get_policy(AttestationType.SGX_ENCLAVE)
       print("Current instance SGX Policy is: ", policy)

get_policy_management_certificates

Retrieves the set of policy management certificates for the instance.

The list of policy management certificates will only have values if the attestation service instance is in Isolated mode.

get_policy_management_certificates(**kwargs: Any) -> Tuple[List[List[str]], AttestationToken]

Keyword-Only Parameters

Name	Description
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. If the token is invalid, the validation_callback function should throw an exception to cause the API call to fail.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Returns

Type	Description
Tuple[List[List[str]], AttestationToken]	A tuple containing the list of PEM encoded X.509 certificate chains and an attestation token.

Examples

Retrieving the policy management certificates.


   print("Get the policy management certificates for a isolated instance.")

   endpoint = os.environ.get("ATTESTATION_ISOLATED_URL")
   with AttestationAdministrationClient(
       endpoint, DefaultAzureCredential()
   ) as admin_client:
       certificates, _ = admin_client.get_policy_management_certificates(
           validation_slack=1.0
       )
       print("Isolated instance has", len(certificates), "certificates")

       # An Isolated attestation instance should have at least one signing
       # certificate which is configured when the instance is created.
       #
       # Note that the certificate list returned is an array of certificate chains.
       for cert_chain in certificates:
           print("Certificate chain has ", len(cert_chain), " elements.")
           i = 1
           for cert in cert_chain:
               # load_pem_x509_certifcate takes a bytes, not str, so convert.
               certificate = load_pem_x509_certificate(cert.encode("ascii"))
               print("    Certificate", i, "subject:", certificate.subject)
               i += 1

remove_policy_management_certificate

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

The AttestationPolicyCertificateResult response to the remove_policy_management_certificate API contains two attributes of interest.

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.

remove_policy_management_certificate(*args: str, **kwargs: Any) -> Tuple[AttestationPolicyCertificateResult, AttestationToken]

Parameters

Name	Description
certificate_to_remove Required	str Required. PEM encoded X.509 certificate to remove from the list of attestation policy management certificates.

Keyword-Only Parameters

Name	Description
signing_key	str PEM encoded signing Key representing the key associated with one of the existing attestation signing certificates.
signing_certificate	str PEM encoded signing certificate which is one of the existing attestation signing certificates.
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Returns

Type	Description
Tuple[AttestationPolicyCertificateResult, AttestationToken]	Result describing the outcome of the certificate removal.

Examples

Removing a policy management certificate.


   with AttestationAdministrationClient(
       endpoint, DefaultAzureCredential()
   ) as admin_client:
       # Now remove the certificate we just added.
       print("Remove the newly added certificate.")
       remove_result, _ = admin_client.remove_policy_management_certificate(
           new_certificate,
           signing_key=self.isolated_key,
           signing_certificate=self.isolated_certificate,
       )

       if (
           remove_result.certificate_resolution
           != CertificateModification.IS_ABSENT
       ):
           raise Exception("Certificate was not removed!")

reset_policy

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

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.

reset_policy(attestation_type: str | AttestationType, **kwargs: Dict[str, Any]) -> Tuple[AttestationPolicyResult, AttestationToken]

Parameters

Name	Description
attestation_type Required	Union[str, AttestationType] AttestationType for which to set the policy.

Keyword-Only Parameters

Name	Description
signing_key	str PEM encoded signing key to be used to sign the policy before sending it to the service.
signing_certificate	str PEM encoded X.509 certificate to be sent to the service along with the policy.
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Returns

Type	Description
Tuple[AttestationPolicyResult, AttestationToken]	A policy set result reflecting the outcome of the policy removal and the token which contained the result.

Exceptions

Type	Description
AttestationTokenValidationException	Raised when an attestation token is invalid.

Examples

Resetting an AAD mode attestation instance.


   print("Set Secured Policy on an Isolated mode attestation instance.")
   # < Load the PEM encoded isolated signing certificate and  key >
   with AttestationAdministrationClient(
       os.environ.get("ATTESTATION_ISOLATED_URL"), DefaultAzureCredential()
   ) as admin_client:
       set_result, _ = admin_client.reset_policy(
           AttestationType.SGX_ENCLAVE,
           signing_key=isolated_key,
           signing_certificate=isolated_certificate,
       )
       print("Policy Set Resolution: ", set_result.policy_resolution)

set_policy

Sets the attestation policy for the specified attestation type.

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: str | AttestationType, attestation_policy: str, **kwargs: Any) -> Tuple[AttestationPolicyResult, AttestationToken]

Parameters

Name	Description
attestation_type Required	Union[str, AttestationType] AttestationType for which to set the policy.
attestation_policy Required	str Attestation policy to be set.

Keyword-Only Parameters

Name	Description
signing_key	str PEM encoded signing key to be used to sign the policy before sending it to the service.
signing_certificate	str PEM encoded X.509 certificate to be sent to the service along with the policy.
validate_token	bool If True, validate the token, otherwise return the token unvalidated.
validation_callback	Callable[[AttestationToken, AttestationSigner], None] Function callback to allow clients to perform custom validation of the token. if the token is invalid, the validation_callback function should throw an exception.
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.
validation_slack	float Slack time for validation - tolerance applied to help account for clock drift between the issuer and the current machine.
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.

Returns

Type	Description
Tuple[AttestationPolicyResult, AttestationToken]	Result of set policy operation.

Exceptions

Type	Description
AttestationTokenValidationException	Raised when an attestation token is invalid.

Examples

Setting the attestation policy with hash verification.


           from cryptography.hazmat.primitives import hashes

           write_banner("set_policy_aad_secured")
           print("Set Secured Policy on an AAD mode attestation instance.")
           with AttestationAdministrationClient(
               os.environ.get("ATTESTATION_AAD_URL"), DefaultAzureCredential()
           ) as admin_client:
               # Create an RSA Key and wrap an X.509 certificate around
               # the public key for that certificate.
               rsa_key = create_rsa_key()
               cert = create_x509_certificate(rsa_key, u"TestCertificate")

               # Set a minimal policy.
               policy_to_set = """
   version= 1.0;
   authorizationrules{=> permit();};
   issuancerules {};
   """
               set_result, _ = admin_client.set_policy(
                   AttestationType.SGX_ENCLAVE,
                   policy_to_set,
                   signing_key=rsa_key,
                   signing_certificate=cert,
               )
               print("Policy Set Resolution: ", set_result.policy_resolution)
               print("Resulting policy signer should match the input certificate:")
               print("Policy Signer: ", set_result.policy_signer.certificates[0])
               print("Certificate:   ", cert)

               # Create an Attestation Token object representing the
               # attestation policy.
               expected_policy = AttestationPolicyToken(
                   policy_to_set, signing_key=rsa_key, signing_certificate=cert
               )

               # Generate the Sha256 hash of the attestation token.
               hasher = hashes.Hash(hashes.SHA256(), backend=default_backend())
               hasher.update(expected_policy.to_jwt_string().encode("utf-8"))
               expected_hash = hasher.finalize()

               print("Expected hash should match returned hash.")
               print("Expected hash: ", expected_hash)
               print("Returned hash: ", set_result.policy_token_hash)

AttestationAdministrationClient Class

Constructor

Parameters

Keyword-Only Parameters

Methods

add_policy_management_certificate

Parameters

Keyword-Only Parameters

Returns

Examples

close

Keyword-Only Parameters

get_policy

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

get_policy_management_certificates

Keyword-Only Parameters

Returns

Examples

remove_policy_management_certificate

Parameters

Keyword-Only Parameters

Returns

Examples

reset_policy

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

set_policy

Parameters

Keyword-Only Parameters

Returns

Exceptions

Examples

Feedback

Additional resources