From f919cabee5948f8c7f17705a0c00dedff198951d Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Thu, 2 Oct 2025 13:31:42 -0700 Subject: [PATCH 1/4] Revise certificate handling documentation for MSI v2 Updated the certificate handling documentation for MSI v2 to improve clarity and structure, including sections on certificate lifecycle, expiration, error handling, and security considerations. --- docs/msi_v2/cert_handling.md | 71 ++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/msi_v2/cert_handling.md diff --git a/docs/msi_v2/cert_handling.md b/docs/msi_v2/cert_handling.md new file mode 100644 index 0000000000..58cf32d56f --- /dev/null +++ b/docs/msi_v2/cert_handling.md @@ -0,0 +1,71 @@ +# Certificate Handling on Windows for MSI v2 / PoP + +## Overview +In the MSI v2 flow, the client must present a certificate over mTLS. +The certificate itself is the **credential** for this flow. + +Currently, the certificate is stored only in memory. +To reduce repeated calls to IMDS and enable reuse across requests, +the certificate should be **rooted (persisted)** in the Windows certificate store. + +## 1. Certificate Store Location +- Use the **Windows Certificate Store**. +- Scope: **CurrentUser\My** store (per-user, not global). +- This provides: + - Secure key isolation (KeyGuard). + - OS-enforced ACLs instead of manual file permissions. + +--- + +## 2. Certificate Lifecycle + +1. **Check Cert Store** + - Look in `CurrentUser\My` for an MSI certificate. + - Identify by subject and issuer. + - If found and not expired → load it. + +2. **No Valid Certificate** + - Generate a key pair (RSA) in KeyGuard (for POP). + - Get an attestation token for the key. + - Create CSR in memory. + - Call **IMDS issuecredential** endpoint. + - Receive certificate from IMDS. + +3. **Persist the Certificate** + - Store the new certificate (with private key) in `CurrentUser\My`. + - Mark the key as **non-exportable**. (uses KeyGuard keys - already non-exportable) + +4. **Use Certificate** + - Load cert from store as needed. + - Use it for mTLS handshake. + +--- + +## 3. Expiration and Renewal +- Certificates are short-lived (7 days). +- Always check expiration before use. +- If expired or close to expiry: + - Remove stale cert from store. + - Acquire and persist a new cert from IMDS. + +--- + +## 4. Error Handling +- If store entry is corrupt → remove it and fetch new cert. +- If IMDS call fails → bubble up error to caller. + +--- + +## 5. Security Considerations +- Private keys must be generated in **CNG/KeyGuard** with `ExportPolicy = None`. +- Keys should **never** be exported or persisted outside the Windows certificate store. +- `CurrentUser\My` is scoped to the signed-in user. +- For service scenarios, use `LocalMachine\My` with proper ACLs. + +--- + +## ✅ Summary +- Always **check Windows cert store first** (`CurrentUser\My`). +- If no valid cert, **request one from IMDS**. +- **Persist it** back into the store securely. +- **Refresh on expiration**. From 0aba5e488cfbbcb6cef7310fe00ab4b771bc59ae Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Thu, 2 Oct 2025 13:49:35 -0700 Subject: [PATCH 2/4] Update cert_handling.md --- docs/msi_v2/cert_handling.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/msi_v2/cert_handling.md b/docs/msi_v2/cert_handling.md index 58cf32d56f..d86e4de64c 100644 --- a/docs/msi_v2/cert_handling.md +++ b/docs/msi_v2/cert_handling.md @@ -56,6 +56,19 @@ the certificate should be **rooted (persisted)** in the Windows certificate stor --- +# Certificate Store Location in Linux +- Linux has no OS-backed cert store like Windows. +- Define a **per-user store** under the home directory: ~/.config/msal/certs/ + +- File naming convention: +- `msal_mtls.pfx` (PKCS#12) or +- `msal_mtls.pem` (PEM with key + cert). +- Permissions: +- Directory = `700` (only the user can read/write/execute). +- File = `600` (only the user can read/write). + +--- + ## 5. Security Considerations - Private keys must be generated in **CNG/KeyGuard** with `ExportPolicy = None`. - Keys should **never** be exported or persisted outside the Windows certificate store. From cee05248ea8f5462b9dfaae2aff8359348e38912 Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Fri, 3 Oct 2025 11:23:18 -0700 Subject: [PATCH 3/4] Include proactive renewal instructions for certificates Added proactive renewal guidance for certificates. --- docs/msi_v2/cert_handling.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/msi_v2/cert_handling.md b/docs/msi_v2/cert_handling.md index d86e4de64c..87b2c24654 100644 --- a/docs/msi_v2/cert_handling.md +++ b/docs/msi_v2/cert_handling.md @@ -48,6 +48,9 @@ the certificate should be **rooted (persisted)** in the Windows certificate stor - Remove stale cert from store. - Acquire and persist a new cert from IMDS. +### Proactive Renewal: Start renewal at half the certificate lifetime (typically, 3.5 days) to avoid expiry during active sessions. + +**This is calculated based on the certificate’s NotAfter property (expiration date).** --- ## 4. Error Handling From 57b7ca372f04fac3016f0470cef608d62b56d52e Mon Sep 17 00:00:00 2001 From: Gladwin Johnson <90415114+gladjohn@users.noreply.github.com> Date: Tue, 14 Oct 2025 08:44:20 -0700 Subject: [PATCH 4/4] Update cert_handling.md --- docs/msi_v2/cert_handling.md | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/docs/msi_v2/cert_handling.md b/docs/msi_v2/cert_handling.md index 87b2c24654..d0e324173d 100644 --- a/docs/msi_v2/cert_handling.md +++ b/docs/msi_v2/cert_handling.md @@ -60,15 +60,7 @@ the certificate should be **rooted (persisted)** in the Windows certificate stor --- # Certificate Store Location in Linux -- Linux has no OS-backed cert store like Windows. -- Define a **per-user store** under the home directory: ~/.config/msal/certs/ - -- File naming convention: -- `msal_mtls.pfx` (PKCS#12) or -- `msal_mtls.pem` (PEM with key + cert). -- Permissions: -- Directory = `700` (only the user can read/write/execute). -- File = `600` (only the user can read/write). +- Rely on .NET’s X509Store abstractions for per-user certificate storage. The framework handles platform-specific details.” --- @@ -76,7 +68,6 @@ the certificate should be **rooted (persisted)** in the Windows certificate stor - Private keys must be generated in **CNG/KeyGuard** with `ExportPolicy = None`. - Keys should **never** be exported or persisted outside the Windows certificate store. - `CurrentUser\My` is scoped to the signed-in user. -- For service scenarios, use `LocalMachine\My` with proper ACLs. ---