PenguinConverters.Keyra.KeyStorageProvider.DpapiNg 3.3.5

PenguinConverters.Keyra.KeyStorageProvider.DpapiNg

DPAPI-NG based KeyStorageProvider using AES-256-GCM encryption for Keyra vaults.

Overview

This provider uses Windows Data Protection API - Next Generation (DPAPI-NG) for protecting AES-256 encryption keys. It provides authenticated encryption with AES-GCM and supports the Keyra authenticator chain for multi-factor key protection.

┌─────────────────────────────────────────────────────────────────┐
│                 DPAPI-NG Key Protection Flow                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  AES-256 Key (32 bytes)                                         │
│        │                                                        │
│        ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Password factor (optional - provider property)           │   │
│  │  • Chain credential (KDF recipe: Argon2id/HKDF/HMAC)     │   │
│  │  • Argon2id KEK derived in the Rust engine               │   │
│  │  • AES key XOR KEK before DPAPI-NG protection            │   │
│  └─────────────────────────────────────────────────────────┘   │
│        │                                                        │
│        ▼                                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ DPAPI-NG (NCryptProtectSecret)                           │   │
│  │  • SID-based protection descriptor                       │   │
│  │  • Tied to Windows user/machine                          │   │
│  │  • TPM-backed when available                             │   │
│  └─────────────────────────────────────────────────────────┘   │
│        │                                                        │
│        ▼                                                        │
│  Protected Key Blob (unified .key file)                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Package Information

AES-256-GCM Encryption

Secrets are encrypted using AES-256 in GCM (Galois/Counter Mode) for authenticated encryption.

┌─────────────────────────────────────────────────────────────────┐
│                   AES-GCM Security Parameters                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Key Size:    256 bits (32 bytes) - AES-256                     │
│  Nonce Size:  96 bits (12 bytes)  - Optimal for GCM             │
│  Tag Size:    128 bits (16 bytes) - Maximum integrity           │
│                                                                 │
│  Ciphertext Format:                                             │
│  ┌──────────┬───────────────────────┬──────────┐               │
│  │  Nonce   │      Ciphertext       │   Tag    │               │
│  │ 12 bytes │      (variable)       │ 16 bytes │               │
│  └──────────┴───────────────────────┴──────────┘               │
│                                                                 │
│  CRITICAL: Nonce is generated randomly for EACH encryption      │
│            using RandomNumberGenerator (cryptographically       │
│            secure) to ensure uniqueness.                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Generation

The provider supports extensible key generation through the IKeyGenerator interface.

┌─────────────────────────────────────────────────────────────────┐
│                    Key Generation System                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  IKeyGenerator Interface:                                       │
│  ├── DisplayName      (UI display)                              │
│  ├── Description      (User-facing description)                 │
│  ├── RequiresUserInput (needs UI interaction?)                  │
│  ├── KeySizeBytes     (32 for AES-256)                          │
│  └── GenerateKey()    (returns 32-byte key)                     │
│                                                                 │
│  Built-in Generators:                                           │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ RandomKeyGenerator (default)                             │   │
│  │  • Uses RandomNumberGenerator.Create()                   │   │
│  │  • Cryptographically secure random bytes                 │   │
│  │  • No user input required                                │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Future extensibility:                                          │
│  • PasswordDerivedKeyGenerator (Argon2id from user password)   │
│  • HardwareDerivedKeyGenerator (TPM/HSM integration)           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

DPAPI-NG Protection Descriptors

┌─────────────────────────────────────────────────────────────────┐
│                  Protection Descriptor Options                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Current User (default):                                        │
│    "SID=S-1-5-21-..."                                           │
│    Only the current user can decrypt                            │
│                                                                 │
│  Local Machine:                                                 │
│    "LOCAL=machine"                                              │
│    Any user on this machine can decrypt                         │
│                                                                 │
│  Multiple Users/Groups:                                         │
│    "SID=S-1-5-21-... OR SID=S-1-5-21-..."                       │
│    Any of the specified SIDs can decrypt                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Storage Format

Key File (unified .key)

All key storage providers share the unified .key extension. The owning provider is identified by the providerTypeId field, never by the file name.

{
  "keyId": "keyra.a1b2c3d4e5f67890...",
  "protectedBlob": "BASE64_ENCODED_DPAPI_NG_BLOB",
  "createdUtc": "2025-01-20T12:00:00Z",
  "algorithm": "AES-256-GCM",
  "version": 1,
  "providerTypeId": "dpapi-ng"
}

Encrypted Secret (Base64)

[Nonce: 12 bytes][Ciphertext: variable][Tag: 16 bytes]

Usage

Creating a New Key

using PenguinConverters.Keyra.KeyStorageProvider.DpapiNg;

// Create provider
Provider provider = new Provider
{
    Identifier = @"C:\Vaults\production"
};

// Generate key with authenticator chain password
SecureString password = await authenticatorChain.DeriveKeyAsync(isNew: true);
IKey key = provider.GenerateKey(password);

// Key is now protected and stored as a unified .key file

Loading an Existing Key

// Load key using authenticator chain
SecureString password = await authenticatorChain.DeriveKeyAsync(isNew: false);
IKey key = provider.FindKeyByIdentifier("keyra.a1b2c3d4...", password);

Encrypting/Decrypting Secrets

// Encrypt a secret
SecureString plaintext = "my-secret-value".ToSecureString();
string ciphertext = key.Encrypt(plaintext);  // Base64 output

// Decrypt a secret
SecureString decrypted = key.Decrypt(ciphertext);

Security Considerations

Nonce Management

• CRITICAL: Never reuse a nonce with the same key
• RandomNumberGenerator ensures cryptographic randomness
• 2^96 possible nonces makes collision extremely unlikely

Key Protection Layers

1. DPAPI-NG: Windows-managed protection tied to user/machine
2. Authenticator Chain: Multi-factor XOR protection (Password, YubiKey)
3. Memory Clearing: Keys zeroed on Dispose using CryptographicOperations.ZeroMemory

Authentication Tag

• 128-bit tag provides maximum GCM integrity protection
• Any tampering with ciphertext will cause decryption to fail

Project Structure

PenguinConverters.Keyra.KeyStorageProvider.DpapiNg/
├── Provider.cs              # IProvider implementation
├── Key.cs                   # IKey with AES-GCM encrypt/decrypt
├── Configuration.cs         # Provider settings
├── ProviderBuilder.cs       # Builder pattern
├── AesGcmCrypto.cs          # AES-GCM helpers
├── DpapiNgProtection.cs     # DPAPI-NG + password protection
├── KeyMetadata.cs           # unified .key file structure
└── Generators/
    └── RandomKeyGenerator.cs  # Default key generator

Comparison with the AES-GCM Provider

License

Proprietary - PenguinConverters