Clients

.NET client

The .NET client is what your application uses to get its secrets: it loads a vault and hands your code the secrets you ask for.

Install it

Requires .NET 8 or later.

The package is Valt0 on NuGet, and its namespace is Valt0 too. It has no dependencies of its own.

dotnet add package Valt0

Open a vault

A vault is opened by its id; the name is a label you choose.

Valt0Client.OpenVault loads a vault from the local service. Pass it the id that valt0 info prints for the vault. The service can only open a vault that has been imported into it. A vault you create is imported for you; for one made somewhere else, run valt0 import first.

It throws a Valt0Exception if the service cannot be reached or the vault cannot be loaded.

C#
using Valt0;

IVault vault = Valt0Client.OpenVault(new VaultOptions
{
    Id = "your-vault-id",
    Name = "your-vault-name",
});

Read a secret

Ask for a secret by name, use it, then dispose of it.

vault.GetSecret(name) fetches one secret and returns a Secret. Declare it with using, which zeroes the secret's buffer when it goes out of scope. Take the value out as bytes where you can: Bytes() hands back the secret's own buffer, so disposing wipes it too, and anything still holding that array afterwards sees only zeros.

The value is kept in a pinned buffer, so the garbage collector never leaves copies of it around the heap. If you need the secret as a string, use Reveal().

C#
// Disposing zeroes the underlying buffer as soon as you are finished
using Secret secret = vault.GetSecret("DATABASE_PASSWORD");

// Preferred: the raw bytes, wiped when the secret is disposed
byte[] pw = secret.Bytes();

// Or, when a string is unavoidable
db.Connect(secret.Reveal());

Unless you ask for its value, a Secret prints as [REDACTED]: ToString(), string interpolation, string.Format, a log message template, System.Text.Json, Newtonsoft.Json and the debugger alike. The value comes out only through Reveal() or Bytes().

C#
Console.WriteLine(secret);                             // [REDACTED]
Console.WriteLine($"pw={secret}");                     // pw=[REDACTED]
logger.LogInformation("Connecting with {Pw}", secret); // Connecting with [REDACTED]
JsonSerializer.Serialize(new { pw = secret });         // {"pw":"[REDACTED]"}

secret.Reveal();                                       // the actual value

Handle errors

The two ways a connection fails have exceptions of their own.

OpenVault and GetSecret throw CannotConnectToServiceException when they cannot find the service, which usually means the service is not running: valt0 status tells you whether it is. They throw NoServiceResponseException when the service did not answer within the one second the client waits.

Both derive from Valt0Exception, the base class of every exception the client throws, so catch that last for anything else, such as a vault that could not be loaded.

Every exception message starts with valt0: , so its errors are easy to find in a log.

C#
try
{
    IVault vault = Valt0Client.OpenVault("your-vault-id", "your-vault-name");
    using Secret secret = vault.GetSecret("DATABASE_PASSWORD");
    db.Connect(secret.Reveal());
}
catch (CannotConnectToServiceException)
{
    // the service was not found: is it running?
}
catch (NoServiceResponseException)
{
    // the service did not answer within the transport timeout (1s)
}
catch (Valt0Exception e)
{
    // any other error, e.g. the vault could not be loaded; e.Message says which
}

Async and threads

Every call has an async version, and a vault is safe to share between threads.

OpenVaultAsync and GetSecretAsync take the same arguments as their synchronous versions, and a CancellationToken. One vault can be used from several threads at once, and each secret is fetched from the service when you ask for it.

C#
IVault vault = await Valt0Client.OpenVaultAsync("your-vault-id", "your-vault-name", cancellationToken);
using Secret secret = await vault.GetSecretAsync("DATABASE_PASSWORD", cancellationToken);

API

Valt0Client.OpenVault(options): IVault

Opens the vault identified by Id. Throws a Valt0Exception if the service cannot be reached or the vault cannot be loaded; the two connection failures are CannotConnectToServiceException and NoServiceResponseException.

An overload takes the two values directly, OpenVault(id, name), and OpenVaultAsync takes either form and a CancellationToken.

Options

Idstring
The vault's id, the one valt0 info prints. It is the only value used to find the vault.
Namestring
A label for the vault, used in messages.

IVault

The opened vault. It is an interface, so your own tests can stand in for it.

Fields

Idstring
The vault's id.
Namestring
The vault's name.

Methods

GetSecret(name)Secret
Fetches one secret by name.
GetSecretAsync(name, ct)Task<Secret>
The same, without blocking a thread.

Secret

One secret, fetched from a vault. It is IDisposable, so a using declaration destroys it when it goes out of scope.

Methods

Bytes()byte[]
The raw bytes: the secret's own buffer, not a copy. Preferable to use where you can, because Dispose() wipes it.
Reveal()string
The value as a string (UTF-8). A string cannot be wiped, so use it sparingly.
Destroy()
Zeroes the buffer.
Dispose()
Calls Destroy(), for using.