PenguinConverters.Keyra.Core 3.3.5

PenguinConverters.Keyra.Core

Core abstractions and interfaces for the Keyra secret vault system.

Overview

Keyra.Core defines the foundational interfaces and base classes for secret management, key storage, and authentication. It is designed to be provider-agnostic, allowing different implementations for key storage (DPAPI-NG, AES-GCM, HSM) and secret storage (Directory, Database, Cloud).

┌─────────────────────────────────────────────────────────────────────┐
│                         Keyra.Core                                  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────┐ │
│  │    Entities     │  │ KeyStorageProvider│  │SecretStorageProvider│ │
│  │                 │  │                 │  │                     │ │
│  │ • IVault        │  │ • IKey          │  │ • IProvider         │ │
│  │ • ISecret       │  │ • IProvider     │  │ • IConfiguration    │ │
│  │ • IFolder       │  │ • IConfiguration│  │                     │ │
│  │ • IAuthenticity │  │                 │  │                     │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────────┘ │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                     Authentication                           │   │
│  │                                                              │   │
│  │  • IKeyAuthenticator      • IChainableAuthenticator         │   │
│  │  • IKeyCredential         • IAuthenticatorChain             │   │
│  │  • AuthenticatorType      • AuthenticatorConfiguration      │   │
│  │  • VaultKeyProtection                                       │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Package Information

Core Concepts

Vault

A vault is a container for secrets, protected by an encryption key.

┌─────────────────────────────────────────────────────────────┐
│                          Vault                               │
│                                                              │
│  Name: "Production"                                          │
│  Created: 2025-01-19                                         │
│  Identifier: "vaults/production"                             │
│                                                              │
│  ┌─────────────┐    ┌────────────────────────────────────┐  │
│  │     Key     │    │            Secrets                  │  │
│  │             │    │                                     │  │
│  │ AES-256-GCM │    │  ┌─────────┐ ┌─────────┐           │  │
│  │ Id: keyra.  │    │  │db-pass  │ │api-key  │  ...      │  │
│  │  abc123...  │    │  └─────────┘ └─────────┘           │  │
│  └─────────────┘    └────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                       Folders                           │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐              │ │
│  │  │ servers  │  │ services │  │ users    │              │ │
│  │  └──────────┘  └──────────┘  └──────────┘              │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Secret

A secret stores encrypted sensitive data with metadata.

public interface ISecret
{
    string Name { get; }
    string? Username { get; }
    string? Value { get; }           // Encrypted ciphertext
    DateTimeOffset Created { get; }
    IAuthenticity Authenticity { get; }
    IKey Key { get; }

    bool TrySetValue(string plaintext);  // Encrypts and stores
    string? TryGetValue();               // Decrypts and returns
}

Key Storage Provider

Abstraction for encryption key management.

┌─────────────────────────────────────────────────────────────┐
│                  IKeyStorageProvider                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  GenerateKey()        → Creates new encryption key          │
│  LoadKey(identifier)  → Loads existing key                  │
│  SaveKey(key)         → Persists key to storage             │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Implementations:                                           │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  DPAPI-NG   │  │   AES-GCM   │  │     HSM     │         │
│  │  (File)     │  │  (Windows)  │  │  (Hardware) │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Secret Storage Provider

Abstraction for secret persistence.

┌─────────────────────────────────────────────────────────────┐
│                ISecretStorageProvider                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  SaveSecret(secret)    → Persists encrypted secret          │
│  LoadSecret(name)      → Retrieves secret                   │
│  DeleteSecret(name)    → Removes secret                     │
│  ListSecrets()         → Enumerates all secrets             │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Implementations:                                           │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Directory  │  │  Database   │  │    Cloud    │         │
│  │  (Files)    │  │  (SQL)      │  │  (Azure/AWS)│         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

Authentication System

Authenticator Types

public enum AuthenticatorType
{
    None = 0,          // Certificate Store (no password)
    Password = 1,      // Password-based
    YubiKey = 2,       // YubiKey HMAC-SHA1
    WindowsHello = 3,  // Biometric/PIN
    SmartCard = 4      // PIV smart card
}

Single Authenticator (Legacy)

public interface IKeyAuthenticator
{
    string DisplayName { get; }
    AuthenticatorType Type { get; }
    bool IsAvailable { get; }

    Task<IKeyCredential?> AuthenticateAsync(string vaultName, bool isNewCredential);
}

Authenticator Chain (v2)

Multiple authenticators can be chained for defense-in-depth.

The chain is recipe-driven (see docs/crypto-primitives.md §3): authenticators only collect inputs; the derivation itself is a KDF recipe built by KdfRecipeFactory.ForChain and executed once by the Rust engine (keyra_ffi_recipe_execute).

