[API Proposal]: Enhance X509Store Import to Support Secure Private Key Storage (Linux & Cross-Platform)

[billnice250]

Background and motivation

Problem

When importing a PFX file using X509Store.Import() or X509Certificate2.Import() on Linux, the private key is extracted and stored in clear text under:
📂 ~/.dotnet/corefx/cryptography/x509stores/

This is different from Windows, where private keys can be securely stored in KeyStore and protected by mechanisms like DPAPI.

The current behavior on Linux does not allow for encrypted storage of private keys, which poses a security risk for users.

Repro Steps

var cert = new X509Certificate2("mycert.pfx", "password", 
    X509KeyStorageFlags.PersistKeySet | X509KeyStorageFlags.UserKeySet);
var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadWrite);
store.Add(cert);
store.Close();

🔹 This process stores the private key in clear text within ~/.dotnet/corefx/cryptography/x509stores/.

Expected Behavior

• The X509Store.Import() functionality should allow for encrypted storage of private keys.
• Alternatively, there should be a flag or mechanism in X509KeyStorageFlags that enforces secure storage of the private key during the import process.
• The X509Store API should handle private key storage in a more secure way, similar to how it's handled on Windows or macOS (e.g., using Keychain on macOS or TPM on Windows).

Actual Behavior

• Private keys are stored in clear text on Linux systems.
• There is no mechanism to encrypt the private key during the import process, leaving sensitive information exposed.

Proposed Solution

1. Provide a flag like X509KeyStorageFlags.SecureImport that encrypts private keys automatically during the import process.
2. Integrate with OS-native key management systems such as libsecret, GPG, or OpenSSL to securely store private keys.
3. Allow .NET users to load and store encrypted PFX files without extracting keys to unprotected disk storage.
4. Ensure the behavior is consistent across platforms (Linux, macOS, Windows) for private key storage.

Environment

• .NET Version: 8.0 (and prior)
• OS: Linux (Ubuntu, Debian, RHEL, etc.)
• Reproducible: ✅ Yes, always

Security Risk

This exposes private keys to unauthorized access unless users manually encrypt or use external security mechanisms, which can be cumbersome and error-prone.

Additional Context

• Windows uses DPAPI for private key protection.
• macOS uses the Keychain for secure private key storage.
• Linux lacks native, consistent private key protection mechanisms for .NET applications, and users must resort to custom workarounds like encrypting the PFX file manually before import.

API Proposal

public enum X509KeyProtectionMode
{
    None,        // Default (current behavior, unprotected storage)
    UserSecret,  // Encrypts private keys using a user-provided secret
    SecureStore  // Uses OS-native secure storage (DPAPI, Keychain, libsecret, etc.)
}

public sealed class X509Store
{
    // New overload of the Add method with key protection mode
    public void Add(X509Certificate2 certificate, X509KeyProtectionMode protectionMode, string? userSecret = null)
    {
        if (protectionMode == X509KeyProtectionMode.UserSecret && string.IsNullOrEmpty(userSecret))
        {
            throw new ArgumentException("UserSecret cannot be null when using UserSecret mode.");
        }

        // Logic to securely store the private key using the chosen protection mode
    }

    // Existing method (for backward compatibility)
    public void Add(X509Certificate2 certificate) { /* Default behavior */ }
}

API Usage

1. Use UserSecret for Encryption

var cert = new X509Certificate2("mycert.pfx", "password", 
    X509KeyStorageFlags.PersistKeySet | X509KeyStorageFlags.UserKeySet);

var store = new X509Store(StoreName.My, StoreLocation.CurrentUser);
store.Open(OpenFlags.ReadWrite);
store.Add(cert, X509KeyProtectionMode.UserSecret, "MySecureUserSecret");
store.Close();

2. Use OS Secure Storage

store.Add(cert, X509KeyProtectionMode.SecureStore);

3. Default (No Protection, Current Behavior)

store.Add(cert, X509KeyProtectionMode.SecureStore);

Alternative Designs

No response

Risks

This exposes private keys to unauthorized access unless users manually encrypt or use external security mechanisms, which can be cumbersome and error-prone.

[bartonjs]

Windows key protection is provided by Windows. macOS key protection is provided by macOS.

