Merge pull request #216776 from MicrosoftDocs/release-maa-tpm-v2-ga

Release maa tpm v2 ga changes

Author: v-regandowner

articles/attestation/azure-tpm-vbs-attestation-usage.md

@@ -0,0 +1,74 @@
+---
+title: Azure TPM VBS attestation usage 
+description: Learn about how to apply TPM and VBS attestation
+services: attestation
+author: prsriva
+ms.service: attestation
+ms.topic: overview
+ms.date: 09/05/2022
+ms.author: prsriva
+ms.custom: tpm attestation
+---
+
+# Using TPM/VBS attestation 
+
+Attestation can be integrated into various applications and services, catering to different use cases. Azure Attestation service, which acts the remote attestation service can be used for desired purposes by updating the attestation policy. The policy engine works as processor, which takes the incoming payload as evidence and performs the validations as authored in the policy. This architecture simplifies the workflow and enables the service owner to purpose build solutions for the varied platforms and use cases.The workflow remains the same as described in [Azure attestation workflow](workflow.md). The attestation policy needs to be crafted as per the validations required.
+
+Attesting a platform has its own challenges with its varied components of boot and setup, one needs to rely on a hardware root-of-trust anchor which can be used to verify the first steps of the boot and extend that trust upwards into every layer on your system. A hardware TPM provides such an anchor for a remote attestation solution. Azure Attestation provides a highly scalable measured boot and runtime integrity measurement attestation solution with a revocation framework to give you full control over platform attestation.
+
+## Attestation steps
+
+Attestation Setup has two setups. One pertaining to the service setup and one pertaining to the client setup.
+
+:::image type="content" source="./media/tpm-attestation-setup.png" alt-text="A diagram that shows the different interactions for attestation." lightbox="./media/tpm-attestation-setup.png":::
+
+Detailed information about the workflow is described in [Azure attestation workflow](workflow.md). 
+
+### Service endpoint setup:
+This is the first step for any attestation to be performed. Setting up an endpoint, this can be performed either via code or using the Azure portal.
+
+Here's how you can set up an attestation endpoint using Portal
+
+1 Prerequisite: Access to the Microsoft Azure Active Directory(Azure AD) tenant and subscription under which you want to create the attestation endpoint.
+Learn more about setting up an [Azure AD tenant](../active-directory/develop/quickstart-create-new-tenant.md).
+
+2 Create an endpoint under the desired resource group, with the desired name.
+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5azcU]
+
+3 Add Attestation Contributor Role to the Identity who will be responsible to update the attestation policy.
+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5aoRj]
+
+4 Configure the endpoint with the required policy.
+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5aoRk]
+
+Sample policies can be found in the [policy section](tpm-attestation-sample-policies.md).
+
+> [!NOTE]
+> TPM endpoints are designed to be provisioned without a default attestation policy.
+
+
+### Client setup:
+A client to communicate with the attestation service endpoint needs to ensure it's following the protocol as described in the [protocol documentation](virtualization-based-security-protocol.md). Use the [Attestation Client NuGet](https://www.nuget.org/packages/Microsoft.Attestation.Client) to ease the integration.
+ 
+1 Prerequisite: An Azure AD identity is needed to access the TPM endpoint.
+Learn more [Azure AD identity tokens](../active-directory/develop/v2-overview.md).
+
+2 Add Attestation Reader Role to the identity that will be need for authentication against the endpoint. Azure i
+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5aoRi]
+
+
+## Execute the attestation workflow:
+Using the [Client](https://github.com/microsoft/Attestation-Client-Samples) to trigger an attestation flow. A successful attestation will result in an attestation report (encoded JWT token). Parsing the JWT token, the contents of the report can be easily validated against expected outcome. 
+
+> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE5azcT]
+
+
+Here's a sample of the contents of the attestation report.
+:::image type="content" source="./media/sample-decoded-token.jpg" alt-text="Sample snapshot of a decoded token for tpm attestation." lightbox="./media/sample-decoded-token.jpg":::
+
+Using the Open ID [metadata endpoint](/rest/api/attestation/metadata-configuration/get?tabs=HTTP) contains properties, which describe the attestation service.The signing keys describe the keys, which will be used to sign tokens generated by the attestation service. All tokens emitted by the attestation service will be signed by one of the certificates listed in the attestation signing keys.
+
+## Next steps
+- [Set up Azure Attestation using PowerShell](quickstart-powershell.md)
+- [Attest an SGX enclave using code samples](/samples/browse/?expanded=azure&terms=attestation)
+- [Learn more about policy](policy-reference.md)

