eyaml rotate keys

1. Introduction
2. EYAML Compatibility Alert
3. Self-Help Documentation

Introduction

The eyaml-rotate-keys command-line tool fits a narrow, special use-case: to rotate the encryption of secret values in YAML data files. Using two pairs of encryption keys -- the old and new sets -- all encrypted data is decrypted and re-encrypted, writing each updated file over the original. Backups of the original files can be made.

This page explores the various command-line arguments understood by eyaml-rotate-keys. For real-world examples of using it, please check eyaml-rotate-keys Examples.

EYAML Compatibility Alert

The maintainers of the hiera-eyaml project have released version 3.x and it is not backward compatible with encryption certificates generated for hiera-eyaml version 2.x. This has nothing to do with YAML Path and is alerted here only as a courtesy to YAML Path users. If you upgrade your installation of hiera-eyaml without first updating your encryption certificates and using a tool like eyaml-rotate-keys (provided here) to re-encrypt your data with the replacement certificates, hiera-eyaml 3.x will fail to decrypt your data! This is not a problem with YAML Path. hiera-eyaml certificate compatibility is well outside the purview of YAML Path and its tools.

Self-Help Documentation

When the --help (-h) flag is passed into eyaml-rotate-keys, it produces this output:

usage: eyaml-rotate-keys [-h] [-V] [-d | -v | -q] [-b] [-x EYAML]
                         -i OLDPRIVATEKEY -c OLDPUBLICKEY
                         -r NEWPRIVATEKEY -u NEWPUBLICKEY
                         YAML_FILE [YAML_FILE ...]

Rotates the encryption keys used for all EYAML values within a set of YAML
files, decrypting with old keys and re-encrypting using replacement keys.

positional arguments:
  YAML_FILE             one or more YAML files containing EYAML values

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -d, --debug           output debugging details
  -v, --verbose         increase output verbosity
  -q, --quiet           suppress all output except errors
  -b, --backup          save a backup of each modified YAML_FILE with an extra
                        .bak file-extension
  -x EYAML, --eyaml EYAML
                        the eyaml binary to use when it isn't on the PATH

EYAML_KEYS:
  All key arguments are required

  -r NEWPRIVATEKEY, --newprivatekey NEWPRIVATEKEY
                        the new EYAML private key
  -u NEWPUBLICKEY, --newpublickey NEWPUBLICKEY
                        the new EYAML public key
  -i OLDPRIVATEKEY, --oldprivatekey OLDPRIVATEKEY
                        the old EYAML private key
  -c OLDPUBLICKEY, --oldpublickey OLDPUBLICKEY
                        the old EYAML public key

Any YAML_FILEs lacking EYAML values will not be modified (or backed up, even
when -b/--backup is specified).