Change markdown extension to .md

1 files changed, 324 insertions, 0 deletions

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 <rhatto@riseup.net>
+% 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
+<https://keyringer.pw>.