KEYRINGER(1)

📦
version 0.6.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

keyringer — encrypted and distributed secret sharing software 💖

yes bestie, this is the manual page for keyringer(1), and it's about to be your new favorite thing, no cap.

📜 SYNOPSIS 📜

keyringer <keyring> <action> [options]...

🦋 DESCRIPTION 🦋

Okay so Keyringer lets you manage and share secrets using GnuPG and Git in a distributed fashion. It's giving "my secrets are safe AND synced", and honestly? obsessed. 💅

It has custom commands to create key-pairs and to encrypt, decrypt and re-encrypt secrets. It also supports encryption to multiple recipients and groups of recipients, so a whole workgroup can share access to a single repository while still restricting some secrets to just subsets of the group. iconic behavior tbh. 👑

Secrets are encrypted using OpenPGP and added to a Git tree so that they can be synced with remote branches later. ✨

🎀 ACTIONS 🎀

Keyringer has three types of actions:

  1. Repository lookup and manipulation actions, which handle repository initialization, content tracking and navigation.
  2. Secret manipulation actions, which take care of encrypting, decrypting and other read/write operations on secrets.
  3. Configuration actions, handling repository metadata.

🗂️ REPOSITORY LOOKUP AND MANIPULATION ACTIONS 🗂️

  • find expression — Find secrets in the repository. 🔍
  • init path [remote] — Initialize a new keyringer repository. If a remote URL is specified, keyringer will clone an existing repository.

After initialization, path will contain a folder structure for storing secrets and metadata (user aka recipients, groups of recipients, etc).

Also, an entry will be added to $HOME/.keyringer/config allowing keyringer to find the keyring by its alias. 🏠

  • destroy — Alias for the teardown action.
  • git action options — Git wrapper that operates from the toplevel keyring repository. You can issue any GIT(1) subcommand with this action to have it applied in the keyring repository. 🌿
  • commit [arguments] — Alias to “git commit”.
  • ls path — List contents from the toplevel repository keys folder, or from relative paths if path is specified. Like the git wrapper, this is a wrapper around the LS(1) command.
  • mkdir path — Create a directory inside the repository keys folder. 📁
  • rmdir path — Remove an empty folder inside the repository keys folder.
  • tree path — List contents from the toplevel repository keys folder, or from relative paths if path is specified, using a tree-like format. Like the ls wrapper, this is a wrapper around the TREE(1) command. 🌳
  • shell — Run keyringer on interactive mode from a built-in command-line prompt where all other actions can be called and are operated from the current selected keyring.

An additional “cd” internal command is available for directory navigation.

All <secret> parameters from actions invoked from the shell are called relatively from the current selected directory. 🐚

  • teardown — Remove permanently a local copy of a repository, very dangerous if you have just a single copy. 💀
  • check — Run maintenance checks in a keyring. ✅

🔐 SECRET MANIPULATION ACTIONS 🔐

All secret manipulation actions operate upon a secret which is the pathname of an encrypted file relative to the keyring with optional .asc extension.

If the .asc extension is omitted, keyringer will add it at the end of the pathname.

No spaces are allowed in the secret name.

Secret manipulation actions do not commit changes into the secret repository. Instead, the user has to manually commit the changes using the git wrapper action. periodt. don't forget it bestie 😭
  • append secret — Append contents into a secret by decrypting the secret, appending lines read from the standard input and encrypting again.
  • append-batch secret — Append contents into a secret, batch mode.
  • decrypt secret — Decrypts a secret into standard output. 🔓
  • del secret — Removes a secret using Git. After deleting a secret a git commit and push is still needed to update remote repositories.

Please note that this command does not remove the secret from the Git history. To completely remove a file from a keyring, you should also rewrite the Git history yourself. 💀

  • delete secret — Alias for the del action.
  • rm secret — Alias for the del action.
  • cp secret dest — Copy a secret.
  • mv secret dest — Rename a secret.
  • edit secret — Edit a secret by temporarily decrypting it, opening the decrypted copy into the text editor defined by the $EDITOR environment variable and then re-encrypting it.
Please make sure to use an EDITOR that does not leak data like history buffers. Keyringer tries to detect if $EDITOR is set to VIM and disables the .viminfo file. 🫶
  • encrypt secret [file] — Encrypts content from standard input or file into secret pathname. No spaces are supported in the secret name. If file is actually a folder, keyringer will recursivelly encrypt all it's contents. 🔒
  • encrypt-batch secret [file] — Encrypt content, batch mode. Behavior is identical to the encrypt action, but less verbose. Useful inside scripts. 🤫
  • genkeys <ssh|gpg|x509|x509-self|ssl|ssl-self> [options] — Wrapper to generate encryption key-pairs, useful for automated key deployment. 🔑
  • genpair <ssh|gpg|x509|x509-self|ssl|ssl-self> [options] — Alias for the genkeys action.
  • open secret — Decrypt a secret into a temporary folder and open it using xdg-open, which tries to figure out the file type and then calls the associated application.

After the application exits, keyringer encrypts the temporary decrypted file again into the secret file and deletes the temporary file. 📂

  • pwgen secret [size] — Generates a random passphrase and stores into secret pathname with optional entropy size in bytes. Default size is 20.

Passphrases will be slightly bigger than size due to base64 conversion.

