HashiCorpVaultLib 1.0.5

HashiCorp Vault Library for .NET

A simple and secure .NET library for retrieving secrets from HashiCorp Vault using AppRole authentication. Compatible with both .NET Framework and .NET Core/.NET 5+.

Features

• AppRole Authentication: Secure authentication using Role ID and Secret ID
• KV v2 Support: Automatically handles Vault KV version 2 API paths
• SSL Certificate Validation: Verifies SSL certificates by default; optional bypass for development environments
• Simple API: Easy-to-use static methods for common use cases
• Environment Variable Security: Secret ID is read from environment variables
• Error Handling: Comprehensive error handling with descriptive messages
• Strict Field Validation: Ensures correct field names in Vault secrets for reliability

Installation

Install the package via NuGet Package Manager:

dotnet add package HashiCorpVaultLib

Or via Package Manager Console:

Install-Package HashiCorpVaultLib

Prerequisites

Before using this library, you must set the VAULT_SECRET_ID environment variable:

Windows (Command Prompt):

set VAULT_SECRET_ID=your-secret-id-here

Windows (PowerShell):

$env:VAULT_SECRET_ID = "your-secret-id-here"

Linux/macOS:

export VAULT_SECRET_ID=your-secret-id-here

Important: If VAULT_SECRET_ID is not set, the application will terminate with exit code 777.

Usage

Retrieving Username and Password

Use this method when your Vault secret contains username and password fields.

⚠️ Required Field Names: Your Vault secret MUST contain fields named exactly username and password. Other field names will not work.

using HashiCorpVaultLib;

// Retrieve credentials from Vault (production - SSL verification enabled)
var (username, password) = VaultLib.GetUsernamePassword(
    vaultUrl: "https://vault.example.com:8200",
    roleId: "your-role-id",
    secretPath: "system_test/username_password",
    ignoreSslErrors: false  // Default - recommended for production
);

Console.WriteLine($"Username: {username}");
Console.WriteLine($"Password: {password}");

// Development mode - bypass SSL validation (use only for development!)
var (devUsername, devPassword) = VaultLib.GetUsernamePassword(
    vaultUrl: "https://vault-dev.example.com:8200",
    roleId: "dev-role-id",
    secretPath: "dev/database",
    ignoreSslErrors: true  // Only for development environments
);

Vault Secret Structure (username/password):

{
  "username": "admin",
  "password": "secure-password-123"
}

⚠️ Important: Field names are case-sensitive and must be exactly username and password. Using different names (e.g., user, userName, pass) will cause an error.

Retrieving Secret Text

Use this method when your Vault secret contains a secret_text field.

⚠️ Required Field Name: Your Vault secret MUST contain a field named exactly secret_text. Other field names will not work.

using HashiCorpVaultLib;

// Retrieve secret text from Vault
string token = VaultLib.GetSecretText(
    vaultUrl: "https://vault.example.com:8200",
    roleId: "your-role-id",
    secretPath: "system_test/username_password",
    ignoreSslErrors: false  // Default - recommended for production
);

Console.WriteLine($"Token: {token}");

Vault Secret Structure (secret text):

{
  "secret_text": "my-api-token-or-other-secret"
}

⚠️ Important: Field name is case-sensitive and must be exactly secret_text. Using different names (e.g., secretText, secret, text) will cause an error.

SSL Certificate Handling

By default, the library verifies SSL certificates for production security. SSL certificate validation is enabled by default (ignoreSslErrors: false).

For development environments with self-signed certificates, you can optionally bypass SSL validation:

// Production (default) - SSL verification enabled
var (username, password) = VaultLib.GetUsernamePassword(
    "https://vault.example.com:8200",
    "role-id",
    "app/database"
    // ignoreSslErrors is false by default
);

// Development - SSL verification disabled
var (username, password) = VaultLib.GetUsernamePassword(
    "https://vault-dev.local:8200",
    "dev-role-id",
    "dev/database",
    ignoreSslErrors: true  // Only for development!
);

⚠️ Warning: Never use ignoreSslErrors: true in production environments!

Path Transformation

The library automatically transforms simple paths to KV v2 API format:

Error Handling

The library throws exceptions in the following cases:

• Missing VAULT_SECRET_ID: Application exits with code 777
• Authentication failure: Invalid Role ID or Secret ID
• Secret not found: Invalid path or insufficient permissions
• Missing required fields: Secret doesn't contain expected fields (username, password, or secret_text)
• Network errors: Connection issues or timeout

Example error handling:

try
{
    var (username, password) = VaultLib.GetUsernamePassword(
        "https://vault.example.com:8200",
        "role-id",
        "system_test/username_password",
        ignoreSslErrors: false
    );

    // Use credentials...
}
catch (Exception ex)
{
    Console.WriteLine($"Failed to retrieve credentials: {ex.Message}");
    // Handle error appropriately
}

Security Considerations

1. Never hardcode secrets: Always use environment variables for Secret ID
2. SSL Verification: SSL certificate validation is enabled by default. Only bypass it in development with ignoreSslErrors: true
3. Credentials Handling: Never log or expose retrieved credentials
4. Environment Variables: Set VAULT_SECRET_ID securely in your deployment environment
5. AppRole Permissions: Ensure your AppRole has minimal required permissions in Vault

Configuration for Production

For production environments, consider:

1. Setting VAULT_SECRET_ID via:

   • CI/CD pipeline secrets
   • Kubernetes secrets
   • Cloud provider secret management
   • Secure configuration management tools

2. Updating your Vault policies to restrict access appropriately

3. Using proper SSL/TLS certificates and enabling certificate validation

Example Project

A complete working example is available in the examples/HashiCorpVaultLib.Example directory. The example demonstrates:

• Loading configuration from appsettings.json
• Retrieving username/password secrets
• Retrieving secret text
• SSL certificate handling
• Error handling

Running the Example:

1. Navigate to the example directory:

   cd examples/HashiCorpVaultLib.Example
   

2. Copy and configure settings:

   cp appsettings.example.json appsettings.json
   # Edit appsettings.json with your Vault details
   

3. Set environment variable:

   export VAULT_SECRET_ID=your-secret-id
   

4. Run the example:

   dotnet run
   

See examples/HashiCorpVaultLib.Example/README.md for detailed instructions.

Vault Secret Field Requirements

⚠️ Critical: This library expects specific field names in your Vault secrets:

For Username/Password secrets:

• Field username (exact case) - contains the username
• Field password (exact case) - contains the password

For Secret Text:

• Field secret_text (exact case) - contains the secret value

These field names are mandatory and case-sensitive. Using different field names will result in errors. The library will throw an exception if the required fields are missing or empty.

Requirements

• .NET Standard 2.0 or higher
• .NET Framework 4.6.1+ or .NET Core 2.0+
• Vault server with AppRole authentication enabled
• KV v2 secrets engine
• Vault secrets must use exact field names: username, password, or secret_text

License

MIT

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Support

For issues and questions, please use the GitHub issue tracker.