Manage Values

How to manage values using Rot
Categories:

In this guide, we’ll go over adding and removing values in a Rot Keyring.

Adding Values

After Rot has been initialized, keys can be added using rot value-add. This command requires a name for a new key, and can optionally be provided with metadata and delimiter for the value. This command performs these actions:

Value Paths

All Values live underneath a Keyring in Rot. Values can have subpaths within the Keyring–this is useful for commands like rot run, which will convert all Values within a path into environment variables.

Value names must be valid Environment Variable names. That means they must start with a letter or _, and can only have letters, numbers, and underscores in their names.

A valid path looks like this: keyring1/a/path/VALUE.

Value Filtering

Rot can display and filter Values using rot value-list. This command supports using regular expressions, so you can easily filter and display Values using regex:

$ rot value-list ^[prd|stg]/postgresql`

This command would display all Values that start with prd/postgresql or stg/postgresql.

Meta

Rot Values can optionally be provided with metadata–key/value pairs that can store useful information about the Value, such as where or how the secret was generated, or who owns the secret.

Metadata can be provided using rot value-add and rot value-meta.

Certain Rot commands may add data to a Value’s meta:

Dynamic Values

Rot can derive dynamic values using Jsonnet scripts. These values can be used to generate JWTs, communicate with external HTTP servers, run external commands, etc. With great power comes great responsibility, Rot assumes you know what you’re doing when adding these.

These scripts will execute when the value is referenced in rot value-get, or rot run, and they obey the Config > jsonnet configurations. They can only be added by editting the rot.jsonnet file directly:

{
  "keyrings": {
    "dev": {
      "values": {
        "CREDENTIALS": {
          "": {
            "jsonnet": "decrypt('mySecret') + 'extraString'"
          }
        },
        "OAUTH_ACCESS_TOKEN": {
          "": {
            "jsonnet": "(import './rot/getOAuthToken.jsonnet')('dev')"
          }
        }
      }
    }
  }
}

These Jsonnet scripts can use two native functions to reference other secrets and use them to generate other secrets, as well as the standard Jsonnet native functions. These functions can only reference values within the keyring of the value.

decrypt(path) []string

This function decrypts the value at the specified path. This path can be a dynamic value, in which case the values will be resolved until one is returned. Rot will error if there is a dependency cycle between paths.

local decrypt(path) = std.native('decrypt')(path);

decrypt('a/path/to/a/value')

meta(path, field) string

This returns the metadata field of the value at the specified path. It will return an empty string if the value does not exist.

local meta(path, field) = std.native('meta')(path, field);

meta('a/path/to/a/value', 'field1')

Versions

Values can be modified after being added to Rot, either by adding a new version of the Value using rot value-add or modifying metadata using rot value-meta. Rot will create a new timestamped version of a Value when a new version is created using rot value-add.

You can view all values and versions using rot value-list. Additionally, you can display a specific version in rot value-get via @:

$ rot value-list mykeyring
{
  "mykeyring/test": [
    "2024-04-26T12:32:52Z",
    "2024-04-26T10:32:44Z"
  ]
}
# Get the latest version
$ rot value-get mykeyring -v mykeyring/test
123
# Get a specific version
$ rot value-get mykeyring -v mykeyring/test@2024-04-26T10:32:44Z
456

# Use longest match
$ rot value-get mykeyring -v 'mykeyring/test@2024-04-26T10'
456

Editing Values in an Editor

Values can be edited as decrypted Jsonnet text using rot edit. This command will decrypt an entire Keyring, nicely format it into a nested Jsonnet string, and open it in your $EDITOR (or whatever editor you specify).

Any changes made to the Keyring will be committed–Values removed will be removed, Values changed will have a new version added, and Values added will be encrypted and added to the Keyring.

Generating Values

Rot can generate random, cryptographically secure strings for you, instead of having you provide a value, via rot value-add.

Removing Values

Values can be removed by running rot value-delete, or editing the configuration and removing the value.