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/3] 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/3] Update docs/msi_v2/key_management.md Co-authored-by: Bogdan Gavril --- 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. From c9a881dbdb93c30aff728ca9f127a549b5b2345a Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Thu, 11 Dec 2025 14:52:22 -0800 Subject: [PATCH 3/3] Update key_management.md --- docs/msi_v2/key_management.md | 65 ++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 28 deletions(-) diff --git a/docs/msi_v2/key_management.md b/docs/msi_v2/key_management.md index a3dceff3e7..46d17da2f9 100644 --- a/docs/msi_v2/key_management.md +++ b/docs/msi_v2/key_management.md @@ -1,45 +1,60 @@ -# MSI v2 — Key Logic +# MSI v2 — Key Management ## 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). +In MSI v2, before MSAL can call the managed identity endpoints (for example the Instance Metadata Service (IMDS) or the ESTS token service), it needs an asymmetric key pair. The private key is the local root of trust used for all subsequent operations (CSR generation, certificate issuance, Proof-of-Possession (PoP) binding, and mutual TLS (mTLS) handshakes). -## Key Responsibilities +## 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. +The key management layer is responsible for: -## Key Selection Priority +- Generating the RSA key pair. +- Storing and managing the private key. + - On Windows, using the most secure available platform keystore (KeyGuard or TPM/KSP). + - On Linux, keeping the key in process memory only. +- Protecting the key to the maximum capability of the platform, preferring hardware-backed and isolated storage when available. +- Providing the key for signing (CSR, PoP requests, mTLS handshakes). +- Preventing export of hardware- or KeyGuard-backed keys (no API returns or serializes the private key material). -MSAL implements a hierarchical key provider strategy: +## Key selection priority + +MSAL implements a hierarchical key-provider strategy. + +On **Windows**: + +1. KeyGuard (preferred, especially for PoP). +2. Hardware / TPM / KSP (fallback). +3. In-memory RSA (last resort). + +On **Linux**, the only available option is in-memory RSA. + +### KeyGuard (preferred 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. -- Used for Proof-of-Possession (PoP). +- Provides the strongest guarantee that the private key cannot be exfiltrated. +- Preferred provider for PoP tokens on supported hosts. ### 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. +- Keys are backed by the Trusted Platform Module (TPM) or the Platform Crypto Provider. +- Non-exportable and tied to the device. +- Provides strong hardware-based protection, but without the additional VBS isolation offered by KeyGuard. -### In-memory RSA (last resort on Windows and only option in Linux) +### In-memory RSA (last resort on Windows and only option on Linux) -- Keys are created and held in memory. -- Software-based only, weakest in terms of protection. -- Used only when platform protections are unavailable. +- Keys are created and held in process memory. +- Software-only protection; weakest in terms of resistance to host compromise. +- Used only when stronger platform protections (KeyGuard or TPM/KSP) are unavailable. -## Mermaid — Key Selection Flow +## 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 @@ -47,16 +62,10 @@ sequenceDiagram KeyProvider-->>KeyProvider: Acquire semaphore alt KeyGuard available KeyProvider-->>MSAL: KeyGuard key (preferred) - else Hardware/TPM available + else KeyGuard not available, Hardware/TPM available KeyProvider-->>MSAL: Hardware key - else + else KeyGuard and Hardware/TPM not available 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.