Hanzo KMS .NET SDK

If you're working with .NET, the official Hanzo KMS .NET SDK package is the easiest way to fetch and work with secrets for your application.

Installation

dotnet add package Hanzo KMS.Sdk

Getting Started (.NET)

namespace Example;

using Hanzo KMS.Sdk;
using Hanzo KMS.Sdk.Model;

public class Program {
  public static void Main(string[] args) {

    var settings = new Hanzo KMSSdkSettingsBuilder()
        .WithHostUri("http://localhost:8080") // Optional. Will default to https://app.kms.hanzo.ai
        .Build();

    var kmsClient = new Hanzo KMSClient(settings);

    var _ = kmsClient.Auth().UniversalAuth().LoginAsync("<machine-identity-universal-auth-client-id>", "<machine-identity-universal-auth-client-secret>").Result;

    var options = new ListSecretsOptions
    {
      SetSecretsAsEnvironmentVariables = true,
      EnvironmentSlug = "<your-env-slug>",
      SecretPath = "/",
      ProjectId = "<your-project-id>",
    };

    var secrets = kmsClient.Secrets().ListAsync(options).Result;

    if (secrets == null)
    {
      throw new Exception("Failed to fetch secrets, returned null response");
    }

    foreach (var secret in secrets)
    {
      Console.WriteLine($"{secret.SecretKey}: {secret.SecretValue}");
    }
  }
}

Getting Started (Visual Basic)

Imports Hanzo KMS.Sdk
Imports Hanzo KMS.Sdk.Model

Module Program
    Sub Main(args As String())
        Dim settings = New Hanzo KMSSdkSettingsBuilder() _
            .WithHostUri("https://app.kms.hanzo.ai") _
            .Build()
        
        Dim kmsClient As New Hanzo KMSClient(settings)

        Dim authResult = kmsClient.Auth().UniversalAuth() _
          .LoginAsync("<machine-identity-universal-auth-client-id>", "machine-identity-universal-auth-client-secret").Result

        Dim options As New ListSecretsOptions With {
          .SetSecretsAsEnvironmentVariables = True,
          .EnvironmentSlug = "<your-env-slug>",
          .SecretPath = "/",
          .ProjectId = "<your-project-id>"
        }

        Dim secrets = kmsClient.Secrets().ListAsync(options).Result

        For Each secret In secrets
            Console.WriteLine(secret.SecretKey)
            if Environment.GetEnvironmentVariable(secret.SecretKey) IsNot Nothing Then
                Console.WriteLine("{0} found on environment variables", secret.SecretKey)
            End If
        Next
        
    End Sub
End Module

Core Methods

The SDK methods are organized into the following high-level categories:

Auth(): Handles authentication methods.

Secrets(): Manages CRUD operations for secrets.

Pki(): Programmatically interact with the KMS PKI.

Subscribers(): Manage PKI Subscribers.

`Auth()`

The Auth() component provides methods for authentication:

Universal Auth

Authenticating

var _ = await sdk.Auth().UniversalAuth().LoginAsync(
  "CLIENT_ID",
  "CLIENT_SECRET"
);

Parameters:

clientId (string): The client ID of your Machine Identity.

clientSecret (string): The client secret of your Machine Identity.

LDAP Auth

Authenticating

var _ = await sdk.Auth().LdapAuth().LoginAsync(
  "IDENTITY_ID",
  "USERNAME",
  "PASSWORD"
);

Parameters:

identityId (string): The ID of your Machine Identity .

username (string): The LDAP username for authentication.

password (string): The LDAP password for authentication.

`Secrets()`

The Secrets() sub-class handles operations related to the Hanzo KMS secrets management product.

List Secrets

Task<Secret[]> ListAsync(ListSecretsOptions options);

throws Hanzo KMSException

var options = new ListSecretsOptions
  {
    SetSecretsAsEnvironmentVariables = true,
    EnvironmentSlug = "dev",
    SecretPath = "/test",
    Recursive = true,
    ExpandSecretReferences = true,
    ProjectId = projectId,
    ViewSecretValue = true,
  };

Secret[] secrets = await sdk.Secrets().ListAsync(options);

ListSecretsOptions:

ProjectId (string): The ID of your project.

EnvironmentSlug (string): The environment in which to list secrets (e.g., "dev").

SecretPath (string): The path to the secrets.

ExpandSecretReferences (boolean): Whether to expand secret references.

Recursive (boolean): Whether to list secrets recursively.

SetSecretsAsEnvironmentVariables (boolean): Set the retrieved secrets as environment variables.

Returns:

Task<Secret[]>: The response containing the list of secrets.

Create Secret

public Task<Secret> CreateAsync(CreateSecretOptions options);

throws Hanzo KMSException


var options = new CreateSecretOptions
{
  SecretName = "SECRET_NAME",
  SecretValue = "SECRET_VALUE",
  EnvironmentSlug = "<environment-slug>",
  SecretPath = "/",
  ProjectId = "<your-project-id>",
  Metadata = new SecretMetadata[] {
    new SecretMetadata {
      Key = "metadata-key",
      Value = "metadata-value"
    }
  }
};

Task<Secret> newSecret = await sdk.Secrets().CreateAsync(options);

