AmazonSecrets Class

Properties   Methods   Events   Configuration Settings   Errors  

The AmazonSecrets class provides an easy-to-use interface for Amazon's Secrets Manager service.

Syntax

cloudkeys.amazonsecrets()

Remarks

The AmazonSecrets class makes it easy to work with the Amazon Secrets Manager service in a secure manner using TLS. Amazon Secrets Manager allows you to securely store secrets (e.g., passwords, symmetric keys, etc.) in the cloud so that the aren't persisted locally. This class helps you to create, manage, and access those secrets.

To begin, register for an AWS account and obtain an AccessKey and SecretKey to use for authentication.

Resource Terminology

A secret in Amazon Secrets Manager is a container for one or more secret versions, which is where secret data is actually stored. Each secret version can have between zero and 20 staging labels attached to it at any given time.

A staging label is a simple string that can be used instead of a version Id to refer to a particular secret version when retrieving secret data. A staging label can only be attached to one version of a secret at any given time. The server ensures that there is always exactly one version of a secret with the special staging label AWSCURRENT, but otherwise you are free to apply any staging labels to any secret versions you choose.

Secret versions that do not have any staging labels attached to them are considered deprecated, and the server may delete them at any time without warning. Deprecated secret versions are not shown in a secret's version list unless explicitly asked for.

Using the Class

The CreateSecret method will create a new secret with an initial secret version that holds the specified secret data. To change a secret's data, create a new version of it using the CreateVersion method.

To retrieve a secret's data, call the GetSecret method, and specify the specific version (either by Id or using a staging label) whose data should be retrieved. If no particular version is specified, the version with the AWSCURRENT staging label is used.

Secrets that will no longer be used can be deleted using the DeleteSecret method, either immediately or after a waiting period. If a secret is scheduled for deletion later, then during said waiting period the deletion can be canceled using CancelDeletion.

// Creates a new secret with the textual data "Test123" named MySecret.
// The initial secret version will have only the "AWSCURRENT" staging label.
amazonsecrets.SecretString = "Test123";
amazonsecrets.CreateSecret("MySecret", "A description of my secret.");

// Creates a new secret version with the textual data "Cats456" and 
// attaches the staging labels "AWSCURRENT" (which gets moved from the previous version)
// and "best-version" to it.
amazonsecrets.SecretString = "Cats456";
amazonsecrets.CreateVersion("MySecret", "AWSCURRENT,best-version");

// Downloads the latest secret version's data to a local file.
amazonsecrets.LocalFile = "C:\temp\secret.txt";
amazonsecrets.GetSecret("MySecret", "", "");

// Schedules the secret, and all its versions, for deletion after 10 days.
amazonsecrets.DeleteSecret("MySecret", 10);

// Cancels the scheduled deletion.
amazonsecrets.CancelDeletion("MySecret");

To list secrets, use the ListSecrets method. To list a secret's versions, use the ListVersions method.

// If there are many secrets to list, there may be multiple pages of results. This will
// cause all pages of results to be accumulated into the Secrets collection property.
do {
  amazonsecrets.ListSecrets();
} while (!string.IsNullOrEmpty(amazonsecrets.SecretMarker));

// A similar thing applies to secret versions as well.
do {
  amazonsecrets.ListVersions("MySecret");
} while (!string.IsNullOrEmpty(amazonsecrets.VersionMarker));

The class also supports other functionality, including:

• Adding, removing, and moving staging labels between secret versions using MoveStagingLabel.
• Retrieval of information for a single secret with GetSecretInfo.
• Random password generation using GenRandomPassword.
• And more!