HashiCorp Vault Key Store

The Vault key store persists encryption keys in HashiCorp Vault using the KV v2 secrets engine. It is the recommended choice for organizations that already use Vault for centralized secrets management and need enterprise-grade audit trails.

Installation

dotnet CLI

dotnet add package Tayra.KeyStore.Vault

Package Manager

Install-Package Tayra.KeyStore.Vault

Basic Setup

The simplest registration uses token authentication:

var services = new ServiceCollection();

// Use HashiCorp Vault with token authentication
services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UseVaultKeyStore(
        vaultAddress: "https://vault.example.com:8200",
        token: "hvs.your-vault-token");

^anchor

Configuration Options

Use the options overload to customize paths and retry behavior:

var services = new ServiceCollection();

services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UseVaultKeyStore(
        vaultAddress: "https://vault.example.com:8200",
        token: "hvs.your-vault-token",
        options =>
        {
            // KV v2 mount point (default: "secret")
            options.MountPoint = "secret";

            // Path prefix within the KV mount (default: "tayra/keys")
            options.PathPrefix = "myapp/encryption-keys";

            // Maximum number of retries for transient errors (default: 3)
            options.MaxRetries = 5;

            // Base delay for exponential backoff on retries (default: 100ms)
            options.RetryBaseDelay = TimeSpan.FromMilliseconds(200);
        });

^anchor

Options Reference

Property	Type	Default	Description
VaultAddress	string?	null	The Vault server address (e.g., "https://vault.example.com:8200"). Required.
Token	string?	null	Authentication token. Used with token-based auth.
MountPoint	string	"secret"	KV v2 mount point in Vault.
PathPrefix	string	"tayra"	Path prefix within the KV mount for storing keys.
MaxRetries	int	3	Maximum number of retries for transient errors.
RetryBaseDelay	TimeSpan	100ms	Base delay for exponential backoff on retries.

Pre-configured Vault Client

If you already have a VaultSharp.IVaultClient configured (e.g., with AppRole or Kubernetes auth), pass it directly:

var services = new ServiceCollection();

// Pass a pre-configured IVaultClient with your preferred auth method
var existingVaultClient = new VaultSharp.VaultClient(
    new VaultSharp.VaultClientSettings(
        "https://vault.example.com:8200",
        new VaultSharp.V1.AuthMethods.Token.TokenAuthMethodInfo("hvs.your-vault-token")));

services.AddTayra(opts => opts.LicenseKey = licenseKey)
    .UseVaultKeyStore(existingVaultClient, options =>
    {
        options.PathPrefix = "myapp/encryption-keys";
    });

^anchor

This is useful when your application uses a different Vault auth method or when you want to share a single client instance across services.

KV v2 Secrets Engine

Tayra stores each encryption key as a separate secret in the Vault KV v2 engine. The secret path follows this pattern:

{mount_point}/data/{path_prefix}/{key_id}

Component	Value	Source
mount_point	secret	MountPoint option (default: "secret")
data	data	Fixed — required by the Vault KV v2 API to distinguish data from metadata operations
path_prefix	tayra	PathPrefix option (default: "tayra")
key_id	user-123:personal	The Tayra key identifier

For example, with the default settings and a key ID of user-123:personal, the secret is stored at:

secret/data/tayra/user-123:personal

The secret contains a single field key with the Base64-encoded AES-256 key bytes.

KV v2 Versioning

Vault KV v2 maintains version history for secrets. When Tayra deletes a key (crypto-shredding), the entire secret is destroyed -- not just the latest version. This ensures that previous versions of the key cannot be recovered.

Vault Policy Requirements

The Vault token must have the following capabilities on the key path:

path "secret/data/tayra/*" {
  capabilities = ["create", "read", "delete"]
}

path "secret/metadata/tayra/*" {
  capabilities = ["list", "delete"]
}

Adjust the path to match your MountPoint and PathPrefix settings. The metadata path is needed for ListKeyIdsAsync and full secret destruction during crypto-shredding.

Least Privilege

Grant only the capabilities listed above. Tayra does not need update (keys are immutable once stored) or sudo capabilities.

Token Renewal

Vault tokens have a TTL and must be renewed periodically. Tayra does not manage token lifecycle -- if your token expires, key store operations will fail.

For production deployments, consider:

• AppRole auth with periodic tokens that auto-renew via a Vault agent sidecar.
• Kubernetes auth if running on Kubernetes, which handles token injection and renewal automatically.
• Token wrapping for secure initial token delivery.

Pass a pre-configured IVaultClient with your preferred auth method rather than a raw token for long-running services.

Retry Logic

The Vault key store includes built-in retry logic with exponential backoff for transient HTTP errors. The backoff delay doubles on each attempt: for the default settings (base delay = 100ms, max retries = 3), the delays are approximately 100ms, 200ms, and 400ms.

See Also

• Key Stores Overview -- Comparison of all providers
• PostgreSQL Key Store -- Simpler alternative for PostgreSQL-based applications
• Azure Key Vault -- Cloud-native alternative for Azure
• Custom Key Store -- Build your own IKeyStore