add X509StoreRsaKeyProvider

Author: Roman Golovanov

README.md

@@ -8,15 +8,15 @@ Property-level encryption for Entity Framework Core 8, 9, and 10. Mark the prope
 - **Use it for:** PII, notes, tokens, small secrets, and values the database should never see in plaintext
 - **Entity experience:** normal CLR properties for transparent reads, or `EncryptedValue<T>` when you want explicit async decryption
 - **Crypto shape:** AES-256-GCM payload encryption, a fresh content-encryption key per encrypted value, AES-GCM key wrapping, and RSA-wrapped key-encryption keys
-- **Key management:** file, in-memory, and Azure Key Vault RSA providers, plus in-memory or database-backed key-chain storage
+- **Key management:** file, OS certificate store, in-memory, and Azure Key Vault RSA providers, plus in-memory or database-backed key-chain storage
 
 ## Why This Package
 
 Many EF Core encryption approaches stop at the first step: convert a property to ciphertext on save and back to plaintext on read. This package also handles the parts that usually become application-specific security plumbing:
 
 - **Envelope encryption out of the box.** Each encrypted value gets its own content-encryption key. Content keys are wrapped by per-purpose key-encryption keys, and key-encryption keys are wrapped by an RSA provider.
 - **Key purposes and rotation.** Use separate key chains for different data classes, such as `email`, `notes`, or `tokens`, and rotate new writes without losing access to old rows.
-- **Production master key locations.** Keep the RSA wrapping key in a PEM file for self-hosted apps, in Azure Key Vault when the private key should stay outside the host, or in memory for tests and demos.
+- **Production master key locations.** Keep the RSA wrapping key in a PEM file, an OS certificate store, in Azure Key Vault when the private key should stay outside the host, or in memory for tests and demos.
 - **Database-backed key chain.** Store wrapped key records beside the application database, with one active key per purpose.
 - **Two entity styles.** Use ordinary CLR properties when transparency matters, or `EncryptedValue<T>` when you want decryption to be explicit and async at the call site.
 - **Typed values, not only strings.** Supported values include primitives, `string`, `byte[]`, `DateTime`, `DateTimeOffset`, `Guid`, enums, and nullable variants.