articles/attestation/media/sample-decoded-token.jpg

@@ -1,5 +1,5 @@
 ---
-title: Examples of an Azure Attestation policy
+title: Examples of an Azure SGX Attestation policy
 description: Examples of Azure Attestation policy.
 services: attestation
 author: msmbaldwin
@@ -80,74 +80,6 @@ eyJhbGciOiJub25lIn0.eyJBdHRlc3RhdGlvblBvbGljeSI6ICJkbVZ5YzJsdmJqMGdNUzR3TzJGMWRH
 eyJhbGciOiJSU0EyNTYiLCJ4NWMiOlsiTUlJQzFqQ0NBYjZnQXdJQkFnSUlTUUdEOUVGakJcdTAwMkJZd0RRWUpLb1pJaHZjTkFRRUxCUUF3SWpFZ01CNEdBMVVFQXhNWFFYUjBaWE4wWVhScGIyNURaWEowYVdacFkyRjBaVEF3SGhjTk1qQXhNVEl6TVRneU1EVXpXaGNOTWpFeE1USXpNVGd5TURVeldqQWlNU0F3SGdZRFZRUURFeGRCZEhSbGMzUmhkR2x2YmtObGNuUnBabWxqWVhSbE1EQ0NBU0l3RFFZSktvWklodmNOQVFFQkJRQURnZ0VQQURDQ0FRb0NnZ0VCQUpyRWVNSlo3UE01VUJFbThoaUNLRGh6YVA2Y2xYdkhmd0RIUXJ5L3V0L3lHMUFuMGJ3MVU2blNvUEVtY2FyMEc1WmYxTUR4alZOdEF5QjZJWThKLzhaQUd4eFFnVVZsd1dHVmtFelpGWEJVQTdpN1B0NURWQTRWNlx1MDAyQkJnanhTZTBCWVpGYmhOcU5zdHhraUNybjYwVTYwQUU1WFx1MDAyQkE1M1JvZjFUUkNyTXNLbDRQVDRQeXAzUUtNVVlDaW9GU3d6TkFQaU8vTy9cdTAwMkJIcWJIMXprU0taUXh6bm5WUGVyYUFyMXNNWkptRHlyUU8vUFlMTHByMXFxSUY2SmJsbjZEenIzcG5uMXk0Wi9OTzJpdFBxMk5Nalx1MDAyQnE2N1FDblNXOC9xYlpuV3ZTNXh2S1F6QVR5VXFaOG1PSnNtSThUU05rLzBMMlBpeS9NQnlpeDdmMTYxQ2tjRm1LU3kwQ0F3RUFBYU1RTUE0d0RBWURWUjBUQkFVd0F3RUIvekFOQmdrcWhraUc5dzBCQVFzRkFBT0NBUUVBZ1ZKVWRCaXRud3ZNdDdvci9UMlo4dEtCUUZsejFVcVVSRlRUTTBBcjY2YWx2Y2l4VWJZR3gxVHlTSk5pbm9XSUJROU9QamdMa1dQMkVRRUtvUnhxN1NidGxqNWE1RUQ2VjRyOHRsejRISjY0N3MyM2V0blJFa2o5dE9Gb3ZNZjhOdFNVeDNGTnBhRUdabDJMUlZHd3dcdTAwMkJsVThQd0gzL2IzUmVCZHRhQTdrZmFWNVx1MDAyQml4ZWRjZFN5S1F1VkFUbXZNSTcxM1A4VlBsNk1XbXNNSnRrVjNYVi9ZTUVzUVx1MDAyQkdZcU1yN2tLWGwxM3lldUVmVTJWVkVRc1ovMXRnb29iZVZLaVFcdTAwMkJUcWIwdTJOZHNcdTAwMkJLamRIdmFNYngyUjh6TDNZdTdpR0pRZnd1aU1tdUxSQlJwSUFxTWxRRktLNmRYOXF6Nk9iT01zUjlpczZ6UDZDdmxGcEV6bzVGUT09Il19.eyJBdHRlc3RhdGlvblBvbGljeSI6ImRtVnljMmx2YmoweExqQTdZWFYwYUc5eWFYcGhkR2x2Ym5KMWJHVnpJSHRqT2x0MGVYQmxQVDBpSkdsekxXUmxZblZuWjJGaWJHVWlYU0FtSmlCYmRtRnNkV1U5UFhSeWRXVmRJRDAtSUdSbGJua29LVHM5UGlCd1pYSnRhWFFvS1R0OU8ybHpjM1ZoYm1ObGNuVnNaWE1nZXlBZ0lDQmpPbHQwZVhCbFBUMGlKR2x6TFdSbFluVm5aMkZpYkdVaVhTQTlQaUJwYzNOMVpTaDBlWEJsUFNKT2IzUkVaV0oxWjJkaFlteGxJaXdnZG1Gc2RXVTlZeTUyWVd4MVpTazdJQ0FnSUdNNlczUjVjR1U5UFNJa2FYTXRaR1ZpZFdkbllXSnNaU0pkSUQwLUlHbHpjM1ZsS0hSNWNHVTlJbWx6TFdSbFluVm5aMkZpYkdVaUxDQjJZV3gxWlQxakxuWmhiSFZsS1RzZ0lDQWdZenBiZEhsd1pUMDlJaVJ6WjNndGJYSnphV2R1WlhJaVhTQTlQaUJwYzNOMVpTaDBlWEJsUFNKelozZ3RiWEp6YVdkdVpYSWlMQ0IyWVd4MVpUMWpMblpoYkhWbEtUc2dJQ0FnWXpwYmRIbHdaVDA5SWlSelozZ3RiWEpsYm1Oc1lYWmxJbDBnUFQ0Z2FYTnpkV1VvZEhsd1pUMGljMmQ0TFcxeVpXNWpiR0YyWlNJc0lIWmhiSFZsUFdNdWRtRnNkV1VwT3lBZ0lDQmpPbHQwZVhCbFBUMGlKSEJ5YjJSMVkzUXRhV1FpWFNBOVBpQnBjM04xWlNoMGVYQmxQU0p3Y205a2RXTjBMV2xrSWl3Z2RtRnNkV1U5WXk1MllXeDFaU2s3SUNBZ0lHTTZXM1I1Y0dVOVBTSWtjM1p1SWwwZ1BUNGdhWE56ZFdVb2RIbHdaVDBpYzNadUlpd2dkbUZzZFdVOVl5NTJZV3gxWlNrN0lDQWdJR002VzNSNWNHVTlQU0lrZEdWbElsMGdQVDRnYVhOemRXVW9kSGx3WlQwaWRHVmxJaXdnZG1Gc2RXVTlZeTUyWVd4MVpTazdmVHMifQ.c0l-xqGDFQ8_kCiQ0_vvmDQYG_u544CYmoiucPNxd9MU8ZXT69UD59UgSuya2yl241NoVXA_0LaMEB2re0JnTbPD_dliJn96HnIOqnxXxRh7rKbu65ECUOMWPXbyKQMZ0I3Wjhgt_XyyhfEiQGfJfGzA95-wm6yWqrmW7dMI7JkczG9ideztnr0bsw5NRsIWBXOjVy7Bg66qooTnODS_OqeQ4iaNsN-xjMElHABUxXhpBt2htbhemDU1X41o8clQgG84aEHCgkE07pR-7IL_Fn2gWuPVC66yxAp00W1ib2L-96q78D9J52HPdeDCSFio2RL7r5lOtz8YkQnjacb6xA       
 ```
 
-## Sample policy for TPM using Policy version 1.0
-
-```
-version=1.0;
-
-authorizationrules { 
-    => permit();
-};
-
-issuancerules
-{
-[type=="aikValidated", value==true]&& 
-[type=="secureBootEnabled", value==true] &&
-[type=="bootDebuggingDisabled", value==true] && 
-[type=="vbsEnabled", value==true] && 
-[type=="notWinPE", value==true] && 
-[type=="notSafeMode", value==true] => issue(type="PlatformAttested", value=true);
-};
-```
-
-A simple TPM attestation policy that can be used to verify minimal aspects of the boot.
-
-## Sample policy for TPM using Policy version 1.2
-
-```
-version=1.2;
-
-configurationrules{
-	=> issueproperty(type="required_pcr_mask", value=131070);
-	=> issueproperty(type="require_valid_aik_cert", value=false);
-};
-
-authorizationrules { 
-c:[type == "tpmVersion", issuer=="AttestationService", value==2] => permit();
-};
-
-issuancerules{
-
-c:[type == "aikValidated", issuer=="AttestationService"] =>issue(type="aikValidated", value=c.value);
-
-// SecureBoot enabled 
-c:[type == "events", issuer=="AttestationService"] => add(type = "efiConfigVariables", value = JmesPath(c.value, "Events[?EventTypeString == 'EV_EFI_VARIABLE_DRIVER_CONFIG' && ProcessedData.VariableGuid == '8BE4DF61-93CA-11D2-AA0D-00E098032B8C']"));
-c:[type == "efiConfigVariables", issuer=="AttestationPolicy"]=> issue(type = "SecureBootEnabled", value = JsonToClaimValue(JmesPath(c.value, "[?ProcessedData.UnicodeName == 'SecureBoot'] | length(@) == `1` && @[0].ProcessedData.VariableData == 'AQ'")));
-![type=="SecureBootEnabled", issuer=="AttestationPolicy"] => issue(type="SecureBootEnabled", value=false);
-
-// Retrieve bool properties Code integrity
-c:[type=="events", issuer=="AttestationService"] => add(type="boolProperties", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `19` || PcrIndex == `20`)].ProcessedData.EVENT_TRUSTBOUNDARY"));
-c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="codeIntegrityEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_CODEINTEGRITY")));
-c:[type=="codeIntegrityEnabledSet", issuer=="AttestationPolicy"] => issue(type="CodeIntegrityEnabled", value=ContainsOnlyValue(c.value, true));
-![type=="CodeIntegrityEnabled", issuer=="AttestationPolicy"] => issue(type="CodeIntegrityEnabled", value=false);
-
-// Bitlocker Boot Status, The first non zero measurement or zero.
-c:[type=="events", issuer=="AttestationService"] => add(type="srtmDrtmEventPcr", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `19`)].ProcessedData.EVENT_TRUSTBOUNDARY"));
-c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="BitlockerStatus", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_BITLOCKER_UNLOCK | @[? Value != `0`].Value | @[0]")));
-[type=="BitlockerStatus", issuer=="AttestationPolicy"] => issue(type="BitlockerStatus", value=true);
-![type=="BitlockerStatus", issuer=="AttestationPolicy"] => issue(type="BitlockerStatus", value=false);
-
-// Elam Driver (windows defender) Loaded
-c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="elamDriverLoaded", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_LOADEDMODULE_AGGREGATION[] | [? EVENT_IMAGEVALIDATED == `true` && (equals_ignore_case(EVENT_FILEPATH, '\\windows\\system32\\drivers\\wdboot.sys') || equals_ignore_case(EVENT_FILEPATH, '\\windows\\system32\\drivers\\wd\\wdboot.sys'))] | @ != `null`")));
-[type=="elamDriverLoaded", issuer=="AttestationPolicy"] => issue(type="ELAMDriverLoaded", value=true);
-![type=="elamDriverLoaded", issuer=="AttestationPolicy"] => issue(type="ELAMDriverLoaded", value=false);
-
-};
-
-```
-
-The policy uses the TPM version to restrict attestation calls. The issuancerules looks at various properties measured during boot.
-
 ## Next steps
 
 - [How to author and sign an attestation policy](author-sign-policy.md)