add custom serializer support

Author: Roman Golovanov

README.md

@@ -298,6 +298,37 @@ This registers an `IHostedService` that unwraps all stored KEKs during host star
 
 Supported value types are primitives, `string`, `byte[]`, `bool`, `DateTime`, `DateTimeOffset`, `Guid`, enums backed by supported primitives, and nullable variants.
 
+### Custom Value Serializers
+
+Register a serializer when an encrypted property uses a plaintext type outside the built-in set. Built-in formats cannot be overridden, so existing encrypted values stay readable.
+
+```csharp
+using System.Text;
+using EfCore.EncryptedProperties.Serialization;
+
+services.AddEncryptedProperties(cfg => cfg
+    .WithFileRsaKeyProvider("rsa-key.pem", "rsa-v1")
+    .WithDatabaseKeyChain(SqlClientFactory.Instance, connectionString)
+    .WithValueSerializer<Uri>(new UriValueSerializer()));
+
+public sealed class Customer
+{
+    public Guid Id { get; set; }
+
+    [Encrypted("website")]
+    public Uri Website { get; set; } = new("https://example.com");
+}
+
+public sealed class UriValueSerializer : IEncryptedPropertyValueSerializer<Uri>
+{
+    public byte[] Serialize(Uri value)
+        => Encoding.UTF8.GetBytes(value.ToString());
+
+    public Uri Deserialize(byte[] data)
+        => new(Encoding.UTF8.GetString(data), UriKind.Absolute);
+}
+```
+
 ## Edge Cases
 
 ### Queries

src/EfCore.EncryptedProperties/Configuration/EncryptedPropertiesOptions.cs

@@ -1,7 +1,36 @@
+using EfCore.EncryptedProperties.Serialization;
+
 namespace EfCore.EncryptedProperties.Configuration;
 
 public sealed class EncryptedPropertiesOptions
 {
+    private readonly Dictionary<Type, ICustomValueSerializer> _valueSerializers = new();
+
     public RotationPolicy RotationPolicy { get; } = new();
     public TimeSpan KekCacheLifetime { get; set; } = TimeSpan.FromMinutes(30);
+
+    internal IReadOnlyList<Type> CustomValueSerializerTypes =>
+        _valueSerializers.Keys
+            .OrderBy(type => type.AssemblyQualifiedName, StringComparer.Ordinal)
+            .ToArray();
+
+    internal void SetValueSerializer<TValue>(IEncryptedPropertyValueSerializer<TValue> serializer)
+    {
+        ArgumentNullException.ThrowIfNull(serializer);
+
+        _valueSerializers[typeof(TValue)] = new CustomValueSerializer<TValue>(serializer);
+    }
+
+    internal bool TryGetValueSerializer(Type type, out ICustomValueSerializer serializer)
+    {
+        var serializerType = Nullable.GetUnderlyingType(type) ?? type;
+        if (_valueSerializers.TryGetValue(serializerType, out var registered))
+        {
+            serializer = registered;
+            return true;
+        }
+
+        serializer = null!;
+        return false;
+    }
 }

src/EfCore.EncryptedProperties/Configuration/EncryptedPropertyContext.cs

@@ -5,4 +5,5 @@ public sealed class EncryptedPropertyContext
     public required string Purpose { get; init; }
     public string? EntityTypeName { get; init; }
     public string? PropertyName { get; init; }
+    public Type? PlaintextType { get; init; }
 }

src/EfCore.EncryptedProperties/Cryptography/EncryptedPropertyCryptor.cs

@@ -31,7 +31,8 @@ public EncryptedPropertyCryptor(
         if (value is null)
             return null;
 
-        var plaintext = _serializer.Serialize(value, value.GetType());
+        var plaintextType = context.PlaintextType ?? value.GetType();
+        var plaintext = _serializer.Serialize(value, plaintextType);
         var kek = await _keyChainManager.GetActiveKeyAsync(context.Purpose, cancellationToken);
         var cek = CekGenerator.Generate();
 

src/EfCore.EncryptedProperties/Extensions/EncryptedPropertiesServiceBuilder.cs

@@ -324,6 +324,16 @@ public EncryptedPropertiesServiceBuilder WithKeyChainPreloadOnStartup()
         return this;
     }
 
