Manage Secret Generation

DevOps Secrets Safe implements several secret generators. Secret generation configurations can be modified at runtime by using the command line interface.

List Secret Generator Configurations

ssrun generator get

This command provides a list of all configured secret generators as JSON.

{
  "Type": "String",
  "Name": "my-password-generator",
  "Description": "Default password construction policy",
  "Options": {
    "MinCharacters": 8,
    "MaxCharacters": 10,
    "AllowUpperCaseCharacters": true,
    "NumberOfRequiredUpperCaseCharacters": 1,
    "UpperCaseCharacters": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "AllowLowerCaseCharacters": true,
    "NumberOfRequiredLowerCaseCharacters": 1,
    "LowerCaseCharacters": "abcdefghijklmnopqrstuvwxyz",
    "AllowNumericCharacters": true,
    "NumberOfRequiredNumericCharacters": 1,
    "NumericCharacters": "1234567890",
    "AllowNonAlphaNumericCharacters": false,
    "NumberOfNonAlphaNumericCharacters": 1,
    "NonAlphaNumericCharacters": "~!@#$%^&*()-+=?/<>|[]{}_.",
    "FirstCharacterRequirement": "AnyCharacterPermitted"
  }
}}

To view a specific generator, you can specify the generator name with the command above (ssrun generator get -n my-password-generator).

Delete a Secret Generator Configuration

ssrun generator delete -n <generator-name>

This deletes the generator with the given name.

Create a Secret Generator Configuration

ssrun generator create -f my-generator.json

This creates a generator configuration using the values in the file my-generator.json. Details on the structure of the configuration file are outlined in the section below.

Secret Generator File Structure

Configurations are defined in JSON formatted files. Generator configurations have the following structure:

{
  "type": "",
  "name": "",
  "version": "1.0",
  "description": "",
  "options": {
    "option1": "",
    "option2": ""
  }
}
Field Required Description
Type Yes

The generator type to use. The options are String and Number. More details about these options are provided below.

Version No

If no version is specified, this defaults to 1.0.

Name Yes Friendly name for the generator. This is the name to provide to ssrun generator delete if you delete the secret generator later.

Names must be unique and can only include the following characters: 0-9, A-Z, a-z, underscore (_) and dash (-).

Description No Provides details about this generator.
Options No This is an array of key-value pairs to provide extra arguments for the generator configuration.

If this section or a child of this section is excluded, it is set to the default value(s) defined by the generator type or version specified.

String Generator Options

The following are the options for version 1.0 of the String generator:

*MinCharacters: (Defaults to 8) Defines the minimum password length.
*MaxCharacters: (Defaults to 10) Defines the maximum password length. MaxCharacters must be greater than MinCharacters.
*AllowUpperCaseCharacters: (Defaults to true) Determines whether uppercase characters are permitted.
*AllowUpperCaseCharacters: (Defaults to true) Minimum number of required uppercase characters.
*UpperCaseCharacters: (Defaults to ABCDEFGHIJKLMNOPQRSTUVWXYZ) Defines the allowable uppercase characters.
*AllowLowerCaseCharacters: (Defaults to true) Determines whether lowercase characters are permitted.
*NumberOfRequiredLowerCaseCharacters: (Defaults to 1) Minimum number of required lowercase characters.
*LowerCaseCharacters: (Defaults to abcdefghijklmnopqrstuvwxyz) Defines the allowable lowercase characters.
*AllowNumericCharacters: (Defaults to true) Determines whether numeric characters are permitted.
*NumberOfRequiredNumericCharacters: (Defaults to 1) Minimum number of required numeric characters.
*NumericCharacters: (Defaults to 1234567890) Defines the allowable numberic characters.
*AllowNonAlphaNumericCharacters: (Defaults to false) Determines whether non-alphanumeric characters are permitted.
*NumberOfNonAlphaNumericCharacters: (Defaults to 1) Minimum number of required non-alphanumeric characters.
*NonAlphaNumericCharacters: (Defaults to ~!@#$%^&()-+=?/<>|[]{}_.) Defines the allowable non-alphanumberic characters.
*FirstCharacterRequirement: (Defaults to AnyCharacterPermitted)

First character value. Allowable options are:

  • AnyCharacterPermitted
  • AlphaCharactersOnly
  • AlphaNumericPermitted
{
  "Type": "String",
  "Name": "my-password-generator",
  "Description": "Default password construction policy",
  "Options": {
    "MinCharacters": 8,
    "MaxCharacters": 10,
    "AllowUpperCaseCharacters": true,
    "NumberOfRequiredUpperCaseCharacters": 1,
    "UpperCaseCharacters": "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
    "AllowLowerCaseCharacters": true,
    "NumberOfRequiredLowerCaseCharacters": 1,
    "LowerCaseCharacters": "abcdefghijklmnopqrstuvwxyz",
    "AllowNumericCharacters": true,
    "NumberOfRequiredNumericCharacters": 1,
    "NumericCharacters": "1234567890",
    "AllowNonAlphaNumericCharacters": false,
    "NumberOfNonAlphaNumericCharacters": 1,
    "NonAlphaNumericCharacters": "~!@#$%^&*()-+=?/<>|[]{}_.",
    "FirstCharacterRequirement": "AnyCharacterPermitted"
  }
}

Number Generator Options

The following are the options for version 1.0 of the Number generator:

*MinValue: (Defaults to 1) Defines the inclusive lower bound of the random number returned.
*MaxValue: (Defaults to 9007199254740991) Defines the exclusive upper bound of the random number returned. MaxValue must be greater than MinValue.
{
  "type": "Number",
  "name": "my-number-generator",
  "description": "Test Random Number Generator",
  "options": {
    "MinValue": 100,
    "MaxValue": 9007199254740991
  }
}

Seed a Secret With a Generated Value

The create and update secret commands optionally accept a generator name as an input. When specified, DevOps Secrets Safe stores a value generated by the generator instead of a value specified by the user.

Before starting this section, ensure you have initialized, unsealed, and logged into DevOps Secrets Safe as root.

  1. Create a new user.
    ssrun user create -n generateSecretUser -pgenerateSecretUserPassword
  2. Create a generator.
    ssrun generator create -f my-generator.json
  3. Authorize the new user to create and update secrets within the resource space secret/path/to/my/secrets.
    ssrun authorization create -p principal/internal/user/generateSecretUser -o create,update -a allow secret/path/to/my/secrets
  4. Authorize the new user to create values using the newly created generator.
    ssrun authorization create -p principal/internal/user/generateSecretUser -o create -a allow generator/<generator-name>
  5. Log in as the new user.
    ssrun login -u generateSecretUser -p generateSecretUserPassword
  6. The new user can now use the newly created generator to generate secrets within the resource space secret/path/to/my/secrets.
  7. ssrun secret create -g <generator-name> path/to/my/secrets:mytestsecret1

    or

    ssrun secret update -g <generator-name> path/to/my/secrets:mytestsecret1