Secrets Management Key CLI Tool

The following commands are available with the Secrets Management Key CLI tool that is included with each Ignition installation to help manage your Secrets Management system, once it's configured.

Working with Redundancy

Make sure that the root and KEK JSON files are applied to both the Master and Backup nodes in a redundant configuration. If not, the embedded secrets and Internal Provider secrets encrypted on one will not decrypt on the other.

Command Descriptions

Reference the tables below for the descriptions to the informational or required commands when running the built-in scripts.

General

Command	Description
-f, --force	Force an overwrite of the target file(s) if it already exists. Ignored if the output destination is not a file or if the same value is used for both input and output.
-h, --help	Show the help message and exit.
-V, --version	Print version information and exit.

ID

Command	Description
-i, --id, --kid, --key-id=<value>	The ID of the key to set as primary or to remove.

KEK Set

The KEK Set argument value can be formatted as follows:

• file:pathname: Reads or writes the KEK Set from/to the specified file pathname, which can be a regular file, device, or named pipe. Only the first JSON element is read from the stream, which is expected to be a JSON object representing the flattened JSON Web Encryption (JWE) serialization of the encrypted Root Key.
• stdout: Reads or writes the KEK Set to standard output. The same handling as described for file applies to KEK Sets read from standard input.

If this option is omitted entirely, then the value defaults to file:$CWD/data/config/ignition/keys/kek.json where $CWD is the current working directory.

Command	Description
-k, --kek=<value>	KEK Set input source or output destination, as applicable.
-k, --kek=<shared>	KEK Set input source and output destination.
--kek:in=<in>	KEK Set input source.
--kek:out=<out>	KEK Set output destination.

Password

The password or passphrase argument value can be formatted as follows:

• pass:password: The actual password or passphrase is password. Since the password or passphrase is visible to utilities (like 'ps' under Unix) this form should only be used where security is not important.
• env:var: Obtain the password or passphrase from the environment variable var. Since the environment of other processes is visible on certain platforms, this option should be used with caution.
• file:pathname: Reads the password or passphrase from the specified file pathname, which can be a regular file, device, or named pipe. Only the first line, up to the newline character, is read from the stream.
• stdin: Reads the password or passphrase from standard input. The same line handling as described for file applies to passwords read from standard input.

If no password or passphrase argument value is given then the user is prompted to enter one. This will typically be read from the current terminal with echoing turned off. If this option is omitted entirely, then the value is obtained from the environment variable IGNITION_ROOT_KEY_PASSWORD and if this environment variable is not set, then the user is prompted to enter one.

Command	Description
-p, --pwd, --pass, --password, --passphrase[=<pass>]	Password or passphrase to encrypt/decrypt the Root Key, as applicable.
-p, --pwd, --pass, --password, --passphrase[=<shared>]	Password or passphrase to decrypt the old Root Key and encrypt the new Root Key.
--pwd:in, --pass:in, --password:in, --passphrase:in[=<in>]	Password or passphrase to decrypt the old Root Key.
--pwd:out, --pass:out, --password:out, --passphrase:out[=<out>]	Password or passphrase to encrypt the new Root Key.

Root Key

The Root Key argument value can be formatted as follows:

• file:pathname: Reads or writes the Root Key from/to the specified file pathname, which can be a regular file, device, or named pipe. Only the first JSON element is read from the stream, which is expected to be a JSON object representing the flattened JSON Web Encryption (JWE) serialization of the encrypted Root Key.
• stdout: Reads or writes the Root Key from/to standard output.

If this option is omitted entirely, then the value defaults to file:$CWD/data/config/ignition/keys/root.json where $CWD is the current working directory.

Command	Description
-r, --root=<value>	Root Key input source or output destination, as applicable.
-r, --root=<shared>	Root Key input source and output destination.
--root:in=<in>	Old Root Key input source.
--root:out=<out>	New Root Key output destination.

Built-in Scripts

Generate a New Root Key

This script generates a new Root Key and encodes it as a JSON Web Key (JWK). The Root Key is encrypted using the given password or passphrase.

Usage

