Merge pull request #230386 from agowdamsft/agowdamsft-patch-skr-3

AKV SKR Related PR

Author: AnnaMHuff

articles/confidential-computing/TOC.yml

@@ -122,6 +122,18 @@
 - name: How To
   expanded: true
   items:
+  - name: concept
+    items:
+    - name: Secure Key Release (SKR) with Azure Key Vault
+      items:
+      - name: SKR with Azure Confidential Computing Concept
+        href: concept-skr-attestation.md
+      - name: SKR with AMD SEV-SNP based Confidential VMs
+        href: skr-flow-confidential-vm-sev-snp.md
+      - name: SKR with Confidential containers on Azure Container Instance
+        href: skr-flow-confidential-containers-azure-container-instance.md
+      - name: SKR Policy Examples
+        href: skr-policy-examples.md
   - name: Partner Solutions
     items:
     - name: Fortanix

articles/confidential-computing/concept-skr-attestation.md

@@ -0,0 +1,119 @@
+---
+title: Secure Key Release with Azure Key Vault and Azure Confidential Computing
+description: Concept guide on what SKR is and its usage with Azure Confidential Computing Offerings
+author: agowdamsft
+ms.service: virtual-machines
+ms.subservice: confidential-computing
+ms.workload: infrastructure
+ms.topic: conceptual
+ms.date: 2/2/2023
+ms.author: amgowda
+---
+
+# Secure Key Release feature with AKV and Azure Confidential Computing (ACC)
+
+Secure Key Release (SKR) is a functionality of Azure Key Vault (AKV) Managed HSM and Premium offering. Secure key release enables the release of an HSM protected key from AKV to an attested Trusted Execution Environment (TEE), such as a secure enclave, VM based TEEs etc. SKR adds another layer of access protection to your data decryption/encryption keys where you can target an application + TEE runtime environment with known configuration get access to the key material. The SKR policies defined at the time of exportable key creation govern the access to these keys.
+
+## SKR support with AKV offerings
+
+- [Azure Key Vault Premium](../security/fundamentals/key-management.md)
+- [Azure Key Vault Managed HSM](../key-vault/managed-hsm/overview.md)
+
+## Overall Secure Key Release Flow with TEE
+
+SKR can only release keys based on the Microsoft Azure Attestation (MAA) generated claims. There's a tight integration on the SKR policy definition to MAA claims.
+
+![Diagram of Secure Key Release Flow.](media/skr-flow-confidential-vm-sev-snp-attestation/skr-e2e-flow.png)
+
+The below steps are for AKV Premium. 
+
+### Step 1: Create a Key Vault Premium HSM Backed
+
+[Follow the details here for Az CLI based AKV creation](../key-vault/general/quick-create-cli.md)
+
+Make sure to set the value of [--sku] to "premium".
+
+### Step 2: Create a Secure Key Release Policy
+
+A Secure Key Release Policy is a json format release policy as defined [here](/rest/api/keyvault/keys/create-key/create-key?tabs=HTTP#keyreleasepolicy) that specifies a set of claims required in addition to authorization to release the key. The claims here are MAA based claims as referenced [here for SGX](/azure/attestation/attestation-token-examples#sample-jwt-generated-for-sgx-attestation) and here for [AMD SEV-SNP CVM](/azure/attestation/attestation-token-examples#sample-jwt-generated-for-sev-snp-attestation).
+
+Visit the TEE specific [examples page for more details](skr-policy-examples.md)
+
+Before you set an SKR policy make sure to run your TEE application through the remote attestation flow. Remote attestation isn't covered as part of this tutorial.
+
+Example
+
+```json
+{
+    "version": "1.0.0",
+    "anyOf": [ // Always starts with "anyOf", meaning you can multiple, even varying rules, per authority.
+        {
+            "authority": "https://sharedweu.weu.attest.azure.net",
+            "allOf": [ // can be replaced by "anyOf", though you cannot nest or combine "anyOf" and "allOf" yet.
+                {
+                    "claim": "x-ms-isolation-tee.x-ms-attestation-type", // These are the MAA claims.
+                    "equals": "sevsnpvm"
+                },
+                {
+                    "claim": "x-ms-isolation-tee.x-ms-compliance-status",
+                    "equals": "azure-compliant-cvm"
+                }
+            ]
+        }
+    ]
+}
+
+
+```
+
+### Step 3: Create an exportable key in AKV with attached SKR policy
+
+Exact details of the type of key and other attributes associated can be found [here](../key-vault/general/quick-create-cli.md).
+
+```azurecli
+az keyvault key create --exportable true --vault-name "vault name from step 1" --kty RSA-HSM --name "keyname" --policy "jsonpolicyfromstep3 -can be a path to JSON" --protection hsm --vault-name "name of vault created from step1"               
+```
+
+### Step 4: Application running within a TEE doing a remote attestation
+
+This step can be specific to the type of TEE you're running your application Intel SGX Enclaves or AMD SEV-SNP based Confidential Virtual Machines (CVM) or Confidential Containers running in CVM Enclaves with AMD SEV-SNP etc.
+
+Follow these references examples for various TEE types offering with Azure:
+
+- [Application within AMD EV-SNP based CVM's performing Secure Key Release](skr-flow-confidential-vm-sev-snp.md)
+- [Confidential containers with Azure Container Instances (ACI) with SKR side-car containers](skr-flow-confidential-containers-azure-container-instance.md)
+- [Intel SGX based applications performing Secure Key Release - Open Source Solution Mystikos Implementation](https://github.com/deislabs/mystikos/tree/main/samples/confidential_ml#environment)
+
+## Frequently Asked Questions (FAQ)
+
+### Can I perform SKR with non confidential computing offerings?
+
+No. The policy attached to SKR only understands MAA claims that are associated to hardware based TEEs.
+
+### Can I bring my own attestation provider or service and use those claims for AKV to validate and release?
+
+No. AKV only understands and integrates with MAA today.
+
+### Can I use AKV SDKs to perform key RELEASE?
+
+Yes. Latest SDK integrated with 7.3 AKV API's support key RELEASE.
+
+### Can you share some examples of the key release policies?
+
+Yes, detailed examples by TEE type are listed [here.](./skr-policy-examples.md)
+
+## Can I attach SKR type of policy with certificates and secrets?
+
+No. Not at this time.
+
+## References
+
+[SKR Policy Examples](skr-policy-examples.md)
+
+[Azure Container Instance with confidential containers Secure Key Release with container side-cars](skr-flow-confidential-containers-azure-container-instance.md)
+
+[CVM on AMD SEV-SNP Applications with Secure Key Release Example](skr-flow-confidential-vm-sev-snp.md)
+
+[AKV REST API With SKR Details](/rest/api/keyvault/keys/create-key/create-key?tabs=HTTP)
+
+[AKV SDKs](../key-vault/general/client-libraries.md)

articles/confidential-computing/confidential-containers-enclaves.md

@@ -1,5 +1,5 @@
 ---
-title: Confidential containers with Intex SGX enclaves on Azure
+title: Confidential containers with Intel SGX enclaves on Azure
 description: Learn about unmodified container support with confidential containers on Intel SGX through OSS and partner solutions
 services: container-service
 author: agowdamsft

articles/confidential-computing/index.yml

@@ -166,3 +166,20 @@ landingContent:
             url: ../virtual-machines/dcv2-series.md
           - text: DCsv3 and DCdsv3-series virtual machines
             url: ../virtual-machines/dcv3-series.md
+## Row 2
+# Card
+  - title: Concepts
+    linkLists:
+      - linkListType: concept
+        links: 
+          - text: Secure Key Release(SKR) with AKV and Azure Confidential Computing
+            url: concept-skr-attestation.md
+          - text: Secure Key Release(SKR) with AKV example policies
+            url: skr-policy-examples.md
+      - linkListType: quickstart
+        links:
+          - text: Confidential VM's SKR with guest attestation application
+            url: skr-flow-confidential-vm-sev-snp.md
+          - text: Confidential containers with Azure Container Instances SKR Side-Car
+            url: skr-flow-confidential-containers-azure-container-instance.md
+     

articles/confidential-computing/media/skr-flow-azure-container-instance-sev-snp-attestation/skr-flow-custom-container.png

@@ -0,0 +1,79 @@
+---
+title: Secure Key Release with Azure Key Vault and Confidential Containers on Azure Container Instance
+description: Learn how to build an application that securely gets the key from AKV to an attested Azure Container Instances confidential container environment
+author: agowdamsft
+ms.service: virtual-machines
+ms.subservice: confidential-computing
+ms.workload: infrastructure
+ms.topic: conceptual
+ms.date: 3/9/2023
+ms.author: amgowda
+---
+
+# Secure Key Release with Confidential containers on Azure Container Instance (ACI)
+
+Secure Key Release (SKR) flow with Azure Key Vault (AKV) with confidential container offerings can implement in couple of ways. Confidential containers run a guest enlightened exposting AMD SEV-SNP device through a Linux Kernel that uses an in guest firmware with necessary Hyper-V related patches that we refer as Direct Linux Boot (DLB). This platform doesn't use vTPM and HCL based that Confidential VMs with AMD SEV-SNP support. This concept document assumes you plan to run the containers in [Azure Container Support choosing a confidential computing SKU](../container-instances/container-instances-tutorial-deploy-confidential-containers-cce-arm.md)
+
+- Side-Car Helper Container provided by Azure
+- Custom implementation with your container application
+
+## Side-Car helper container provided by Azure
+
+An [open sourced GitHub project "confidential side-cars"](https://github.com/microsoft/confidential-sidecar-containers) details how to build this container and what parameters/environment variables are required for you to prepare and run this side-car container. The current side car implementation provides various HTTP REST APIs that your primary application container can use to fetch the key from AKV. The integration through Microsoft Azure Attestation(MAA) is already built in. The preparation steps to run the side-car SKR container can be found in details [here](https://github.com/microsoft/confidential-sidecar-containers/tree/main/examples/skr).
+
+Your main application container application can call the side-car WEB API end points as defined in the example blow. Side-cars runs within the same container group and is a local endpoint to your application container. Full details of the API can be found [here](https://github.com/microsoft/confidential-sidecar-containers/blob/main/cmd/skr/README.md)
+ 
+The `key/release` POST method expects a JSON of the following format:
+
+```json
+{	
+    "maa_endpoint": "<maa endpoint>", //https://learn.microsoft.com/en-us/azure/attestation/quickstart-portal#attestation-provider
+    "akv_endpoint": "<akv endpoint>", //AKV URI
+    "kid": "<key identifier>" //key name,
+    "access_token": "optional aad token if the command will run in a resource without proper managed identity assigned"
+}
+```
+
+Upon success, the `key/release` POST method response carries a `StatusOK` header and a payload of the following format:
+
+```json
+{
+    "key": "<key in JSON Web Key format>"
+}
+```
+
+Upon error, the `key/release` POST method response carries a `StatusForbidden` header and a payload of the following format:
+
+```json
+{
+    "error": "<error message>"
+}
+```
+
+## Custom implementation with your container application
+
+To perform a custom container application that extends the capability of Azure Key Vault (AKV) - Secure Key Release and Microsoft Azure Attestation (MAA), use the below as a high level reference flow. An easy approach is to review the current side-car implementation code in this [side-car Github project](https://github.com/microsoft/confidential-sidecar-containers/tree/d933d0f4e3d5498f7ed9137189ab6a23ade15466/pkg/common).
+
+![Image of the aforementioned operations, which you should be performing.](media/skr-flow-azure-container-instance-sev-snp-attestation/skr-flow-custom-container.png)
+
+1. **Step 1:** Set up AKV with Exportable Key and attach the release policy. More [here](concept-skr-attestation.md)
+1. **Step 2:** Set up a managed identity with Azure Active Directory and attach that to AKV. More [here](../container-instances/container-instances-managed-identity.md)
+1. **Step 3:** Deploy your container application with required parameters within ACI by setting up a confidential computing enforcement policy. More [here](../container-instances/container-instances-tutorial-deploy-confidential-containers-cce-arm.md)
+1. **Step 4:** In this step, your application shall fetch a RAW AMD SEV-SNP hardware report by doing a IOCTL Linux Socket call. You don't need any guest attestation library to perform this action. More on existing side-car [implementation](https://github.com/microsoft/confidential-sidecar-containers/blob/d933d0f4e3d5498f7ed9137189ab6a23ade15466/pkg/attest/snp.go)
+1. **Step 5:** Fetch the AMD SEV-SNP cert chain for the container group. These certs are delivered from Azure host IMDS endpoint. More [here](https://github.com/microsoft/confidential-sidecar-containers/blob/d933d0f4e3d5498f7ed9137189ab6a23ade15466/pkg/common/info.go)
+1. **Step 6:** Send the SNP RAW hardware report and cert details to MAA for verification and return claims. More [here](../attestation/basic-concepts.md)
+1. **Step 7:** Send the MAA token and the managed identity token generated by ACI to AKV for key release. More [here](../container-instances/container-instances-managed-identity.md)
+
+On success of the key fetch from AKV, you can consume the key for decrypting the data sets or encrypt the data going out of the confidential container environment.
+
+## References
+
+[ACI with Confidential container deployments](../container-instances/container-instances-tutorial-deploy-confidential-containers-cce-arm.md)
+
+[Side-Car Implementation with encrypted blob fetch and decrypt with SKR AKV key](https://github.com/microsoft/confidential-sidecar-containers/#encrypted-filesystem-sidecar)
+
+[AKV SKR with Confidential VM's AMD SEV-SNP](skr-flow-confidential-vm-sev-snp.md)
+
+[Microsoft Azure Attestation (MAA)](../attestation/overview.md)
+
+[SKR Policy Examples](skr-policy-examples.md)