BNN.KeyKet 1.0.2

KeyKet

Class library for hardware-backed cryptographic operations — TPM 2.0 and USB Token (PKCS#11) behind a single interface

Quick start

IKeyKetManager manager = KeyKetFactory.Create(new KeyKetOptions
{
    Provider      = KeyKetProviderType.Tpm,
    RootPath      = "/var/myapp",   // optional — defaults to AppData
    RsaKeyAccount = "device-001"
});

// or USB Token
IKeyKetManager manager = KeyKetFactory.Create(new KeyKetOptions
{
    Provider      = KeyKetProviderType.UsbToken,
    Pkcs11LibPath = "/usr/lib/softhsm/libsofthsm2.so",
    TokenSerial   = "ABC123",
    Pin           = "1234"
});

manager.Dispose(); // always dispose when done

Dependency Injection

Fixed provider (most common)

builder.Services.AddSingleton<IKeyKetManager>(_ =>
    KeyKetFactory.Create(new KeyKetOptions
    {
        Provider      = KeyKetProviderType.Tpm,
        RsaKeyAccount = "device-001"
    }));

Runtime-switchable provider

When you need to swap hardware without restarting, use SwitchableKeyKetManager. Register under both names — both resolve to the same singleton instance.

// Line 1: create the instance, register under concrete type
//         so any controller/service that needs SwitchTo() can inject this directly
builder.Services.AddSingleton<SwitchableKeyKetManager>(_ =>
    new SwitchableKeyKetManager(new KeyKetOptions
    {
        Provider      = KeyKetProviderType.Tpm,
        RsaKeyAccount = "device-001"
    }));

// Line 2: alias IKeyKetManager → same instance (no second object created)
//         ordinary services inject IKeyKetManager and never need to know about switching
builder.Services.AddSingleton<IKeyKetManager>(sp =>
    sp.GetRequiredService<SwitchableKeyKetManager>());

// Regular service — inject by interface, unaware of hardware details
public class SigningService(IKeyKetManager manager) { ... }

// Admin endpoint — inject concrete type to access SwitchTo()
[HttpPost("admin/switch")]
public IActionResult Switch(
    [FromServices] SwitchableKeyKetManager manager,
    [FromBody] KeyKetOptions options)
{
    manager.SwitchTo(options);                       // atomic swap, old instance auto-disposed
    return Ok(manager.CurrentProvider.ToString());
}

SwitchTo() uses Interlocked.Exchange — pointer swap is atomic.
Requests in flight at the moment of switch may receive an error — this is accepted behaviour.

Both providers simultaneously (.NET 8 keyed services)

builder.Services.AddKeyedSingleton<IKeyKetManager>("tpm",
    (_, _) => KeyKetFactory.Create(tpmOptions));
builder.Services.AddKeyedSingleton<IKeyKetManager>("usb",
    (_, _) => KeyKetFactory.Create(usbOptions));

public class MyService(
    [FromKeyedServices("tpm")] IKeyKetManager tpm,
    [FromKeyedServices("usb")] IKeyKetManager usb) { }

Always register as Singleton. TPM handles and PKCS#11 sessions are stateful hardware resources — never create per-request.

Return type

All methods return KeyKetCommonResult. Always check Success before using Data.

public class KeyKetCommonResult
{
    public string Data    { get; set; }   // result value when successful
    public string Error   { get; set; }   // error message when failed
    public bool   Success => Error == null;
}

var result = manager.GenerateAndGetPublicKey();
if (!result.Success)
    throw new Exception(result.Error);

string publicKey = result.Data;

API reference

GetDeviceUserSerial()

Returns a stable unique identifier for the current machine.

GenerateAndGetPublicKey()

Generates an RSA 2048 key pair on the hardware device if one does not exist, then returns the public key. Safe to call multiple times — only generates once.

Send Data to your server so the server can encrypt SAD keys for this device.

CreateJWT(Dictionary<string, string> payload)

Creates a signed RS256 JWT using the device's own key pair.

SignSAD(byte[] encryptedKey, byte[] iv, byte[] blob, string sad)

Decrypts the SAD private key using the hardware device, then uses it to sign sad. The decrypted key is disposed immediately after signing.

CreateCSR(byte[] encryptedKey, byte[] iv, byte[] blob, string subjectName)

Decrypts the SAD private key (same mechanism as SignSAD) and creates a PKCS#10 Certificate Signing Request.

Submit Data to your CA to receive a signed certificate.