┌─────────────────────────────────────────────────────────────────┐
│              Authenticator Chain (recipe-driven)                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Initial Challenge (32 bytes random, keyprotection.json)  │   │
│  └────────────────────────┬────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Passwords (0..n) — input password[i] (UTF-16LE)          │   │
│  │   Argon2id(password[i], salt=challenge‖LE32(i),          │   │
│  │            m=64 MiB, t=3, p=1) per password              │   │
│  │   → xor_combine (ordered: position i has its own salt)   │   │
│  └────────────────────────┬────────────────────────────────┘   │
│                           │  running material                   │
│                           ▼                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ YubiKeys (0..m, sequential by order) — input hw[j]       │   │
│  │   Device: HMAC-SHA1 challenge-response over the          │   │
│  │           running material (20-byte response)            │   │
│  │   Recipe: hkdf_sha256(ikm=hw[j], salt=running,           │   │
│  │           info="KeyraYubiKeyDerivedKey.v2")              │   │
│  └────────────────────────┬────────────────────────────────┘   │
│                           │                                     │
│  Active Directory: pass-through — contributes NO key            │
│  material (its factor is the DPAPI-NG protection descriptor)    │
│                           │                                     │
│                           ▼                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Final: hmac_sha256(running, "KeyraVaultKey")             │   │
│  │ Output: 32 B → Base64 → key storage provider password    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Empty chain:        HMAC(SHA256(challenge), "KeyraVaultKey")   │
│  AD-only (passthru): HMAC(challenge, "KeyraVaultKey")           │
└─────────────────────────────────────────────────────────────────┘

IChainableAuthenticator Interface

public interface IChainableAuthenticator
{
    string AuthenticatorId { get; }    // e.g., "yubikey-12345678-slot1"
    string DisplayName { get; }        // e.g., "YubiKey 12345678 (Slot 1)"
    AuthenticatorType Type { get; }
    int Order { get; set; }            // Position in chain
    bool IsAvailable { get; }

    // Core method: collect this authenticator's raw KDF-recipe input (password bytes,
    // hardware device response, or ChainInput.None for a pass-through). The chain executes
    // the vault's stored kdfRecipe over the collected inputs through the single Rust
    // recipe interpreter — authenticators never derive key material themselves (issue #48).
    Task<ChainInput?> CollectInputAsync(byte[] chainChallenge, bool isNewCredential,
        ICredentialProvider? credentialProvider);

    // Serialization
    AuthenticatorConfiguration GetConfiguration();
    void LoadConfiguration(AuthenticatorConfiguration configuration);
}

VaultKeyProtection Storage Format

Version 2 format supporting authenticator chains:

{
  "version": 2,
  "initialChallenge": "base64-encoded-32-bytes...",
  "authenticators": [
    {
      "type": 1,
      "order": 0,
      "authenticatorId": "password",
      "parameters": {}
    },
    {
      "type": 2,
      "order": 1,
      "authenticatorId": "yubikey-12345678-slot1",
      "parameters": {
        "serialNumber": "12345678",
        "slot": "1",
        "challenge": "base64-encoded-challenge..."
      }
    }
  ]
}

Migration from v1

The system automatically migrates legacy single-authenticator format:

┌─────────────────────────┐         ┌─────────────────────────────┐
│  Version 1 (Legacy)     │         │     Version 2 (Chain)       │
├─────────────────────────┤         ├─────────────────────────────┤
│                         │         │                             │
│ {                       │ ──────► │ {                           │
│   "authenticatorType":1,│ Migrate │   "version": 2,             │
│   "yubiKeyChallenge":...│         │   "initialChallenge": ...,  │
│ }                       │         │   "authenticators": [...]   │
│                         │         │ }                           │
└─────────────────────────┘         └─────────────────────────────┘

Interface Extensions

IExportable / IImportable

public interface IExportable
{
    Package Export(IKey key);
}

public interface IImportable
{
    void Import(Package package, IKey key);
}

IPersistable

public interface IPersistable
{
    void Save(string path);
    void Load(string path);
}

IGitConfiguration

public interface IGitConfiguration
{
    bool IsAllowedByPolicy { get; }
    string? DefaultRemote { get; }
    bool AutoCommit { get; }
}

JSON Converters

Custom JSON converters for serialization:

Usage Example

using PenguinConverters.Keyra.Core;
using PenguinConverters.Keyra.Core.Entities;
using PenguinConverters.Keyra.Core.Authentication;

// Create a vault with authentication chain
VaultKeyProtection protection = VaultKeyProtection.ForChain(
    initialChallenge: RandomBytes(32),
    authenticators: new List<AuthenticatorConfiguration>
    {
        new() { Type = AuthenticatorType.Password, Order = 0, AuthenticatorId = "password" },
        new() { Type = AuthenticatorType.YubiKey, Order = 1, AuthenticatorId = "yubikey-123-slot1" }
    }
);

// Create vault
Vault vault = new Vault
{
    Name = "MyVault",
    Created = DateTimeOffset.UtcNow,
    Identifier = "vaults/myvault"
};

// Add a secret — value crypto runs through the vault's cipher, never the key itself
Secret secret = new Secret
{
    Name = "database-password",
    Username = "admin",
    Cipher = vault.Cipher
};

secret.TrySetValue("SuperSecretPassword123!");

NuGet Installation

dotnet add package PenguinConverters.Keyra.Core

License

Proprietary - PenguinConverters