summaryrefslogtreecommitdiff
path: root/share/man/keyringer.1.mdwn
diff options
context:
space:
mode:
Diffstat (limited to 'share/man/keyringer.1.mdwn')
-rw-r--r--share/man/keyringer.1.mdwn324
1 files changed, 0 insertions, 324 deletions
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 <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>.