AttestationAdministrationClient Class
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.objectAttestationAdministrationClient
Constructor
AttestationAdministrationClient(endpoint: str, credential: TokenCredential, **kwargs: Any)Parameters
- endpoint
- str
The attestation instance base URI, for example https://mytenant.attest.azure.net.
- 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[azure.security.attestation._models.AttestationPolicyCertificateResult, azure.security.attestation._models.AttestationToken]Parameters
- certificate_to_add
- str
Required. PEM encoded X.509 certificate to add to the list of attestation policy management certificates.
- 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
AttestationPolicyCertificateResult object describing the status of the add request and the token sent from the service which contained the response.
Return type
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() -> Noneget_policy
Retrieves the attestation policy for a specified attestation type.
Note
The Azure Attestation Policy language is defined here
get_policy(attestation_type: Union[str, azure.security.attestation._generated.models._azure_attestation_rest_client_enums.AttestationType], **kwargs: Any) -> Tuple[str, azure.security.attestation._models.AttestationToken]Parameters
- attestation_type
- <xref:Union>[str, AttestationType]
AttestationType for which to retrieve 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
A tuple containing the attestation policy and the token returned by the service..
Return type
Exceptions
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]], azure.security.attestation._models.AttestationToken]Parameters
- 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
A tuple containing the list of PEM encoded X.509 certificate chains and an attestation token.
Return type
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 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.
remove_policy_management_certificate(*args: str, **kwargs: Any) -> Tuple[azure.security.attestation._models.AttestationPolicyCertificateResult, azure.security.attestation._models.AttestationToken]Parameters
- certificate_to_remove
- str
Required. PEM encoded X.509 certificate to remove from the list of attestation policy management certificates.
- 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
Result describing the outcome of the certificate removal.
Return type
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: Union[str, azure.security.attestation._generated.models._azure_attestation_rest_client_enums.AttestationType], **kwargs: Dict[str, Any]) -> Tuple[azure.security.attestation._models.AttestationPolicyResult, azure.security.attestation._models.AttestationToken]Parameters
- attestation_type
- <xref:Union>[str, AttestationType]
AttestationType for which to set the policy.
- 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
A policy set result reflecting the outcome of the policy removal and the token which contained the result.
Return type
Exceptions
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: Union[str, azure.security.attestation._generated.models._azure_attestation_rest_client_enums.AttestationType], attestation_policy: str, **kwargs: Any) -> Tuple[azure.security.attestation._models.AttestationPolicyResult, azure.security.attestation._models.AttestationToken]Parameters
- attestation_type
- <xref:Union>[str, AttestationType]
AttestationType for which to set the policy.
- 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
Result of set policy operation.
Return type
Exceptions
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)
Feedback
Submit and view feedback for