aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSilvio Rhatto <rhatto@riseup.net>2022-08-19 12:36:21 -0300
committerSilvio Rhatto <rhatto@riseup.net>2022-08-19 12:36:21 -0300
commit1c416bd775ce4915d5fdd5c3bcf37fc8c88a33f5 (patch)
tree4d475f307449011e4b5010b392f0e3213e2439a3
parent0bce87704b1ca134880067942e3eb64f548a0e32 (diff)
downloadkeyringer-1c416bd775ce4915d5fdd5c3bcf37fc8c88a33f5.tar.gz
keyringer-1c416bd775ce4915d5fdd5c3bcf37fc8c88a33f5.tar.bz2
Fix(docs): main documentation moved to README
-rw-r--r--README.md297
-rw-r--r--index.md298
2 files changed, 295 insertions, 300 deletions
diff --git a/README.md b/README.md
index 2b11b60..6ca6741 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,296 @@
-# Keyringer
+# Keyringer: encrypted and distributed secret sharing software
-A 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.
-Se [docs](index.md) for details.
+* Repository and issue tracker: [https://0xacab.org/rhatto/keyringer](https://0xacab.org/rhatto/keyringer)
+* Repository mirror: [https://git.fluxo.info/keyringer](https://git.fluxo.info/keyringer)
+* Archived issue trackers:
+ * [Built-in Taskwarrior database](/tasks).
+ * [Trac](https://keyringer.fluxo.info/trac)
+* Manpage: [keyringer.1](share/man/keyringer.1)
+* License: [GPLv3+](LICENSE)
+* Tor Onion Service: [http://fpwwehb7ngvmxwl5ahtubh5gs5i4olmrubx73zlnzheubhjweik5irid.onion](http://fpwwehb7ngvmxwl5ahtubh5gs5i4olmrubx73zlnzheubhjweik5irid.onion)
+* Releases: [https://keyringer.fluxo.info/releases](releases)
+* Contact: rhatto at riseup.net
+
+Index
+-----
+
+[[TOC]]
+
+Installation
+------------
+
+Just clone
+
+ git clone https://0xacab.org/rhatto/keyringer.git
+
+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 <keyring> init <path> [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 <repository-url>
+
+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 <keyring> commands
+
+Encrypting a secret
+
+ keyringer <keyring> encrypt <secret>
+
+Encrypting a secret from a file
+
+ keyringer <keyring> encrypt <secret> <plaintext-file>
+
+Decrypting a secret (only to stdout)
+
+ keyringer <keyring> decrypt <secret>
+
+Re-encrypting a secret or the whole repository
+
+ keyringer <keyring> recrypt [secret]
+
+Appending information to a secret
+
+ keyringer <keyring> append <secret>
+
+Editing a secret
+
+ keyringer <keyring> edit <secret>
+
+Use this option with caution as it keeps temporary unencrypted data
+into a temporary folder.
+
+Listing secrets
+
+ keyringer <keyring> ls [arguments]
+
+Git wrapper
+-----------
+
+Keyringer comes with a simple git wrapper to ease common management tasks:
+
+ keyringer <keyring> git remote add keyringer <url>
+ keyringer <keyring> git push keyringer master
+ keyringer <keyring> 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/<keyring>`: managed by
+ "keyringer <keyring> 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 <keyring> 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 <keyring> preferences add KEYID=<fingerprint>
+
+Example:
+
+ keyringer <keyring> 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 <keyring> 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 <keyring> recipients edit [recipient-name]
+ keyringer <keyring> recipients ls
+
+Remember that keyringer support multiple recipients in a per-folder style. Try
+it by creating a sample recipient file:
+
+ keyringer <keyring> recipients edit closest-friends
+
+Fill it with your friends key IDs. Now encrypt a secret just for then:
+
+ keyringer <keyring> 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.
+
+Alternatives
+------------
+
+There are many alternatives do collaborative secret management. Here are some:
+
+* [Pass: The Standard Unix Password Manager](https://www.passwordstore.org/)
+* [SOPS: Secret OPerationS: Simple and flexible tool for managing secrets](https://github.com/mozilla/sops)
+
+Also check
+
+* [This page](https://wiki.koumbit.net/PasswordManagementService/SoftwareComparison)
+ a comparison on different password management tools.
+* [This issue](https://gitlab.torproject.org/tpo/tpa/team/-/issues/29677) for an
+ additional discussion.
+
+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.md).
diff --git a/index.md b/index.md
index 645acdb..6787609 100644
--- a/index.md
+++ b/index.md
@@ -1,297 +1 @@
-[[!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.fluxo.info](https://keyringer.fluxo.info)
-* Repository and issue tracker: [https://0xacab.org/rhatto/keyringer](https://0xacab.org/rhatto/keyringer)
-* Repository mirror: [https://git.fluxo.info/keyringer](https://git.fluxo.info/keyringer)
-* Archived issue trackers:
- * [Built-in Taskwarrior database](/tasks).
- * [Trac](https://keyringer.fluxo.info/trac)
-* Manpage: [keyringer.1](share/man/keyringer.1)
-* License: [GPLv3+](LICENSE)
-* Tor Onion Service: [http://fpwwehb7ngvmxwl5ahtubh5gs5i4olmrubx73zlnzheubhjweik5irid.onion](http://fpwwehb7ngvmxwl5ahtubh5gs5i4olmrubx73zlnzheubhjweik5irid.onion)
-* Releases: [https://keyringer.fluxo.info/releases](releases)
-* Contact: rhatto at riseup.net
-
-Index
------
-
-[[!toc levels=4]]
-
-Installation
-------------
-
-Just clone
-
- git clone https://0xacab.org/rhatto/keyringer.git
-
-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 <keyring> init <path> [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 <repository-url>
-
-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 <keyring> commands
-
-Encrypting a secret
-
- keyringer <keyring> encrypt <secret>
-
-Encrypting a secret from a file
-
- keyringer <keyring> encrypt <secret> <plaintext-file>
-
-Decrypting a secret (only to stdout)
-
- keyringer <keyring> decrypt <secret>
-
-Re-encrypting a secret or the whole repository
-
- keyringer <keyring> recrypt [secret]
-
-Appending information to a secret
-
- keyringer <keyring> append <secret>
-
-Editing a secret
-
- keyringer <keyring> edit <secret>
-
-Use this option with caution as it keeps temporary unencrypted data
-into a temporary folder.
-
-Listing secrets
-
- keyringer <keyring> ls [arguments]
-
-Git wrapper
------------
-
-Keyringer comes with a simple git wrapper to ease common management tasks:
-
- keyringer <keyring> git remote add keyringer <url>
- keyringer <keyring> git push keyringer master
- keyringer <keyring> 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/<keyring>`: managed by
- "keyringer <keyring> 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 <keyring> 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 <keyring> preferences add KEYID=<fingerprint>
-
-Example:
-
- keyringer <keyring> 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 <keyring> 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 <keyring> recipients edit [recipient-name]
- keyringer <keyring> recipients ls
-
-Remember that keyringer support multiple recipients in a per-folder style. Try
-it by creating a sample recipient file:
-
- keyringer <keyring> recipients edit closest-friends
-
-Fill it with your friends key IDs. Now encrypt a secret just for then:
-
- keyringer <keyring> 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.
-
-Alternatives
-------------
-
-There are many alternatives do collaborative secret management. Here are some:
-
-* [Pass: The Standard Unix Password Manager](https://www.passwordstore.org/)
-* [SOPS: Secret OPerationS: Simple and flexible tool for managing secrets](https://github.com/mozilla/sops)
-
-Also check
-
-* [This page](https://wiki.koumbit.net/PasswordManagementService/SoftwareComparison)
- a comparison on different password management tools.
-* [This issue](https://gitlab.torproject.org/tpo/tpa/team/-/issues/29677) for an
- additional discussion.
-
-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).
+Docs moved to [https://0xacab.org/rhatto/keyringer](https://0xacab.org/rhatto/keyringer).