Manage Values

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 val-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:

• Generate a Value Key
• Encrypt the provided Value using the Value Key
• Encrypt the Value Key using the Keyring Public Key
• Populate the values with the new value, and save the configuration to configPath.

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 val-lst. This command supports using regular expressions, so you can easily filter and display Values using regex:

$ rot val-lst ^[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 val-add and rot val-set-meta.

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

• rot val-add-prv will store the public key in the publicKey meta field.

Versions

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

You can view all values and versions using rot val-lst. Additionally, you can display a specific version in rot val-dis via @:

$ rot val-lst mykeyring
{
  "mykeyring/test": [
    "2024-04-26T12:32:52Z",
    "2024-04-26T10:32:44Z"
  ]
}
# Display the latest version
$ rot val-dis mykeyring -v mykeyring/test
123
# Display a specific version
$ rot val-dis mykeyring -v mykeyring/test@2024-04-26T10:32:44Z
456
# Use longest match
$ rot val-dis 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 val-add.

Removing Values

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