+    public EncryptedPropertiesServiceBuilder WithValueSerializer<TValue>(
+        IEncryptedPropertyValueSerializer<TValue> serializer)
+    {
+        ArgumentNullException.ThrowIfNull(serializer);
+
+        ValidateCustomValueSerializerType(typeof(TValue));
+        _options.SetValueSerializer(serializer);
+        return this;
+    }
+
     internal void Validate()
     {
         if (!_rsaKeyProviderConfigured)
@@ -347,4 +357,31 @@ private static void ThrowIfNullOrWhiteSpace(string value)
         if (string.IsNullOrWhiteSpace(value))
             throw new ArgumentException("Value cannot be null or whitespace.", nameof(value));
     }
+
+    private static void ValidateCustomValueSerializerType(Type type)
+    {
+        var nullableType = Nullable.GetUnderlyingType(type);
+        if (nullableType is not null)
+        {
+            throw new ArgumentException(
+                $"Custom encrypted property value serializer type '{GetTypeDisplayName(type)}' cannot be nullable. Register a serializer for '{GetTypeDisplayName(nullableType)}' instead.");
+        }
+
+        if (EncryptedPropertyTypeSupport.IsEncryptedValueType(type))
+        {
+            throw new ArgumentException(
+                $"Custom encrypted property value serializers target plaintext types. Register a serializer for the inner plaintext type instead of '{GetTypeDisplayName(type)}'.");
+        }
+
+        if (EncryptedPropertyTypeSupport.IsBuiltInPlaintextType(type))
+        {
+            throw new ArgumentException(
+                $"Built-in encrypted property type '{GetTypeDisplayName(type)}' cannot be overridden by a custom value serializer.");
+        }
+    }
+
+    private static string GetTypeDisplayName(Type type)
+    {
+        return type.FullName ?? type.Name;
+    }
 }

src/EfCore.EncryptedProperties/Infrastructure/EncryptedPropertiesConventionSetPlugin.cs

