fle-dotnet

name	fle-dotnet
summary	Field-Level Encryption with the Couchbase .NET SDK — CryptoManager setup, [EncryptedField] attribute, encrypting and decrypting document fields
description	Field-Level Encryption with the Couchbase .NET SDK — CryptoManager setup, [EncryptedField] attribute, encrypting and decrypting document fields
compatibility	.NET SDK 3.x. Couchbase.Extensions.Encryption NuGet package required.
metadata	{"last_verified":"2026-05","min_server_version":"6.0","handoff":[{"condition":"user asks about FLE concepts or supported SDKs","skill":"fle"},{"condition":"user asks about connection setup","skill":"server-connection-dotnet"}]}

Field-Level Encryption — .NET

Setup

dotnet add package Couchbase.Extensions.Encryption

Configure CryptoManager

using Couchbase;
using Couchbase.Encryption;
using Couchbase.Encryption.Attributes;

var keyBytes = new byte[64]; // 64-byte key for AES-256
var keyring = new InsecureKeyring(new Key("my-key-id", keyBytes));
var provider = new AeadAes256CbcHmacSha512Provider(keyring);

var cryptoManager = DefaultCryptoManager.Builder()
    .DefaultEncrypter(provider.EncrypterForKey("my-key-id"))
    .Decrypter(provider.Decrypter())
    .Build();

var cluster = await Cluster.ConnectAsync("couchbase://localhost",
    new ClusterOptions()
        .WithCredentials("username", "Password!123")
        .WithCryptoManager(cryptoManager));

var collection = await cluster.BucketAsync("myapp")
    .ContinueWith(b => b.Result.DefaultCollectionAsync().Result);

Encrypting Fields with [EncryptedField] Attribute

using Couchbase.Encryption.Attributes;

public class UserDocument
{
    public string Name { get; set; }

    [EncryptedField(KeyName = "my-key-id")]
    public string Ssn { get; set; }

    [EncryptedField(KeyName = "my-key-id")]
    public string CreditCard { get; set; }
}

// Write
var user = new UserDocument
{
    Name = "Alice",
    Ssn = "123-45-6789",
    CreditCard = "4111111111111111"
};
await collection.UpsertAsync("user::alice", user);

// Read — decryption is automatic
var result = await collection.GetAsync("user::alice");
var doc = result.ContentAs<UserDocument>();
Console.WriteLine(doc.Ssn); // "123-45-6789"

Limitations

• Encrypted fields cannot be indexed or queried with SQL++
• Adds ~30% overhead to encrypted field size
• See fle for full concept reference