secs-man: A Vendor-Independent Secrets Backup Tool

secs-man: A Vendor-Independent Secrets Backup Tool

Avoid Vendor Lock-in for Critical Secrets

secs-man is a command-line tool designed for the secure backup, restoration, and verification of secrets. Its primary objective is to ensure that users are not dependent on any specific software ecosystem for the recovery of their most sensitive data. By decoupling encryption and restoration from the tool itself, secs-man ensures that secrets remain accessible even if the software is no longer maintained or available.

Core Philosophy: Interoperability and Standards

The fundamental design principle of secs-man is that the recovery of important data should not require the specific software used to encrypt it. To achieve this, the tool relies on widely adopted technologies and standards rather than proprietary formats.

The Recovery Stack

secs-man is built to be perfectly reproducible using only the following components:

  • A terminal
  • Coreutils: Standard Linux utilities such as cp, mv, and sha256sum
  • age: A modern, simple, and small encryption tool
  • Manual effort: The ability to perform manual recovery steps if the tool is unavailable

By relying on age for encryption and coreutils for integrity verification, the tool minimizes the risk of data loss caused by software obsolescence.

Technical Implementation and Workflow

secs-man manages secrets by utilizing a centralized directory and a manifest file (.secrets-manifest) that lists the files to be managed, along with optional owner and mode permissions for restoration.

Export and Encryption

When exporting secrets, secs-man performs the following steps:

  1. Integrity Check: Verifies the checksum of the source file.
  2. Encryption: Encrypts files using age with a passphrase provided via an interactive prompt. The tool never reads passphrases from environment variables, files, or arguments.
  3. Checksum Generation: Generates a *.sha256 file to guarantee the integrity of the encrypted data.
  4. Snapshotting: Saves the encrypted files into a timestamped snapshot within the export target directory.

Import and Decryption

To restore secrets, the tool decrypts the files using the same passphrase and restores them to the target directory. If specified in the manifest, the tool applies the correct file ownership and permissions (defaulting to 600 if no mode is specified).

Verification

Users can verify the integrity of an existing export by running verify-export. This process checks that every checksum matches, ensuring that old exports have not decayed or become corrupted.

Remote Machine Management

secs-man includes a companion script, secs-man-ssh, to handle secrets on remote hosts without exposing the encryption passphrase to the remote machine.

  • Exporting from remote: The script copies remote secrets to a temporary directory on the remote host, moves them to the local host, and then performs the export locally.
  • Importing to remote: The script decrypts the snapshot locally into a temporary directory, copies the plaintext files to the remote host, and then imports them into the final remote secrets directory.

This workflow ensures that the decryption process happens on the local, trusted machine rather than the untrusted remote host.

Manual Recovery Process

Because secs-man uses standard tools, recovery is possible without the tool itself.

  • Manual Export: The behavior is equivalent to running age --passphrase --output filename.txt.age --encrypt filename.txt.
  • Manual Verification: Integrity can be verified using find . -name "sha256sums.txt" -execdir sha256sum -c sha256sums.txt \;.
  • Manual Import: Files can be decrypted using age --output filename.txt --decrypt filename.txt.age, followed by manual chmod and chown commands to restore permissions.

Threat Model and Security Considerations

secs-man creates snapshots during export that are not automatically cleaned up. This presents different risk profiles based on the secret type:

  • Authenticating Secrets: For rotatable keys (e.g., SSH or WireGuard keys), snapshots pose minimal additional risk.
  • Decrypting Secrets: For master keys or disk keys, old snapshots may expose past decryption keys if the current secrets are leaked. The author recommends manually deleting old exported snapshots when rotating these types of secrets.

Sources