@@ -11,15 +11,31 @@ namespace EfCore.EncryptedProperties.Infrastructure;
 
 internal sealed class EncryptedPropertiesConventionSetPlugin : IConventionSetPlugin
 {
+    private readonly IReadOnlyList<Type> _customValueSerializerTypes;
+
+    public EncryptedPropertiesConventionSetPlugin(IReadOnlyList<Type> customValueSerializerTypes)
+    {
+        _customValueSerializerTypes = customValueSerializerTypes;
+    }
+
     public ConventionSet ModifyConventions(ConventionSet conventionSet)
     {
-        conventionSet.ModelFinalizingConventions.Insert(0, new EncryptedPropertiesStorageConvention());
+        conventionSet.ModelFinalizingConventions.Insert(
+            0,
+            new EncryptedPropertiesStorageConvention(_customValueSerializerTypes));
         return conventionSet;
     }
 }
 
 internal sealed class EncryptedPropertiesStorageConvention : IModelFinalizingConvention
 {
+    private readonly IReadOnlyList<Type> _customValueSerializerTypes;
+
+    public EncryptedPropertiesStorageConvention(IReadOnlyList<Type> customValueSerializerTypes)
+    {
+        _customValueSerializerTypes = customValueSerializerTypes;
+    }
+
     public void ProcessModelFinalizing(
         IConventionModelBuilder modelBuilder,
         IConventionContext<IConventionModelBuilder> context)
@@ -126,7 +142,7 @@ private static void ApplyEncryptedAttribute(IConventionProperty property, Encryp
             .FirstOrDefault();
     }
 
-    private static void ConfigureCiphertextStorage(IConventionEntityType entityType, IConventionProperty plaintextProperty)
+    private void ConfigureCiphertextStorage(IConventionEntityType entityType, IConventionProperty plaintextProperty)
     {
         if (plaintextProperty.IsKey()
             || plaintextProperty.IsForeignKey()
@@ -235,7 +251,7 @@ private static string GetConfiguredMaterializationMode(IConventionEntityType ent
             $"Encrypted property '{GetPropertyDisplayName(entityType, property)}' has invalid materialization mode '{materialization}'. Supported modes are '{EncryptedPropertyTypeSupport.DecryptOnReadMaterialization}' and '{EncryptedPropertyTypeSupport.LazyMaterialization}'.");
     }
 
-    private static void ValidateEncryptedProperty(
+    private void ValidateEncryptedProperty(
         IConventionEntityType entityType,
         IConventionProperty property,
         string materialization)
@@ -264,10 +280,10 @@ private static void ValidateEncryptedProperty(
             plaintextType = property.ClrType;
         }
 
-        if (!EncryptedPropertyTypeSupport.IsSupportedPlaintextType(plaintextType))
+        if (!EncryptedPropertyTypeSupport.IsSupportedPlaintextType(plaintextType, _customValueSerializerTypes))
         {
             throw new InvalidOperationException(
-                $"Encrypted property '{GetPropertyDisplayName(entityType, property)}' has unsupported CLR type '{GetTypeDisplayName(plaintextType)}'. Supported encrypted property types are {EncryptedPropertyTypeSupport.SupportedTypesDescription}.");
+                $"Encrypted property '{GetPropertyDisplayName(entityType, property)}' has unsupported CLR type '{GetTypeDisplayName(plaintextType)}'. Supported encrypted property types are {EncryptedPropertyTypeSupport.SupportedTypesDescriptionWithCustomSerializers}.");
         }
     }
 

src/EfCore.EncryptedProperties/Infrastructure/EncryptedPropertiesDbContextOptionsExtension.cs

@@ -1,3 +1,4 @@
+using EfCore.EncryptedProperties.Configuration;
 using Microsoft.EntityFrameworkCore.Infrastructure;
 using Microsoft.EntityFrameworkCore.Metadata.Conventions.Infrastructure;
 using Microsoft.Extensions.DependencyInjection;
@@ -11,15 +12,20 @@ internal sealed class EncryptedPropertiesDbContextOptionsExtension : IDbContextO
     public EncryptedPropertiesDbContextOptionsExtension(IServiceProvider applicationServiceProvider)
     {
         ApplicationServiceProvider = applicationServiceProvider;
+        CustomValueSerializerTypes = applicationServiceProvider
+            .GetRequiredService<EncryptedPropertiesOptions>()
+            .CustomValueSerializerTypes;
     }
 
     internal IServiceProvider ApplicationServiceProvider { get; }
+    internal IReadOnlyList<Type> CustomValueSerializerTypes { get; }
 
     public DbContextOptionsExtensionInfo Info => _info ??= new ExtensionInfo(this);
 
     public void ApplyServices(IServiceCollection services)
     {
-        services.AddSingleton<IConventionSetPlugin, EncryptedPropertiesConventionSetPlugin>();
+        services.AddSingleton<IConventionSetPlugin>(
+            new EncryptedPropertiesConventionSetPlugin(CustomValueSerializerTypes));
         services.AddScoped<EncryptedPropertyStateTracker>();
     }
 
@@ -29,22 +35,35 @@ public void Validate(IDbContextOptions options)
 
     private sealed class ExtensionInfo : DbContextOptionsExtensionInfo
     {
-        public ExtensionInfo(IDbContextOptionsExtension extension) : base(extension)
+        private readonly EncryptedPropertiesDbContextOptionsExtension _extension;
+
+        public ExtensionInfo(EncryptedPropertiesDbContextOptionsExtension extension) : base(extension)
         {
+            _extension = extension;
         }
 
         public override bool IsDatabaseProvider => false;
         public override string LogFragment => "using EncryptedProperties ";
 
         public override int GetServiceProviderHashCode()
-            => 0;
+        {
+            var hash = new HashCode();
+            foreach (var type in _extension.CustomValueSerializerTypes)
+                hash.Add(type.AssemblyQualifiedName, StringComparer.Ordinal);
+
+            return hash.ToHashCode();
+        }
 
         public override bool ShouldUseSameServiceProvider(DbContextOptionsExtensionInfo other)
-            => other is ExtensionInfo;
+            => other is ExtensionInfo otherInfo
+                && _extension.CustomValueSerializerTypes.SequenceEqual(otherInfo._extension.CustomValueSerializerTypes);
 
         public override void PopulateDebugInfo(IDictionary<string, string> debugInfo)
         {
             debugInfo["EncryptedProperties:Enabled"] = "true";
+            debugInfo["EncryptedProperties:CustomValueSerializers"] = string.Join(
+                ",",
+                _extension.CustomValueSerializerTypes.Select(type => type.AssemblyQualifiedName));
         }
     }
 }

