Macoev.MongoDB.EncryptionLib

A .NET library for simplified MongoDB Client-Side Field Level Encryption (CSFLE).

This library provides a high-level abstraction for managing MongoDB encryption, supporting both Automatic Encryption (for MongoDB Enterprise and Atlas) and Explicit Encryption (for MongoDB Community Edition).

Features

• Automatic Encryption Support: Integration with MongoDB Enterprise/Atlas auto-encryption.
• Explicit Encryption Support: Manual field-level encryption for Community Edition.
• POCO Attribute-based Encryption: Use attributes to mark fields for encryption.
• KMS Provider Configuration: Easily configure Key Management Service (KMS) providers.
• JSON Schema Generation: Automatically generate encryption schemas from your C# classes.

Installation

Install the package via NuGet:

dotnet add package Macoev.MongoDB.EncryptionLib

Basic Usage

1. Define your Entity

Use the EncryptedField attribute to mark properties that need encryption.

using Macoev.MongoDB.EncryptionLib.Attributes;

public class UserProfile
{
    public Guid Id { get; set; }
    
    public string Name { get; set; } = string.Empty;

    [EncryptedField]
    public string Email { get; set; } = string.Empty;

    [EncryptedField]
    public string SocialSecurityNumber { get; set; } = string.Empty;
}

2. Configure Encryption Settings

using Macoev.MongoDB.EncryptionLib;
using MongoDB.Driver;

var kmsProviders = new Dictionary<string, IReadOnlyDictionary<string, object>>
{
    { "local", new Dictionary<string, object> { { "key", Convert.FromBase64String("YOUR_LOCAL_KEY_HERE") } } }
};

var keyVaultNamespace = CollectionNamespace.FromFullName("encryption.keyVault");

var encryptionSettings = new MongoEncryptionSettings(kmsProviders, keyVaultNamespace);

3. Initialize and Create Client

string connectionString = "mongodb://localhost:27001";
encryptionSettings.SetConnectionString(connectionString);

// Create or retrieve the Data Encryption Key (DEK)
var dataKeyId = await encryptionSettings.GetOrCreateDataKeyAsync(connectionString);
encryptionSettings.SetDataKeyId(dataKeyId);

// Check if the server supports auto-encryption
var details = await encryptionSettings.GetConnectionDetailsAsync(connectionString);
encryptionSettings.SetAutoEncryptionSupport(details.IsEnterprise);

// Create the encrypted MongoClient
var client = encryptionSettings.CreateEncryptedClient(connectionString);

4. Manual Encryption (Community Edition)

If you are using MongoDB Community Edition, you can encrypt your entities before saving them:

var user = new UserProfile { Name = "John Doe", Email = "john@example.com" };
var encryptedDoc = await encryptionSettings.EncryptEntityAsync(user);

var database = client.GetDatabase("test");
var collection = database.GetCollection<BsonDocument>("users");
await collection.InsertOneAsync(encryptedDoc);

Environment Variables

• MONGODB_CRYPT_SHARED_LIB_PATH: Path to the mongo_crypt_v1 shared library. If not set, it defaults to common system paths.

License

This project is licensed under the MIT License.