Last time I looked, there was not a standard solution on Linux. There are "solutions", but not "a solution", and they all resort to "you put a master key somewhere" and that master key, of course, has to be loadable by the runtime with no prompting.

When we evaluated things in the past we decided that was the same as not encrypting the keys, so we just do our best effort to restrict access (like fail if the directory mode bits grant read to other than the user).

[billnice250]

Hi @bartonjs,

Thanks for the clarification — I fully agree with your view of the current Linux situation.

Right now, the runtime relies on file system permissions to protect keys, and if we load a master key at runtime without user interaction, it essentially means no real protection, since the master key becomes part of the trusted computing base.

That’s exactly the gap I want to address with this new design. Instead of just focusing on encrypting keys at rest, I’m proposing an architecture that separates the certificate from the private key material and delegates key management to pluggable providers (through and interface that can be defined by the user through libraries/nuget packages).
The runtime stays agnostic and simply reads metadata, handing off control to providers such as:
• Local encrypted stores for simple setups,
• OS-native keystores (DPAPI, Keychain, libsecret),
• Or stronger solutions like TPM, HSM, or Cloud HSM, where keys never enter application memory.

This way, especially in environments like Linux, we avoid weak workarounds (like loading a master key from disk) and give developers flexibility to choose providers that fit their security needs.

I’ll expand on this soon and share the full architecture, explaining how providers would work, how metadata references the keys, and how this approach keeps the runtime clean while giving developers better security options.

[billnice250]

Proposal: Provider-Based Private Key Management for X509Store

I want to propose a clean, maintainable design for improving private key handling in X509Store, making it extensible and secure, while keeping a familiar developer experience.

Today, when we call .Add() on X509Store, both the certificate and its private key (PFX) are stored together.
On Linux, this means the private key ends up written unencrypted in the store path:

~/.dotnet/corefx/cryptography/x509stores/

This is a risk: it relies entirely on file system permissions.
More importantly, even if we encrypted it, we still have to manage the secret key leading to the issues @bartonjs pointed out.

Instead of focusing on encrypting the private key at rest, I am proposing to fully separate the private key handling from the certificate storage, and delegate it to pluggable providers, discovered via dependency injection.

---

Design Summary

• ✅ The X509Store constructor accepts an IServiceProvider.
• ✅ When calling .Add(), we store only the certificate and private key metadata.
• ✅ Providers manage the actual private key storage (or use an existing external key).
• ✅ At runtime, the store resolves the correct provider via DI and uses the metadata to either:
  • Decrypt and return the key material (exportable case), or
  • Provide a native cryptographic interface for private operations (non-exportable case).
• ✅ If the provider is not registered, the private key is ignored gracefully.
• ✅ Metadata can either be auto-generated by the provider or partially supplied by the caller (for advanced cases like external HSM / Cloud KMS , Platform native providers (Windows API / Macs KeyChain)).

---

Add() Flow — Two Options

Option 1: Provider generates metadata (simplest case)

// Setup services
var services = new ServiceCollection();
services.AddSingleton<IPrivateKeyProvider, CloudHsmProvider>();
var serviceProvider = services.BuildServiceProvider();

// Create store with DI
var store = new X509Store(StoreName.My, StoreLocation.CurrentUser, serviceProvider);

// Add certificate, provider generates metadata (key id, etc.)
var cert = new X509Certificate2("mycert.pfx", "password");
store.Open(OpenFlags.ReadWrite);
store.Add(cert, providerName: "CloudHsmProvider");
store.Close();

✔️ Provider generates key ID and metadata internally.
✔️ Useful for provider-managed key lifecycle.

---

Option 2: Caller supplies key ID (advanced/external keys)

// Existing external key in CloudHSM or TPM
var keyId = "cloudhsm://my-preexisting-key";

// Add certificate, passing external key ID explicitly
store.Open(OpenFlags.ReadWrite);
store.Add(cert, providerName: "CloudHsmProvider", privateKeyId: keyId);
store.Close();

✔️ Metadata includes caller-supplied key ID.
✔️ Useful when the key already exists externally and should not be generated by the provider.

---

Metadata Example