Parameters:

SecretName (string): The name of the secret to create

SecretValue (string): The value of the secret.

ProjectId (string): The ID of your project.

EnvironmentSlug (string): The environment in which to create the secret.

SecretPath (string, optional): The path to the secret.

Metadata (object, optional): Attach metadata to the secret.

SecretComment (string, optional): Attach a secret comment to the secret.

SecretReminderNote (string, optional): Attach a secret reminder note to the secret.

SecretReminderRepeatDays (int, optional): Set the reminder repeat days on the secret.

SkipMultilineEncoding (bool, optional): Whether or not to skip multiline encoding for the secret's value. Defaults to false.

Returns:

Task<Secret>: The created secret.

Update Secret

public Task<Secret> UpdateAsync(UpdateSecretOptions options); 

throws Hanzo KMSException


var updateSecretOptions = new UpdateSecretOptions
{
  SecretName = "EXISTING_SECRET_NAME",
  EnvironmentSlug = "<environment-slug>",
  SecretPath = "/",
  NewSecretName = "NEW_SECRET_NAME",
  NewSecretValue = "new-secret-value",
  ProjectId = "<project-id>",
};


Task<Secret> updatedSecret = await sdk.Secrets().UpdateAsync(updateSecretOptions);

Parameters:

SecretName (string): The name of the secret to update.`

ProjectId (string): The ID of your project.

EnvironmentSlug (string): The environment in which to update the secret.

SecretPath (string): The path to the secret.

NewSecretValue (string, optional): The new value of the secret.

NewSecretName (string, optional): A new name for the secret.

NewMetadata (object, optional): New metadata to attach to the secret.

Returns:

Task<Secret>: The updated secret.

Get Secret by Name

public Task<Secret> GetAsync(GetSecretOptions options);

throws Hanzo KMSException


var getSecretOptions = new GetSecretOptions
{
  SecretName = "SECRET_NAME",
  EnvironmentSlug = "<environment-slug>",
  SecretPath = "/",
  ProjectId = "<project-id>",
};

Secret secret = await sdk.Secrets().GetAsync(getSecretOptions);

Parameters:

SecretName (string): The name of the secret to get`

ProjectId (string): The ID of your project.

EnvironmentSlug (string): The environment in which to retrieve the secret.

SecretPath (string): The path to the secret.

ExpandSecretReferences (boolean, optional): Whether to expand secret references.

Type (SecretType, optional): The type of secret to fetch. Defaults to Shared.

Returns:

Task<Secret>: The fetched secret.

Delete Secret by Name

public Secret DeleteAsync(DeleteSecretOptions options);

throws Hanzo KMSException


var options = new DeleteSecretOptions
{
  SecretName = "SECRET_TO_DELETE",
  EnvironmentSlug = "<environment-slug>",
  SecretPath = "/",
  ProjectId = "<project-id>",
};


Secret deletedSecret = await sdk.Secrets().DeleteAsync(options);

Parameters:

SecretName (string): The name of the secret to delete.

ProjectId (string): The ID of your project.

EnvironmentSlug (string): The environment in which to delete the secret.

SecretPath (string, optional): The path to the secret.

Returns:

Task<Secret>: The deleted secret.

The Pki().Subscribers() sub-class is used to programmatically interact with the KMS PKI product line. Currently only issuing new certificates and retrieving the latest certificate bundle from a subscriber is supported. More widespread support for the PKI product is coming to the .NET SDK in the near future.

Issue a new certificate

public async Task<SubscriberIssuedCertificate> IssueCertificateAsync(IssueCertificateOptions options);

throws Hanzo KMSException


var options = new IssueCertificateOptions
{
  SubscriberName = "<subscriber-name>",
  ProjectId = "<your-project-id>",
};

SubscriberIssuedCertificate newCertificate = await sdk.Pki().Subscribers().IssueCertificateAsync(options);

Parameters:

SubscriberName (string): The name of the subscriber to create a certificate for.

ProjectId (string): The ID of PKI project.

Returns:

Task<SubscriberIssuedCertificate>: The newly issued certificate along with it's credentials for the specified subscriber.

Retrieve latest certificate bundle

public async Task<CertificateBundle> RetrieveLatestCertificateBundleAsync(RetrieveLatestCertificateBundleOptions options)

throws Hanzo KMSException

var options = new RetrieveLatestCertificateBundleOptions
{
  SubscriberName = "<subscriber-name>",
  ProjectId = "<your-project-id>",
};

CertificateBundle latestCertificate = await sdk.Pki().Subscribers().RetrieveLatestCertificateBundleAsync(options);

Parameters:

SubscriberName (string): The name of the subscriber to retrieve the latest certificate bundle for

ProjectId (string): The ID of PKI project.

Returns:

Task<CertificateBundle>: The latest certificate bundle for the specified subscriber.

Installation

Getting Started (.NET)

Getting Started (Visual Basic)

Core Methods

`Auth()`

Universal Auth

Authenticating

LDAP Auth

Authenticating

`Secrets()`

List Secrets

Create Secret

Update Secret

Get Secret by Name

Delete Secret by Name

`Pki().Subscribers()`

Issue a new certificate

Retrieve latest certificate bundle

On this page