ignition-secrets-tool root generate [-fhV] [-p[=<pass>]] [-r=<value>]

Generate a New Key Encryption Key

This script generates a new Key Encryption Key (KEK) Set:

1. A new KEK is generated and encoded as a JSON Web Key (JWK).
2. A new KEK Set is generated and encoded as a JWK Set.
3. The new KEK is wrapped inside the new KEK Set as its only element.
4. The KEK Set is encrypted using the given Root Key.

Usage

ignition-secrets-tool kek generate [-fhV] [-p[=<pass>]] [-k=<value>] [-r=<value>]

List the Key Encryption Keys

This script lists Key Encryption Keys (KEKs):

1. A password or passphrase is first loaded to decrypt the Root Key.
2. The Root Key is loaded next to decrypt the KEK Set.
3. The KEK Set is finally loaded last, and its contents are printed to stdout with sensitive key material omitted.

Usage

ignition-secrets-tool kek list [-hV] [-p[=<pass>]] [-k=<value>] [-r=<value>] 

Rotate the Root Key

This script rotates the Root Key:

1. A password or passphrase is first loaded to decrypt the old Root Key.
   • Optionally, a second distinct password or passphrase is loaded next to encrypt the new Root Key.
2. The old Root Key is loaded next to decrypt the KEK Set.
3. The KEK Set is loaded last. It is decrypted using the old Root Key.
4. A new Root Key is generated and encoded as a JSON Web Key (JWK).
5. The new Root Key is encrypted using the given password or passphrase.
6. The new Root Key is written to its target output destination.
7. The KEK Set is encrypted using the new Root Key.
8. The encrypted KEK Set is written to its target output destination.

Usage

ignition-secrets-tool root rotate [-fhV] [-p[=<shared>] | [[--pwd:in [=<in>]] [--pwd:out[=<out>]]]] [-r=<shared> | [[--root:in=<in>] [--root:out=<out>]]] [-k=<shared> | [[--kek:in=<in>] [--kek:out=<out>]]]

Rotate the Key Encryption Key

This script rotates the Key Encryption Key (KEK):

1. A password or passphrase is first loaded to decrypt the Root Key.
2. The Root Key is loaded next to decrypt the KEK Set.
3. The KEK Set is loaded last.
4. A new KEK is generated and encoded as a JSON Web Key (JWK).
5. The new KEK is added to the end of the KEK Set, which makes it the new primary key.
6. The KEK Set is encrypted using the given Root Key.
7. The encrypted KEK Set is written to its target output destination.

Usage

ignition-secrets-tool kek rotate [-fhV] [-p[=<pass>]] [-r=<value>] [-k=<shared> | [[--kek:in=<in>] [--kek:out=<out>]]]

Reset the Primary Key Encryption Key

This script sets the primary Key Encryption Key (KEK) to the key with a given ID. The primary KEK is the key in the last position in the KEK Set. The primary KEK is the key used for encrypting new secrets.

1. A password or passphrase is first loaded to decrypt the Root Key.
2. The Root Key is loaded next to decrypt the KEK Set.
3. The KEK Set is loaded last, and its primary key is set to the key with the given ID.
4. The KEK Set is encrypted using the given Root Key.
5. The encrypted KEK Set is written to its target output destination.

Usage

ignition-secrets-tool kek primary [-fhV] [-p[=<pass>]] -i=<value> [-r=<value>] [-k=<shared> | [[--kek:in=<in>] [--kek:out=<out>]]]

Remove a Key Encryption Key

This script removes the Key Encryption Key (KEK) with a given ID:

1. A password or passphrase is first loaded to decrypt the Root Key.
2. The Root Key is loaded next to decrypt the KEK Set.
3. The KEK Set is loaded last, and the key with the given ID is removed from the set.
4. The KEK Set is encrypted using the given Root Key.
5. The encrypted KEK Set is written to its target output destination.

Usage

ignition-secrets-tool kek remove [-fhV] [-p[=<pass>]] -i=<value> [-r=<value>] [-k=<shared> | [[--kek:in=<in>] [--kek:out=<out>]]]