With this action you can generate and store a passphrase without need to see it. Combined with clip or sclip action provides a hygienic way to handle secrets. 🧼

  • recrypt secret — Re-encrypts a secret by decrypting it and encrypting it again. Useful when users are added into the recipient configuration. If no secret is given, all secrets in the repository are re-encrypted. 🔁
  • clip secret — Copy the first line of a secret to the clipboard, following password-store convention. 📋
  • xclip secret — Alias to the clip action.
  • sclip secret — Same as the clip action, but sleeps five seconds, overwrite clipboard and exit. If xdotool is available, it also switches to the next window using the alt+Tab shortcut. This action is useful to be invoked by a custom key combo in a window manager so it becomes easy to provide keyringer managed passphrases to other applications such as a web browser. 🌐

⚙️ CONFIGURATION ACTIONS ⚙️

  • commands — List available actions, useful for shell completion and syntax check.
  • options <ls|edit|add> — List, edit or add miscellaneous repository options.

Repository options are settings which are saved in the repository as a global configuration stanza for a given keyring, shared by all users with access to the repository.

Options are written using the KEY=VALUE syntax. All lines starting with the hash (#) character are interpreted as comments. 📝

  • preferences <ls|edit|add> — List, edit or add user preferences for a given repository.

User preferences are settings which are saved in the user's keyringer folder ($HOME/.keyringer/), and not shared with the other users.

Preferences are written using the KEY=VALUE syntax. All lines starting with the hash (#) character are interpreted as comments. 🙈

  • usage — Show keyringer usage information.
  • help — Alias for the usage action.
  • recipients <ls|edit> <recipients-file> — List, create or edit recipients configuration.

Recipients files are lists of OpenPGP public key fingerprints which are used by keyringer when encrypting secrets and associated with email aliases.

Keyringer uses a default recipients file, but specifying a custom recipients-file pathname will override this default.

For instance, if a user encrypts a secret to a file in the keyring repository's accounting folder, a recipients-file under accounting will be used. Encrypting a secret into accounting/bank-accounts will result in a file $KEYRING_FOLDER/keys/accounting/bank-accounts.asc encrypted using the public keys listed in the config file $KEYRING_FOLDER/config/recipients/accounting.

Each line in a recipients file has entries in the format john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX, where john@doe.com is an alias for the OpenPGP public key whose fingerprint is XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.

All lines starting with the hash (#) character are interpreted as comments.

Parameters to the recipients action are:

  • ls — List all existing recipients files.
  • edit — Create or edit a recipients file.

Editing happens using the editor specified by the $EDITOR environment variable.

The required parameter recipients-file is interpreted relative to the $KEYRING_FOLDER/config/recipients/ folder.

📁 FILES 📁

  • $HOME/.keyringer/config — User's main configuration file used to map alias names to keyrings.
  • $HOME/.keyringer/keyring — User preferences for the keyringer aliased keyring keyring.
  • $KEYRING_FOLDER/config/options — Custom keyring options which will be applied for all users that use the keyringer repository.

💀 LIMITATIONS 💀

okay bestie, real talk — Keyringer is iconic but she is not perfect, and here's exactly where she's got limits. Read this part, fr fr:

  1. Metadata is not encrypted 😭 meaning that an attacker with access to a keyringer repository can discover all public key IDs used for encryption, and which secrets are encrypted to which keys. This can be improved in the future by encrypting the repository configuration with support for the --hidden-recipient GnuPG option and encrypted repository options.

To mitigate that, it's possible to keep the repo just atop of an encrypted and non-public place. 🫶

  1. History is not rewritten by default when secrets are removed from a keyringer repository. After a secret is removed with the del action, it will still be available in the repository history even after a commit. This is by design for the following reasons:
    • It's the default behavior of the Git content tracker. Forcing the deletion by default could break the expected behavior and hence limit the repository's backup features, which can be helpful if someone mistakenly overwrites a secret. 💅
    • History rewriting cannot be considered a security measure against the unauthorized access to a secret as it doesn't automatically update all working copies of the repository.

In the case that the secret is a passphrase, the recommended measure against such attacks is to change the passphrase, making useless the knowledge of the previous secret. 🔥

Users wishing to edit their repository history should proceed manually using the git action.

  1. Keyringer does not protect data which were not encrypted to a keyring, so be careful when decrypting secrets and writing them to the disk or other storage media. 🙈

Pay special attention that keyringer outputs data to stdout, which could be easily spotted by any agent looking directly at your computer screen. 👀

The xclip action even copies secret data to the X11 clipboard, which can be accessed by any application running in the user's X11 session, so use this feature carefully. ⚠️

not to be dramatic but like… anyone shoulder-surfing your terminal is literally the final boss. be careful out there. 💖

🌈 SEE ALSO 🌈

The README file distributed with Keyringer contains full documentation. 📖

The Keyringer source code and all documentation may be downloaded from <https://keyringer.pw>. ✨

👑 AUTHORS 👑

Silvio Rhatto <rhatto@riseup.net>. 💜

and that's a wrap on the whole manual, bestie!! this page is from the Keyringer User Manual, dated Oct 25, 2013, and it lives at KEYRINGER(1) — go forth and encrypt responsibly, you absolute main character 🎀🦋💖

📦 where this page comes from