src/EfCore.EncryptedProperties/Metadata/EncryptedPropertyModelBuilder.cs

@@ -46,7 +46,8 @@ public static EncryptedPropertyModel Build(IModel model)
                     {
                         Purpose = purpose,
                         EntityTypeName = entityType.ClrType.FullName!,
-                        PropertyName = propertyName
+                        PropertyName = propertyName,
+                        PlaintextType = innerType
                     },
                     DefaultValue = GetDefaultValue(innerType),
                     Accessors = EncryptedPropertyAccessors.Create(entityType.ClrType, propertyName, mode)

src/EfCore.EncryptedProperties/Metadata/EncryptedPropertyTypeSupport.cs

@@ -11,6 +11,22 @@ public static bool IsEncryptedValueType(Type type)
     }
 
     public static bool IsSupportedPlaintextType(Type type)
+    {
+        return IsBuiltInPlaintextType(type);
+    }
+
+    public static bool IsSupportedPlaintextType(
+        Type type,
+        IReadOnlyCollection<Type> customValueSerializerTypes)
+    {
+        if (IsBuiltInPlaintextType(type))
+            return true;
+
+        var serializerType = Nullable.GetUnderlyingType(type) ?? type;
+        return customValueSerializerTypes.Contains(serializerType);
+    }
+
+    public static bool IsBuiltInPlaintextType(Type type)
     {
         var nullableType = Nullable.GetUnderlyingType(type);
         if (nullableType is not null)
@@ -31,6 +47,9 @@ public static bool IsSupportedPlaintextType(Type type)
     public static string SupportedTypesDescription =>
         "string, byte[], bool, numeric primitive types, decimal, DateTime, DateTimeOffset, Guid, enums, and nullable value-type variants";
 
+    public static string SupportedTypesDescriptionWithCustomSerializers =>
+        SupportedTypesDescription + ", or types registered with WithValueSerializer<TValue>()";
+
     private static bool IsSupportedNonNullablePlaintextType(Type type)
     {
         return type == typeof(bool)

src/EfCore.EncryptedProperties/Serialization/ICustomValueSerializer.cs

@@ -0,0 +1,27 @@
+namespace EfCore.EncryptedProperties.Serialization;
+
+internal interface ICustomValueSerializer
+{
+    byte[] Serialize(object value);
+    object? Deserialize(byte[] data);
+}
+
+internal sealed class CustomValueSerializer<TValue> : ICustomValueSerializer
+{
+    private readonly IEncryptedPropertyValueSerializer<TValue> _serializer;
+
+    public CustomValueSerializer(IEncryptedPropertyValueSerializer<TValue> serializer)
+    {
+        _serializer = serializer;
+    }
+
+    public byte[] Serialize(object value)
+    {
+        return _serializer.Serialize((TValue)value);
+    }
+
+    public object? Deserialize(byte[] data)
+    {
+        return _serializer.Deserialize(data);
+    }
+}