{
  "thumbprint": "ABC123",
  "keyIdentifier": "cloudhsm://my-preexisting-key",
  "provider": "CloudHsmProvider",
  "exportable": false,
  "protectionMode": "ExternalProvider"
}

• ✅ keyIdentifier: supplied or generated by provider.
• ✅ provider: maps to IPrivateKeyProvider resolved from DI.
• ✅ exportable: provider-defined.
• ✅ protectionMode: descriptive for audit/debug purposes.

---

Get() Flow

store.Open(OpenFlags.ReadOnly);
foreach (var cert in store.Certificates)
{
    var privateKey = cert.GetPrivateKey(); // Store uses IServiceProvider to resolve the correct provider
    // Use privateKey for signing or decryption
}
store.Close();

✔️ If provider is available, the store resolves the private key via metadata.
✔️ If provider is missing, the store loads the certificate without the private key.
✔️ No insecure fallback.

---

Benefits

• ✅ Clean, familiar developer experience.
• ✅ Avoids insecure plaintext private keys (critical for Linux).
• ✅ Providers control key generation, storage, and exportability.
• ✅ DI-driven — natural fit for .NET applications.
• ✅ Multiple providers supported (in place (default plain behaviour), local, cloud, hardware-backed, custom).
• ✅ Metadata-first design, enabling flexibility and future extensibility.

---

Summary

This proposal respects the current flow of X509Store, while introducing provider-based flexibility for managing private keys securely.
Whether the private key is generated on-demand or exists externally, the flow is natural and predictable for developers.

The runtime behaves safely:

• No provider → no private key loaded.
• Provider available → resolve via metadata and use key or operational handle.
• Developer flow remains clear, while underlying security posture is greatly improved.

Looking forward to your thoughts @bartonjs!

[bartonjs]

We don't do dependency injection in the BCL. We definitely can't use IServiceProvider-based DI, because it depends on the BCL.

Your proposal seems to be implying that the private key could be stored in a cloud HSM. That's not viable. On Windows private keys have to be backed directly by Windows CNG (NCrypt) to work with SslStream, on Linux they have to be OpenSSL EVP_PKEYs, and on macOS the cert and key need to be SecIdentity(Ref). Supporting "keys from somewhere else" would require a colossal amount of work, especially given that we are adamant that we will not implement the TLS protocol (we use other libraries for that).

Maybe I read the suggestion wrong and you're saying that CloudHSM has a KEK to protect locally encrypted key blobs. That's fine, but remember the store is a shared component; per-process runtime configuration doesn't really make sense. That would have to be something read at startup and used for any access to whatever store/stores use it, and would count as persisted state, not runtime options. It then needs to account for what failure means, if it's supposed to be able to talk to a cloud HSM then what sort of timeouts, and network failure resolution should take place, etc.

I do appreciate the idea, and the the thought and effort behind it. But the only thing we can do is "make the story on Linux better", and that whatever we would do has to work on basically all Linux-based OS/Distros. And further keep in mind that multiple versions of .NET share the same X509Store... so any change will either take many years of dark-deploy or have to be serviced (which means it needs to be both valueable and 'surgical').

To my recollection, very few things in .NET use X509Store or store name parameters (except config), they use X509Certificate12Collection. So you could get most of the benefit, and a lot of "in the field" learning from just doing it as a store on the side. It will, ultimately have to end up with something acceptable to X509Certificate2.CopyWithPrivateKey, which means either the correct underlying private key type for the platform, or an exportable key that gets copied into a platform interpretation.

var privateKey = cert.GetPrivateKey();

Private keys have no common base class (they used to, until we decided the new PQC types should break away from the tyranny of AsymmetricAlgorithm). This is part of why I don't ever like anyone using var, you get to just pretend that there's an answer. If your answer is this is some new kind of keyref.. well, that goes back to this being a colossal effort.

---

There's definitely good thinking that can come out of grandiose plans. But because of interdependencies and compatibility concerns, we can't do anything on this grand a scale. Something like having one KEK, or one KEK per store, and having only one file that needs to be really locked down is tactical, and different. Is it enough? That would require a real threat model -- describing what things it mitigates against, what the cost is, and how the new failure modes would manifest.