Usage

The secret rotator re-encrypts the secrets stored in the Horizon or Stream database with the current primary key of the Tink keyset.

The tool never modifies the keyset. The primary key must be rotated beforehand, as described in the Tinkey key rotation section of the Horizon or Stream documentation, and the previous keys must stay ENABLED so that the existing secrets can still be decrypted. Once the rotation succeeds, the previous keys can be disabled.

Listing the supported versions

To list the supported product versions:

  • RHEL

  • Debian

  • Docker

/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator list
/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator list
docker run registry.evertrust.io/evertrust-secret-rotator list

Checking the secrets

The examples below target Horizon. For Stream, use --product stream and the Stream keyset (/opt/stream/etc/stream.keyset by default).

The check command verifies that every secret can be decrypted with the keyset, and counts the secrets that still need to be rotated. Nothing is written to the database.

  • RHEL

  • Debian

  • Docker

/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator check --product horizon --mongo-uri "<mongo URI>" --keyset-path /opt/horizon/etc/horizon.keyset
/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator check --product horizon --mongo-uri "<mongo URI>" --keyset-path /opt/horizon/etc/horizon.keyset
docker run registry.evertrust.io/evertrust-secret-rotator check --product horizon --mongo-uri "<mongo URI>" --keyset-path /opt/horizon/etc/horizon.keyset

Rotating the secrets

Stop the product and back up the database before running the rotate command. Documents modified while the rotation runs are not overwritten and are reported as conflicts: run the rotation again to handle them.

To re-encrypt the configuration secrets with the primary key of the keyset:

  • RHEL

  • Debian

  • Docker

/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator rotate --product horizon --mongo-uri "<mongo URI>" --keyset-path /opt/horizon/etc/horizon.keyset
/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator rotate --product horizon --mongo-uri "<mongo URI>" --keyset-path /opt/horizon/etc/horizon.keyset
docker run registry.evertrust.io/evertrust-secret-rotator rotate --product horizon --mongo-uri "<mongo URI>" --keyset-path /opt/horizon/etc/horizon.keyset

For Horizon only, to re-encrypt the escrowed private keys with the primary key of the escrow vault keyset, use the escrow mode:

  • RHEL

  • Debian

  • Docker

/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator rotate --mode escrow --product horizon --mongo-uri "<mongo URI>" --keyset-path /path/to/escrow.keyset
/opt/evertrust/evertrust-secret-rotator/bin/evertrust-secret-rotator rotate --mode escrow --product horizon --mongo-uri "<mongo URI>" --keyset-path /path/to/escrow.keyset
docker run registry.evertrust.io/evertrust-secret-rotator rotate --mode escrow --product horizon --mongo-uri "<mongo URI>" --keyset-path /path/to/escrow.keyset

The rotation is idempotent: the secrets already encrypted with the primary key are skipped. If the primary key uses a RAW output prefix, every secret is re-encrypted.

The command exits with a non-zero code if any secret could not be decrypted with the keyset. These secrets are reported and left untouched.

Parameters

Parameters are only read from the command line. Environment variables and /etc/default files are never read.

Parameter Description

--product

Required. The product owning the database: horizon or stream

--mongo-uri

Required. The database URI, including the database name

--keyset-path

Required. The path of the Tink keyset, whose primary key has already been rotated

--master-key-uri

The master key URI, only for a wrapped keyset (PKCS#11, AWS KMS or GCP KMS)

--credentials-path

The KMS credentials, requires --master-key-uri. The KMS default credentials are used if not set

--mode

config (default) to rotate the configuration vault secrets, escrow to rotate the escrow vault private keys (Horizon only)

--product-version

Overrides the product version detected from the misc collection