ktsu.CredentialCache 1.3.25

ktsu.CredentialCache

A cross-platform credential cache for .NET that stores secrets in the host's native keyring.

Overview

CredentialCache keeps credentials in memory for fast lookup during the lifetime of a process and persists each one through an ICredentialStore whose default implementation delegates to the platform-native secret manager:

Each persona's credential is stored as its own entry in the OS keyring scoped by a service name — the library never writes a plaintext blob to disk.

Installation

dotnet add package ktsu.CredentialCache

Requires .NET 9 or .NET 10.

Linux runtime prerequisites

The Linux store requires libsecret and a running Secret Service implementation (gnome-keyring, KWallet's secret-service bridge, KeePassXC, …). On Debian/Ubuntu:

sudo apt-get install libsecret-1-0 gnome-keyring

On headless or CI hosts you'll typically need a session bus and an unlocked keyring — see the cross-platform.yml workflow in this repo for the dbus-run-session + gnome-keyring-daemon incantation. If a Secret Service isn't available in your deployment, fall back to InMemoryCredentialStore (or roll your own ICredentialStore).

Quick start

using ktsu.CredentialCache;
using ktsu.CredentialCache.Storage;
using ktsu.Semantics.Strings;

// Pick the platform-native store explicitly...
ICredentialStore store = CredentialStoreFactory.CreateDefault("MyApp");
using CredentialCache cache = new(store);

// ...or just use the singleton, which calls CreateDefault() on first access.
CredentialCache singleton = CredentialCache.Instance;

PersonaGUID persona = CredentialCache.CreatePersonaGUID();

cache.AddOrReplace(persona, new CredentialWithUsernamePassword
{
    Username = SemanticString<CredentialUsername>.Create("alice"),
    Password = SemanticString<CredentialPassword>.Create("hunter2"),
});

if (cache.TryGet(persona, out Credential? stored)
    && stored is CredentialWithUsernamePassword creds)
{
    Console.WriteLine($"Hello, {creds.Username}");
}

cache.Remove(persona);

Pick your own service name

CredentialStoreFactory.CreateDefault(serviceName) scopes entries by a logical service name (defaults to "ktsu.CredentialCache"). If two applications share a host, pass per-app names so their keyring entries don't collide.

Credential types

The library ships with three concrete Credential subclasses:

Adding your own credential type

Credential is a polymorphic record class round-tripped through System.Text.Json. New subclasses need a [JsonDerivedType] on the base so deserialization can resolve them:

// 1. Add the subclass.
public sealed class CredentialWithCertificate : Credential
{
    public string Thumbprint { get; init; } = "";
}

// 2. Register it on the base in Credential.cs.
[JsonDerivedType(typeof(CredentialWithCertificate), nameof(CredentialWithCertificate))]
public abstract class Credential { /* ... */ }

// 3. Optional: register a factory so TryCreate<T> works.
public sealed class CertificateFactory : ICredentialFactory<CredentialWithCertificate>
{
    public CredentialWithCertificate Create() => new();
}
cache.RegisterCredentialFactory(new CertificateFactory());

If a subclass uses SemanticString<T> properties, they round-trip through ktsu.RoundTripStringJsonConverter automatically.

Customising the backing store

ICredentialStore is a small CRUD interface (TryLoad / Save / Remove). Bring your own implementation when you need a different backend (HashiCorp Vault, an encrypted file, a test double):

public sealed class MyCustomStore : ICredentialStore { /* ... */ }

ICredentialStore store = new MyCustomStore();
CredentialCache.ConfigureStore(store); // must be called before first Instance access

For unit tests, use the in-memory store and skip the singleton entirely:

using CredentialCache cache = new(new InMemoryCredentialStore());

Enumerating stored personas

ICredentialStore deliberately has no EnumerateKeys method, because macOS Keychain and libsecret require substantially more native marshalling for enumeration than the simple key-value ops. The optional ISearchableCredentialStore interface adds it, and only the Windows and in-memory stores implement it:

if (cache.Store is ISearchableCredentialStore searchable)
{
    foreach (PersonaGUID key in searchable.EnumerateKeys())
    {
        // ...
    }
}
else
{
    // Track persona GUIDs yourself on macOS / Linux.
}

Platform notes

• Windows Credential Manager caps the credential blob at 2560 bytes (5 * 512). Tokens larger than that throw CredentialStoreException — split or compress before storing.
• macOS uses the user's default login keychain. The first access from an application prompts the user for permission, as with any keychain client.
• Linux requires libsecret-1 plus an active Secret Service. Headless CI agents typically have neither — use InMemoryCredentialStore there, or set up dbus-run-session + gnome-keyring-daemon as the cross-platform.yml workflow does.
• All native calls happen on the thread the API is invoked from. The library's in-memory cache is thread-safe (ConcurrentDictionary); the native APIs themselves are documented as thread-safe by their respective platform owners, but blocking calls (especially libsecret) are not cheap — treat Save / Remove as I/O, not as cheap accessors.

API summary

CredentialCache

ICredentialStore

ISearchableCredentialStore : ICredentialStore

Don't dispose the singleton

CredentialCache.Instance returns a process-wide singleton. Calling Dispose() on it (e.g. via using var c = CredentialCache.Instance;) puts the singleton in a disposed state and the next consumer in the process gets ObjectDisposedException. If you need disposal semantics, construct your own instance with new CredentialCache(store).

License

MIT — see LICENSE.md.