@@ -162,6 +162,24 @@ services.AddEncryptedProperties(cfg => cfg
 
 The file provider creates the PEM file if it does not exist. Back it up and protect it like any other application secret.
 
+### OS Certificate Store
+
+```csharp
+services.AddEncryptedProperties(cfg => cfg
+    .WithX509StoreRsaKeyProvider(options =>
+    {
+        options.CurrentCertificateThumbprint = "00112233445566778899AABBCCDDEEFF00112233";
+    })
+    .WithDatabaseKeyChain(SqlClientFactory.Instance, connectionString)
+    .WithKeyChainPreloadOnStartup());
+```
+
+By default, the provider reads from `CurrentUser\My`. New KEKs are wrapped with the configured current certificate thumbprint, and the stored KEK record keeps a self-describing RSA key ID such as `x509store:CurrentUser:My:{thumbprint}`. Historical KEKs unwrap by the stored thumbprint, so keep old certificates and their private keys in the store while any KEKs still reference them.
+
+For Windows services, `LocalMachine\My` can be used when the service identity has private-key access. Prefer CNG-backed RSA certificates; older CAPI keys may not support `RSA-OAEP-256`. On Linux, prefer `CurrentUser\My`; `LocalMachine\My` is not a portable place for private-key certificates in .NET. 
+
+The provider does not export private keys from store.
+
 ### Azure Key Vault
 
 ```csharp
@@ -240,6 +258,8 @@ The key-chain table enforces one active KEK per purpose with a filtered unique i
 
 Keep the RSA key stable. If the file key is deleted, replaced, or a different Key Vault key is configured, previously stored key-chain records may no longer unwrap.
 
+For the OS certificate store provider, rotate RSA wrapping keys by provisioning a new certificate with a private key, deploying its thumbprint as `CurrentCertificateThumbprint`, and allowing KEK rotation to create new active KEKs. Keep previous certificates available for decrypt and startup preload until no `EncryptedPropertyKeks.RsaKeyId` values reference their thumbprints.
+
 The library rotates data-encryption keys, but it does not automatically rotate the RSA master key.
 
 ### Plaintext Change Tracking

src/EfCore.EncryptedProperties/Extensions/EncryptedPropertiesServiceBuilder.cs

@@ -122,6 +122,19 @@ public EncryptedPropertiesServiceBuilder WithAzureKeyVaultRsaKeyProvider(
         return this;
     }
 
+    public EncryptedPropertiesServiceBuilder WithX509StoreRsaKeyProvider(
+        Action<X509StoreRsaKeyProviderOptions> configure)
+    {
+        ArgumentNullException.ThrowIfNull(configure);
+
+        var options = new X509StoreRsaKeyProviderOptions();
+        configure(options);
+
+        ReplaceSingleton<IRsaKeyProvider>(new X509StoreRsaKeyProvider(options));
+        _rsaKeyProviderConfigured = true;
+        return this;
+    }
+
     public EncryptedPropertiesServiceBuilder WithInMemoryKeyChain()
     {
         ReplaceSingleton<IKeyChainStorage>(new InMemoryKeyChainStorage());
@@ -168,7 +181,7 @@ internal void Validate()
     {
         if (!_rsaKeyProviderConfigured)
             throw new InvalidOperationException(
-                "An RSA key provider must be configured via WithInMemoryRsaKeyProvider, WithFileRsaKeyProvider, or WithAzureKeyVaultRsaKeyProvider.");
+                "An RSA key provider must be configured via WithInMemoryRsaKeyProvider, WithFileRsaKeyProvider, WithAzureKeyVaultRsaKeyProvider, or WithX509StoreRsaKeyProvider.");
 
         if (!_keyChainStorageConfigured)
             throw new InvalidOperationException(

src/EfCore.EncryptedProperties/Providers/X509StoreRsaKeyProvider.cs

@@ -0,0 +1,293 @@
+using System.Security.Cryptography;
+using System.Security.Cryptography.X509Certificates;
+using System.Text;
+using EfCore.EncryptedProperties.Abstractions;
+
+namespace EfCore.EncryptedProperties.Providers;
+
+public sealed class X509StoreRsaKeyProvider : IRsaKeyProvider
+{
+    private const string KeyIdPrefix = "x509store";
+    private const string AlgorithmName = "RSA-OAEP-256";
+    private readonly X509StoreRsaKeyProviderOptions _options;
+    private readonly string _currentCertificateThumbprint;
+
+    public X509StoreRsaKeyProvider(X509StoreRsaKeyProviderOptions options)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        if (!Enum.IsDefined(options.StoreLocation))
+            throw new ArgumentOutOfRangeException(nameof(options.StoreLocation), "Store location is not valid.");
+
+        var storeName = NormalizeStoreName(options.StoreName);
+        _currentCertificateThumbprint = NormalizeThumbprint(
+            options.CurrentCertificateThumbprint,
+            nameof(options.CurrentCertificateThumbprint));
+
+        _options = new X509StoreRsaKeyProviderOptions
+        {
+            StoreLocation = options.StoreLocation,
+            StoreName = storeName,
+            CurrentCertificateThumbprint = _currentCertificateThumbprint,
+            ValidateCurrentCertificateTime = options.ValidateCurrentCertificateTime,
+            ValidateKeyUsage = options.ValidateKeyUsage
+        };
+
+        KeyId = CreateKeyId(_options.StoreLocation, _options.StoreName, _currentCertificateThumbprint);
+    }
+
+    public string KeyId { get; }
+    public string Algorithm => AlgorithmName;
+
+    public ValueTask<RsaKeyWrapResult> WrapKeyAsync(
+        byte[] plaintext,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(plaintext);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        using var certificate = FindCertificate(
+            _options.StoreLocation,
+            _options.StoreName,
+            _currentCertificateThumbprint);
+
+        ValidateCurrentCertificate(certificate);
+
+        using var publicKey = certificate.GetRSAPublicKey()
+            ?? throw CreateCertificateException(
+                _options.StoreLocation,
+                _options.StoreName,
+                _currentCertificateThumbprint,
+                "does not have an RSA public key");
+
+        var ciphertext = publicKey.Encrypt(plaintext, RSAEncryptionPadding.OaepSHA256);
+        return new ValueTask<RsaKeyWrapResult>(
+            new RsaKeyWrapResult(ciphertext, KeyId, Algorithm));
+    }
+
+    public ValueTask<byte[]> UnwrapKeyAsync(
+        byte[] ciphertext,
+        string rsaKeyId,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(ciphertext);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var keyId = ParseKeyId(rsaKeyId);
+        using var certificate = FindCertificate(keyId.StoreLocation, keyId.StoreName, keyId.Thumbprint);
+        using var privateKey = GetPrivateKey(certificate, keyId.StoreLocation, keyId.StoreName, keyId.Thumbprint);
+
+        var plaintext = privateKey.Decrypt(ciphertext, RSAEncryptionPadding.OaepSHA256);
+        return new ValueTask<byte[]>(plaintext);
+    }
+
+    private void ValidateCurrentCertificate(X509Certificate2 certificate)
+    {
+        using var privateKey = GetPrivateKey(
+            certificate,
+            _options.StoreLocation,
+            _options.StoreName,
+            _currentCertificateThumbprint);
+
+        if (_options.ValidateCurrentCertificateTime)
+            ValidateCertificateTime(certificate);
+
+        if (_options.ValidateKeyUsage)
+            ValidateCertificateKeyUsage(certificate);
+    }
+
+    private static RSA GetPrivateKey(
+        X509Certificate2 certificate,
+        StoreLocation storeLocation,
+        string storeName,
+        string thumbprint)
+    {
+        if (!certificate.HasPrivateKey)
+        {
+            throw CreateCertificateException(
+                storeLocation,
+                storeName,
+                thumbprint,
+                "does not have an RSA private key");
+        }
+
+        try
+        {
+            return certificate.GetRSAPrivateKey()
+                ?? throw CreateCertificateException(
+                    storeLocation,
+                    storeName,
+                    thumbprint,
+                    "does not have an RSA private key");
+        }
+        catch (CryptographicException ex)
+        {
+            throw CreateCertificateException(
+                storeLocation,
+                storeName,
+                thumbprint,
+                "has an RSA private key, but it could not be opened",
+                ex);
+        }
+    }
+
+    private void ValidateCertificateTime(X509Certificate2 certificate)
+    {
+        var now = DateTimeOffset.UtcNow;
+        var notBefore = new DateTimeOffset(certificate.NotBefore.ToUniversalTime(), TimeSpan.Zero);
+        var notAfter = new DateTimeOffset(certificate.NotAfter.ToUniversalTime(), TimeSpan.Zero);
+
+        if (now < notBefore || now > notAfter)
+        {
+            throw CreateCertificateException(
+                _options.StoreLocation,
+                _options.StoreName,
+                _currentCertificateThumbprint,
+                $"is not valid at the current time. Valid from {notBefore:O} to {notAfter:O}");
+        }
+    }
+
+    private void ValidateCertificateKeyUsage(X509Certificate2 certificate)
+    {
+        var keyUsage = certificate.Extensions
+            .OfType<X509KeyUsageExtension>()
+            .FirstOrDefault();
+
+        if (keyUsage is null)
+            return;
+
+        const X509KeyUsageFlags allowed =
+            X509KeyUsageFlags.KeyEncipherment | X509KeyUsageFlags.DataEncipherment;
+
+        if ((keyUsage.KeyUsages & allowed) == 0)
+        {
+            throw CreateCertificateException(
+                _options.StoreLocation,
+                _options.StoreName,
+                _currentCertificateThumbprint,
+                "does not allow key encipherment or data encipherment");
+        }
+    }
+
+    private static X509Certificate2 FindCertificate(
+        StoreLocation storeLocation,
+        string storeName,
+        string thumbprint)
+    {
+        using var store = new X509Store(storeName, storeLocation);
+        try
+        {
+            store.Open(OpenFlags.ReadOnly);
+        }
+        catch (CryptographicException ex)
+        {
+            throw new InvalidOperationException(
+                $"Could not open X.509 certificate store '{FormatStoreName(storeLocation, storeName)}'.",
+                ex);
+        }
+
+        var matches = store.Certificates.Find(
+            X509FindType.FindByThumbprint,
+            thumbprint,
+            validOnly: false);
+
+        if (matches.Count == 0)
+        {
+            throw new InvalidOperationException(
+                $"Certificate '{thumbprint}' was not found in X.509 certificate store '{FormatStoreName(storeLocation, storeName)}'.");
+        }
+
+        return new X509Certificate2(matches[0]);
+    }
+
+    private static ParsedKeyId ParseKeyId(string rsaKeyId)
+    {
+        if (string.IsNullOrWhiteSpace(rsaKeyId))
+            throw new ArgumentException("RSA key ID cannot be null or whitespace.", nameof(rsaKeyId));
+
+        var parts = rsaKeyId.Split(':');
+        if (parts.Length != 4 || !string.Equals(parts[0], KeyIdPrefix, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException(
+                $"RSA key ID '{rsaKeyId}' is not an X.509 store key ID. Expected '{KeyIdPrefix}:{{StoreLocation}}:{{StoreName}}:{{Thumbprint}}'.");
+        }
+
+        if (!Enum.TryParse<StoreLocation>(parts[1], ignoreCase: true, out var storeLocation)
+            || !Enum.IsDefined(storeLocation))
+        {
+            throw new InvalidOperationException($"RSA key ID '{rsaKeyId}' contains an invalid X.509 store location.");
+        }
+
+        var storeName = NormalizeStoreName(parts[2]);
+        var thumbprint = NormalizeThumbprint(parts[3], nameof(rsaKeyId));
+        return new ParsedKeyId(storeLocation, storeName, thumbprint);
+    }
+
+    private static string CreateKeyId(
+        StoreLocation storeLocation,
+        string storeName,
+        string thumbprint)
+        => $"{KeyIdPrefix}:{storeLocation}:{storeName}:{thumbprint}";
+
+    private static string NormalizeStoreName(string? storeName)
+    {
+        if (string.IsNullOrWhiteSpace(storeName))
+            throw new ArgumentException("X.509 store name cannot be null or whitespace.", nameof(storeName));
+
+        if (storeName.Contains(':', StringComparison.Ordinal))
+            throw new ArgumentException("X.509 store name cannot contain ':'.", nameof(storeName));
+
+        return storeName.Trim();
+    }
+
+    private static string NormalizeThumbprint(string? thumbprint, string parameterName)
+    {
+        if (string.IsNullOrWhiteSpace(thumbprint))
+            throw new ArgumentException("Certificate thumbprint cannot be null or whitespace.", parameterName);
+
+        var builder = new StringBuilder(40);
+        foreach (var ch in thumbprint)
+        {
+            if (char.IsWhiteSpace(ch) || ch is ':' or '-')
+                continue;
+
+            if (!Uri.IsHexDigit(ch))
+            {
+                throw new ArgumentException(
+                    "Certificate thumbprint must contain only hexadecimal characters, whitespace, ':' or '-'.",
+                    parameterName);
+            }
+
+            builder.Append(char.ToUpperInvariant(ch));
+        }
+
+        if (builder.Length != 40)
+        {
+            throw new ArgumentException(
+                "Certificate thumbprint must be a SHA-1 thumbprint containing 40 hexadecimal characters.",
+                parameterName);
+        }
+
+        return builder.ToString();
+    }
+
+    private static InvalidOperationException CreateCertificateException(
+        StoreLocation storeLocation,
+        string storeName,
+        string thumbprint,
+        string message,
+        Exception? innerException = null)
+    {
+        return new InvalidOperationException(
+            $"Certificate '{thumbprint}' in X.509 certificate store '{FormatStoreName(storeLocation, storeName)}' {message}.",
+            innerException);
+    }
+
+    private static string FormatStoreName(StoreLocation storeLocation, string storeName)
+        => $"{storeLocation}\\{storeName}";
+
+    private sealed record ParsedKeyId(
+        StoreLocation StoreLocation,
+        string StoreName,
+        string Thumbprint);
+}

src/EfCore.EncryptedProperties/Providers/X509StoreRsaKeyProviderOptions.cs

@@ -0,0 +1,12 @@
+using System.Security.Cryptography.X509Certificates;
+
+namespace EfCore.EncryptedProperties.Providers;
+
+public sealed class X509StoreRsaKeyProviderOptions
+{
+    public StoreLocation StoreLocation { get; set; } = StoreLocation.CurrentUser;
+    public string StoreName { get; set; } = "My";
+    public string? CurrentCertificateThumbprint { get; set; }
+    public bool ValidateCurrentCertificateTime { get; set; } = true;
+    public bool ValidateKeyUsage { get; set; } = true;
+}