From aa1667ffc22a592d5b1330a9cc42ea3eb056075a Mon Sep 17 00:00:00 2001
From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>
Date: Thu, 2 Oct 2025 12:33:58 -0700
Subject: [PATCH 1/2] Add key management documentation for MSI v2

Document the key management logic and responsibilities in MSI v2, including key selection priorities and flow.
---
 docs/msi_v2/key_management.md | 62 +++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/msi_v2/key_management.md

diff --git a/docs/msi_v2/key_management.md b/docs/msi_v2/key_management.md
new file mode 100644
index 0000000000..92767fa03d
--- /dev/null
+++ b/docs/msi_v2/key_management.md
@@ -0,0 +1,62 @@
+# MSI v2 — Key Logic
+
+## Overview
+
+In MSI v2, before MSAL can do anything with IMDS or ESTS, it needs a key pair. This private key is the root trust anchor for all subsequent operations (CSR, cert issuance, PoP binding).
+
+## Key Responsibilities
+
+- Generate and hold the RSA private key.
+- Ensure the key is protected to the maximum capability of the platform.
+- Provide the key for signing (CSR, PoP requests, mTLS handshakes).
+- Never allow export if backed by hardware/KeyGuard.
+
+## Key Selection Priority
+
+MSAL implements a hierarchical key provider strategy:
+
+### KeyGuard (awlays for PoP)
+- Requires Virtualization-Based Security (VBS).
+- Keys are isolated in a secure enclave.
+- Strongest guarantee that the private key cannot be exfiltrated.
+- Used for Proof-of-Possession (PoP).
+
+### Hardware / TPM / KSP (fallback)
+
+- Keys are backed by TPM or the Platform Crypto Provider.
+- Non-exportable, tied to the device.
+- Provides strong hardware-based protection, but not as strict as VBS isolation.
+
+### In-memory RSA (last resort on Windows and only option in Linux)
+
+- Keys are created and held in memory.
+- Software-based only, weakest in terms of protection.
+- Used only when platform protections are unavailable.
+
+## Mermaid — Key Selection Flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant MSAL
+    participant KeyProvider as Key Provider
+    MSAL->>KeyProvider: GetOrCreateKey()
+    alt Cached key exists
+        KeyProvider-->>MSAL: Return cached key
+    else No cached key
+        KeyProvider-->>KeyProvider: Acquire semaphore
+        alt KeyGuard available
+            KeyProvider-->>MSAL: KeyGuard key (preferred)
+        else Hardware/TPM available
+            KeyProvider-->>MSAL: Hardware key
+        else
+            KeyProvider-->>MSAL: In-memory RSA key
+        end
+        KeyProvider-->>KeyProvider: Cache key & release semaphore
+    end
+```
+
+
+✅ Summary:
+
+In MSI v2, everything starts with a key. MSAL enforces a secure-first fallback chain: KeyGuard → TPM → In-memory. For PoP tokens, KeyGuard is the preferred option since it offers the strongest binding guarantees.

From 6633a4e49d7e46302462a0cd0a59c30b132c25e4 Mon Sep 17 00:00:00 2001
From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com>
Date: Tue, 21 Oct 2025 09:58:03 -0700
Subject: [PATCH 2/2] Update docs/msi_v2/key_management.md

Co-authored-by: Bogdan Gavril <bogavril@microsoft.com>
---
 docs/msi_v2/key_management.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/msi_v2/key_management.md b/docs/msi_v2/key_management.md
index 92767fa03d..a3dceff3e7 100644
--- a/docs/msi_v2/key_management.md
+++ b/docs/msi_v2/key_management.md
@@ -15,7 +15,7 @@ In MSI v2, before MSAL can do anything with IMDS or ESTS, it needs a key pair. T
 
 MSAL implements a hierarchical key provider strategy:
 
-### KeyGuard (awlays for PoP)
+### KeyGuard (always for PoP)
 - Requires Virtualization-Based Security (VBS).
 - Keys are isolated in a secure enclave.
 - Strongest guarantee that the private key cannot be exfiltrated.