From 9222f51984ec0d15044da3d14b7f41ee1d8f5abc Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Sun, 1 Oct 2017 17:19:35 -0300 Subject: Change markdown extension to .md --- development.md | 110 +++++++++++++++ development.mdwn | 110 --------------- index.md | 281 +++++++++++++++++++++++++++++++++++++++ index.mdwn | 281 --------------------------------------- share/man/keyringer.1.md | 324 +++++++++++++++++++++++++++++++++++++++++++++ share/man/keyringer.1.mdwn | 324 --------------------------------------------- 6 files changed, 715 insertions(+), 715 deletions(-) create mode 100644 development.md delete mode 100644 development.mdwn create mode 100644 index.md delete mode 100644 index.mdwn create mode 100644 share/man/keyringer.1.md delete mode 100644 share/man/keyringer.1.mdwn diff --git a/development.md b/development.md new file mode 100644 index 0000000..2349c84 --- /dev/null +++ b/development.md @@ -0,0 +1,110 @@ +[[!meta title="Keyringer: development guidelines and workflow"]] + +Index +----- + +[[!toc levels=4]] + +Coding standards +---------------- + +* Uses Semantic Versioning. +* Respect the existing coding style. +* Be clear: easy audability must be one of keyringer's requirements. + +Release workflow +---------------- + +Go to develop branch and start a new release + + git checkout develop + +Prepare the source code: + + $EDITOR keyringer # and update KEYRINGER_VERSION + $EDITOR ChangeLog + VERSION="`./keyringer | head -n 1 | cut -d ' ' -f 2`" + +Create and upload a new release: + + make release + +Tag the release: + + git tag -s $VERSION -m "Keyringer $VERSION" + +Update the debian branch: + + make debian + +Push everything: + + git push --tags + +Build the package from the debian Git branch: + + git-buildpackage + +Run lintian (or [add it to your pbuilder hooks](http://askubuntu.com/questions/140697/how-do-i-run-lintian-from-pbuilder-dist)): + + lintian --info --display-info --pedantic --color auto build-area/keyringer_$VERSION*.changes + +Then go back to the develop branch and push everything: + + git checkout develop + git push --all + +Cleanup symlink: + + rm ../keyringer_$VERSION.orig.tar.bz2 + +Notes: + +* `git-import-orig` takes care of running `pristine-tar commit`, of merging of the tag and orig tarball into the upstream branch, and then it merges the result into the debian branch. With the above configuration, it also runs git-dch to do the bulk of the work in `debian/changelog`. +* To build a development package, checkout the debian branch, merge master, run `git-dch --auto --snapshot` and build. + +Packaging workflow +------------------ + +We recommend [this packaging workflow](https://git.sarava.org/?p=debian.git;a=blob;f=README.md;hb=HEAD). + +Adding or changing a subcommand +------------------------------- + +When adding a new subcommand or changing subcommand behavior, ensure: + +* Documentation is updated. +* Manpage is updated. +* Shell completions are updated. + +Test environment +---------------- + +Setup: + + keyringer test init ~/temp/tests/keyringer + +Teardown: + + keyringer test teardown -y + +Translation +----------- + +Run just once: + + cd share/man + po4a-gettextize -f text -m keyringer.1.mdwn -p keyringer.pot + +References +---------- + +* [Using Git for Debian Packaging](http://www.eyrie.org/~eagle/notes/debian/git.html). +* [Building packages from the Git repository](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.building.html). +* [Cowbuilder](https://wiki.debian.org/cowbuilder). +* [git-pbuilder](https://wiki.debian.org/git-pbuilder). +* [PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit). +* [Generating pristine tarballs from git repositories](http://joeyh.name/blog/entry/generating_pristine_tarballs_from_git_repositories/). +* [Debian Packaging](https://wiki.debian.org/Packaging). +* [Debian Upstream Guide](https://wiki.debian.org/UpstreamGuide). +* [DanielKahnGillmor/preferred_packaging - Debian Wiki](https://wiki.debian.org/DanielKahnGillmor/preferred_packaging). diff --git a/development.mdwn b/development.mdwn deleted file mode 100644 index 2349c84..0000000 --- a/development.mdwn +++ /dev/null @@ -1,110 +0,0 @@ -[[!meta title="Keyringer: development guidelines and workflow"]] - -Index ------ - -[[!toc levels=4]] - -Coding standards ----------------- - -* Uses Semantic Versioning. -* Respect the existing coding style. -* Be clear: easy audability must be one of keyringer's requirements. - -Release workflow ----------------- - -Go to develop branch and start a new release - - git checkout develop - -Prepare the source code: - - $EDITOR keyringer # and update KEYRINGER_VERSION - $EDITOR ChangeLog - VERSION="`./keyringer | head -n 1 | cut -d ' ' -f 2`" - -Create and upload a new release: - - make release - -Tag the release: - - git tag -s $VERSION -m "Keyringer $VERSION" - -Update the debian branch: - - make debian - -Push everything: - - git push --tags - -Build the package from the debian Git branch: - - git-buildpackage - -Run lintian (or [add it to your pbuilder hooks](http://askubuntu.com/questions/140697/how-do-i-run-lintian-from-pbuilder-dist)): - - lintian --info --display-info --pedantic --color auto build-area/keyringer_$VERSION*.changes - -Then go back to the develop branch and push everything: - - git checkout develop - git push --all - -Cleanup symlink: - - rm ../keyringer_$VERSION.orig.tar.bz2 - -Notes: - -* `git-import-orig` takes care of running `pristine-tar commit`, of merging of the tag and orig tarball into the upstream branch, and then it merges the result into the debian branch. With the above configuration, it also runs git-dch to do the bulk of the work in `debian/changelog`. -* To build a development package, checkout the debian branch, merge master, run `git-dch --auto --snapshot` and build. - -Packaging workflow ------------------- - -We recommend [this packaging workflow](https://git.sarava.org/?p=debian.git;a=blob;f=README.md;hb=HEAD). - -Adding or changing a subcommand -------------------------------- - -When adding a new subcommand or changing subcommand behavior, ensure: - -* Documentation is updated. -* Manpage is updated. -* Shell completions are updated. - -Test environment ----------------- - -Setup: - - keyringer test init ~/temp/tests/keyringer - -Teardown: - - keyringer test teardown -y - -Translation ------------ - -Run just once: - - cd share/man - po4a-gettextize -f text -m keyringer.1.mdwn -p keyringer.pot - -References ----------- - -* [Using Git for Debian Packaging](http://www.eyrie.org/~eagle/notes/debian/git.html). -* [Building packages from the Git repository](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.building.html). -* [Cowbuilder](https://wiki.debian.org/cowbuilder). -* [git-pbuilder](https://wiki.debian.org/git-pbuilder). -* [PackagingWithGit - Debian Wiki](https://wiki.debian.org/PackagingWithGit). -* [Generating pristine tarballs from git repositories](http://joeyh.name/blog/entry/generating_pristine_tarballs_from_git_repositories/). -* [Debian Packaging](https://wiki.debian.org/Packaging). -* [Debian Upstream Guide](https://wiki.debian.org/UpstreamGuide). -* [DanielKahnGillmor/preferred_packaging - Debian Wiki](https://wiki.debian.org/DanielKahnGillmor/preferred_packaging). diff --git a/index.md b/index.md new file mode 100644 index 0000000..6c1849a --- /dev/null +++ b/index.md @@ -0,0 +1,281 @@ +[[!meta title="Keyringer: encrypted and distributed secret sharing software"]] + +Keyringer lets you manage and share secrets using GnuPG and Git with custom +commands to encrypt, decrypt, recrypt, create key pairs, etc. + +- Project page: [https://keyringer.pw](https://keyringer.pw) +- Manpage: [keyringer.1](share/man/keyringer.1) +- License: [GPLv3+](LICENSE) +- Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac) +- Tor hidden service: [http://4qt45wbulqipigwa.onion](http://4qt45wbulqipigwa.onion) +- Releases: [https://keyringer.pw/releases](releases) +- Contact: rhatto at riseup.net + +Index +----- + +[[!toc levels=4]] + +Installation +------------ + +Just clone + + git clone https://git.fluxo.info/keyringer + +You can also verify the latest commit's OpenPGP signature: + + /usr/bin/git -C keyringer verify-commit HEAD + +Note that `/usr/bin/git` is called to avoid any other `git` wrappers or aliases +you might have available on your shell. + +You can also add the `keyringer` script into your `$PATH` environment variable +or package it to your preferred distro. + +If you're using Debian `stable` or newer, just run + + apt-get install keyringer + +Creating a keyringer repository +------------------------------- + +The first step is to setup a keyring. + +Keyringer supports management of multiple isolated keyrings. To start +a new keyring (or register an existing one with your config file), run: + + keyringer init [remote] + +This will + + 1. Add an entry at `$HOME/.keyringer/config` aliasing 'keyring' to 'path'. + 2. Initialize a git repository if needed. + +For example, + + keyringer friends init $HOME/keyrings/friends + +creates an alias "friends" pointing to `$HOME/keyrings/friends`. All +other keyring actions for this keyring should be called using this alias. + +If there is an existing remote keyring git repository and you just +want to checkout it, use + + keyringer friends init $HOME/keyrings/friends + +Managing secrets +---------------- + +Each `secret` has a corresponding file inside `keys` subdirectory from the +keyring folder. Keyringer has plenty of actions to operate in these secrets: + + keyringer commands + +Encrypting a secret + + keyringer encrypt + +Encrypting a secret from a file + + keyringer encrypt + +Decrypting a secret (only to stdout) + + keyringer decrypt + +Re-encrypting a secret or the whole repository + + keyringer recrypt [secret] + +Appending information to a secret + + keyringer append + +Editing a secret + + keyringer edit + +Use this option with caution as it keeps temporary unencrypted data +into a temporary folder. + +Listing secrets + + keyringer ls [arguments] + +Git wrapper +----------- + +Keyringer comes with a simple git wrapper to ease common management tasks: + + keyringer git remote add keyringer + keyringer git push keyringer master + keyringer git pull + +Configuration files, preferences, options and recipients +-------------------------------------------------------- + +Basic keyringer operation depends in a set of configuration files: + + 1. Main config file: `$HOME/.keyringer/config`: store the location of + each keyring. + + 2. User preferences per keyring: `$HOME/.keyringer/`: managed by + "keyringer preferences". Preferences aren't shared among + users, so each user can have it's own set of preferences. + + 3. Custom keyring options: `$KEYRING_FOLDER/config/options`: managed by + "keyringer options". Options are shared among all + keyring users. + + 4. Recipients: `$KEYRING_FOLDER/config/recipients/`: controls the list of + OpenPGP public key fingerprints that should be used when encrypting content. + Multiple recipients are supported, so secrets can be encrypted to + different sets of OpenPGP pubkeys in the same keyring. + +Other configuration parameters used by keyringer and it's actions are stored at +`$KEYRING_FOLDER/config/`. + +Using a non-default OpenPGP key +------------------------------- + +If you want to use a different key other than your default for a given +keyringer, use + + keyringer preferences add KEYID= + +Example: + + keyringer preferences add KEYID=0123456789ABCDEF0123456789ABCDE012345678 + +Managing recipients +------------------- + +Keyringer uses the `default` recipient stored at `$KEYRING_FOLDER/config/recipients/default` +as the standard list of OpenPGP public key fingerprints to which secrets should be encrypted. + +Additionally, keyringer supports multiple `recipient` files which can have a different set +of OpenPGP public key fingerprints used for encryption. + +Recipients are matched against secrets according to it's path. If there exists a recipient +called `accounting`, the following secret will be encrypted using it's OpenPGP public key +fingerprints: + + keyringer encrypt accounting/balance + +In other words, the `accounting` recipient file is used because the secret name begins +with `accounting`. + +So it's the case that recipients listed in the `default` recipient but not in the +`accounting` recipients won't be able to decrypt this secret. + +When you first initalized your keyring, keyringer might have asked you to populate +the `default` recipient list or you cloned a keyring repository which already has +the `default` recipient. + +If you want more recipient files, your next step is tell keyringer the OpenPGP +key IDs to encrypt files to: + + keyringer recipients edit [recipient-name] + keyringer recipients ls + +Remember that keyringer support multiple recipients in a per-folder style. Try +it by creating a sample recipient file: + + keyringer recipients edit closest-friends + +Fill it with your friends key IDs. Now encrypt a secret just for then: + + keyringer encrypt closest-friends/secret + +In other words, if keyringer finds a recipient file matching a given path, +it will use it instead of the global recipients file. + +You can even create recipient files with your friends' key IDs but without +yours: then you shall be able to encrypt secrets for them that even you cannot +access. Try to find an use case for that ;) + +Each recipient list is defined in a file placed at `config/recipients` in your +keyring repository. Take care to add just trustable recipients. + +Design +------ + +Keyringer's basic concepts are as follows: + + - Each secret is encrypted using multiple users's OpenPGP public keys and commit the + output in a git repository we call a "keyring". + + - A "recipient" a list of OpenPGP keys associated with a path in the keyring, so each + keyring can have multiple recipient definitions so secret compartmentalization is + builtin. All encryption should respect recipient definition. + + - Users can keep their keyring copies in sync using any git remote and push/pull + strategy they like, so key sharing gets easy. + + - A secret is not limited to passphrases or text: keyringer supports any file encryption, + so managing private keys, spreadsheets and media files are handled without distinction. + + - Secret is stored with OpenPGP ASCII-armoured output, so one doesn't need any special + program besides GnuPG to actually decrypt information. + + - Keyringer is agnostic about how you store your secrets. You may choose to have + one encrypted file that contains one line for each secret, e.g. a single file called + secrets with lines such as: + + emma : root : secret1 + emma - /dev/hda : : secret2 + + Or you may also have a different encrypted file for each secret, e.g. a file called + `emma.root` that contains the root passphrase for the server named `emma` and + another called `emma.hda` with the passphrase to decrypt `/dev/hda` on `emma`. + + Creating a logical structure to store your secrets is up to you :) + +Workflow +-------- + +Keyringer can be used as a personal or shared password/secret manager: + + - Each keyring is a full git repository used to store encrypted secrets + using ASCII-armoured OpenPGP. + + - Actions like `encrypt` allows you to paste your secrets directly to + GnuPG so no plaintext is written to disk. + + - By commiting, pushing and pulling each keyring repository, you can + easily share secrets with other people and systems and they don't + need to decrypt this information until they need. + +In summary, keyringer data store is basically gpg-encrypted data atop of a git +repository (one can think of a kind of distributed encrypted filesystem). + +Git was chosen to host encrypted info mostly for two reasos: easy to distribute +and its the only VCS known to make easier repository history manipulation. + +Limitations +----------- + + - See the [manpage](share/man/keyringer.1) for details. + + - Check [this page](https://wiki.koumbit.net/PasswordManagementService/SoftwareComparison) + a comparison on different password management tools. + +Requirements +------------ + +Keyringer needs: + + - [Bash](http://tiswww.case.edu/php/chet/bash/bashtop.html) + - [Git](http://git-scm.com) + - [GNU Privacy Guard](http://gnupg.org) + - Grep, awk, tail, cut, sed and other GNU tools + +Optional dependencies if you want to manage ssl keys: + + - [OpenSSL](http://www.openssl.org) + +Development guidelines +---------------------- + +See [development](development). diff --git a/index.mdwn b/index.mdwn deleted file mode 100644 index 6c1849a..0000000 --- a/index.mdwn +++ /dev/null @@ -1,281 +0,0 @@ -[[!meta title="Keyringer: encrypted and distributed secret sharing software"]] - -Keyringer lets you manage and share secrets using GnuPG and Git with custom -commands to encrypt, decrypt, recrypt, create key pairs, etc. - -- Project page: [https://keyringer.pw](https://keyringer.pw) -- Manpage: [keyringer.1](share/man/keyringer.1) -- License: [GPLv3+](LICENSE) -- Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac) -- Tor hidden service: [http://4qt45wbulqipigwa.onion](http://4qt45wbulqipigwa.onion) -- Releases: [https://keyringer.pw/releases](releases) -- Contact: rhatto at riseup.net - -Index ------ - -[[!toc levels=4]] - -Installation ------------- - -Just clone - - git clone https://git.fluxo.info/keyringer - -You can also verify the latest commit's OpenPGP signature: - - /usr/bin/git -C keyringer verify-commit HEAD - -Note that `/usr/bin/git` is called to avoid any other `git` wrappers or aliases -you might have available on your shell. - -You can also add the `keyringer` script into your `$PATH` environment variable -or package it to your preferred distro. - -If you're using Debian `stable` or newer, just run - - apt-get install keyringer - -Creating a keyringer repository -------------------------------- - -The first step is to setup a keyring. - -Keyringer supports management of multiple isolated keyrings. To start -a new keyring (or register an existing one with your config file), run: - - keyringer init [remote] - -This will - - 1. Add an entry at `$HOME/.keyringer/config` aliasing 'keyring' to 'path'. - 2. Initialize a git repository if needed. - -For example, - - keyringer friends init $HOME/keyrings/friends - -creates an alias "friends" pointing to `$HOME/keyrings/friends`. All -other keyring actions for this keyring should be called using this alias. - -If there is an existing remote keyring git repository and you just -want to checkout it, use - - keyringer friends init $HOME/keyrings/friends - -Managing secrets ----------------- - -Each `secret` has a corresponding file inside `keys` subdirectory from the -keyring folder. Keyringer has plenty of actions to operate in these secrets: - - keyringer commands - -Encrypting a secret - - keyringer encrypt - -Encrypting a secret from a file - - keyringer encrypt - -Decrypting a secret (only to stdout) - - keyringer decrypt - -Re-encrypting a secret or the whole repository - - keyringer recrypt [secret] - -Appending information to a secret - - keyringer append - -Editing a secret - - keyringer edit - -Use this option with caution as it keeps temporary unencrypted data -into a temporary folder. - -Listing secrets - - keyringer ls [arguments] - -Git wrapper ------------ - -Keyringer comes with a simple git wrapper to ease common management tasks: - - keyringer git remote add keyringer - keyringer git push keyringer master - keyringer git pull - -Configuration files, preferences, options and recipients --------------------------------------------------------- - -Basic keyringer operation depends in a set of configuration files: - - 1. Main config file: `$HOME/.keyringer/config`: store the location of - each keyring. - - 2. User preferences per keyring: `$HOME/.keyringer/`: managed by - "keyringer preferences". Preferences aren't shared among - users, so each user can have it's own set of preferences. - - 3. Custom keyring options: `$KEYRING_FOLDER/config/options`: managed by - "keyringer options". Options are shared among all - keyring users. - - 4. Recipients: `$KEYRING_FOLDER/config/recipients/`: controls the list of - OpenPGP public key fingerprints that should be used when encrypting content. - Multiple recipients are supported, so secrets can be encrypted to - different sets of OpenPGP pubkeys in the same keyring. - -Other configuration parameters used by keyringer and it's actions are stored at -`$KEYRING_FOLDER/config/`. - -Using a non-default OpenPGP key -------------------------------- - -If you want to use a different key other than your default for a given -keyringer, use - - keyringer preferences add KEYID= - -Example: - - keyringer preferences add KEYID=0123456789ABCDEF0123456789ABCDE012345678 - -Managing recipients -------------------- - -Keyringer uses the `default` recipient stored at `$KEYRING_FOLDER/config/recipients/default` -as the standard list of OpenPGP public key fingerprints to which secrets should be encrypted. - -Additionally, keyringer supports multiple `recipient` files which can have a different set -of OpenPGP public key fingerprints used for encryption. - -Recipients are matched against secrets according to it's path. If there exists a recipient -called `accounting`, the following secret will be encrypted using it's OpenPGP public key -fingerprints: - - keyringer encrypt accounting/balance - -In other words, the `accounting` recipient file is used because the secret name begins -with `accounting`. - -So it's the case that recipients listed in the `default` recipient but not in the -`accounting` recipients won't be able to decrypt this secret. - -When you first initalized your keyring, keyringer might have asked you to populate -the `default` recipient list or you cloned a keyring repository which already has -the `default` recipient. - -If you want more recipient files, your next step is tell keyringer the OpenPGP -key IDs to encrypt files to: - - keyringer recipients edit [recipient-name] - keyringer recipients ls - -Remember that keyringer support multiple recipients in a per-folder style. Try -it by creating a sample recipient file: - - keyringer recipients edit closest-friends - -Fill it with your friends key IDs. Now encrypt a secret just for then: - - keyringer encrypt closest-friends/secret - -In other words, if keyringer finds a recipient file matching a given path, -it will use it instead of the global recipients file. - -You can even create recipient files with your friends' key IDs but without -yours: then you shall be able to encrypt secrets for them that even you cannot -access. Try to find an use case for that ;) - -Each recipient list is defined in a file placed at `config/recipients` in your -keyring repository. Take care to add just trustable recipients. - -Design ------- - -Keyringer's basic concepts are as follows: - - - Each secret is encrypted using multiple users's OpenPGP public keys and commit the - output in a git repository we call a "keyring". - - - A "recipient" a list of OpenPGP keys associated with a path in the keyring, so each - keyring can have multiple recipient definitions so secret compartmentalization is - builtin. All encryption should respect recipient definition. - - - Users can keep their keyring copies in sync using any git remote and push/pull - strategy they like, so key sharing gets easy. - - - A secret is not limited to passphrases or text: keyringer supports any file encryption, - so managing private keys, spreadsheets and media files are handled without distinction. - - - Secret is stored with OpenPGP ASCII-armoured output, so one doesn't need any special - program besides GnuPG to actually decrypt information. - - - Keyringer is agnostic about how you store your secrets. You may choose to have - one encrypted file that contains one line for each secret, e.g. a single file called - secrets with lines such as: - - emma : root : secret1 - emma - /dev/hda : : secret2 - - Or you may also have a different encrypted file for each secret, e.g. a file called - `emma.root` that contains the root passphrase for the server named `emma` and - another called `emma.hda` with the passphrase to decrypt `/dev/hda` on `emma`. - - Creating a logical structure to store your secrets is up to you :) - -Workflow --------- - -Keyringer can be used as a personal or shared password/secret manager: - - - Each keyring is a full git repository used to store encrypted secrets - using ASCII-armoured OpenPGP. - - - Actions like `encrypt` allows you to paste your secrets directly to - GnuPG so no plaintext is written to disk. - - - By commiting, pushing and pulling each keyring repository, you can - easily share secrets with other people and systems and they don't - need to decrypt this information until they need. - -In summary, keyringer data store is basically gpg-encrypted data atop of a git -repository (one can think of a kind of distributed encrypted filesystem). - -Git was chosen to host encrypted info mostly for two reasos: easy to distribute -and its the only VCS known to make easier repository history manipulation. - -Limitations ------------ - - - See the [manpage](share/man/keyringer.1) for details. - - - Check [this page](https://wiki.koumbit.net/PasswordManagementService/SoftwareComparison) - a comparison on different password management tools. - -Requirements ------------- - -Keyringer needs: - - - [Bash](http://tiswww.case.edu/php/chet/bash/bashtop.html) - - [Git](http://git-scm.com) - - [GNU Privacy Guard](http://gnupg.org) - - Grep, awk, tail, cut, sed and other GNU tools - -Optional dependencies if you want to manage ssl keys: - - - [OpenSSL](http://www.openssl.org) - -Development guidelines ----------------------- - -See [development](development). diff --git a/share/man/keyringer.1.md b/share/man/keyringer.1.md new file mode 100644 index 0000000..8acd747 --- /dev/null +++ b/share/man/keyringer.1.md @@ -0,0 +1,324 @@ +% KEYRINGER(1) Keyringer User Manual +% Silvio Rhatto +% Oct 25, 2013 + +# NAME + +keyringer - encrypted and distributed secret sharing software + +# SYNOPSIS + +keyringer <*keyring*> <*action*> [*options*]... + +# DESCRIPTION + +Keyringer lets you manage and share secrets using GnuPG and Git in a +distributed fashion. + +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, to allow a workgroup to share access to a single +repository while restricting some secrets to subsets of the group. + +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 *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. + +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 *del* action. + +rm <*secret*> +: Alias for *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* which 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 *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 *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 an 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 clip action. + +sclip <*secret*> +: Same as 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 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 + +Keyringer currently has the following limitations: + +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. + +2. 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. + +3. 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 you 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. + +# SEE ALSO + +The *README* file distributed with Keyringer contains full documentation. + +The Keyringer source code and all documentation may be downloaded from +. diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn deleted file mode 100644 index 8acd747..0000000 --- a/share/man/keyringer.1.mdwn +++ /dev/null @@ -1,324 +0,0 @@ -% KEYRINGER(1) Keyringer User Manual -% Silvio Rhatto -% Oct 25, 2013 - -# NAME - -keyringer - encrypted and distributed secret sharing software - -# SYNOPSIS - -keyringer <*keyring*> <*action*> [*options*]... - -# DESCRIPTION - -Keyringer lets you manage and share secrets using GnuPG and Git in a -distributed fashion. - -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, to allow a workgroup to share access to a single -repository while restricting some secrets to subsets of the group. - -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 *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. - -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 *del* action. - -rm <*secret*> -: Alias for *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* which 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 *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 *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 an 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 clip action. - -sclip <*secret*> -: Same as 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 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 - -Keyringer currently has the following limitations: - -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. - -2. 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. - -3. 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 you 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. - -# SEE ALSO - -The *README* file distributed with Keyringer contains full documentation. - -The Keyringer source code and all documentation may be downloaded from -. -- cgit v1.2.3