-.\" Automatically generated by Pandoc 2.17.1.1
+.\" Automatically generated by Pandoc 3.1.11.1
.\"
-.\" Define V font for inline verbatim, using C font in formats
-.\" that render this, and otherwise B font.
-.ie "\f[CB]x\f[]"x" \{\
-. ftr V B
-. ftr VI BI
-. ftr VB B
-. ftr VBI BI
-.\}
-.el \{\
-. ftr V CR
-. ftr VI CI
-. ftr VB CB
-. ftr VBI CBI
-.\}
.TH "KEYRINGER" "1" "Oct 25, 2013" "Keyringer User Manual" ""
-.hy
.SH NAME
-.PP
-keyringer - encrypted and distributed secret sharing software
+keyringer \- encrypted and distributed secret sharing software
.SH SYNOPSIS
-.PP
keyringer <\f[I]keyring\f[R]> <\f[I]action\f[R]>
[\f[I]options\f[R]]\&...
.SH DESCRIPTION
-.PP
Keyringer lets you manage and share secrets using GnuPG and Git in a
distributed fashion.
.PP
-It has custom commands to create key-pairs and to encrypt, decrypt and
-re-encrypt secrets.
+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.
.SH ACTIONS
-.PP
Keyringer has three types of actions:
.IP "1." 3
Repository lookup and manipulation actions, which handle repository
storing secrets and metadata (user aka recipients, groups of recipients,
etc).
.PP
-Also, an entry will be added to \f[V]$HOME/.keyringer/config\f[R]
+Also, an entry will be added to \f[CR]$HOME/.keyringer/config\f[R]
allowing keyringer to find the keyring by its alias.
.RE
.TP
.TP
tree <\f[I]path\f[R]>
List contents from the toplevel repository \f[I]keys\f[R] folder or from
-relative paths if \f[I]path\f[R] is specified using a tree-like format.
+relative paths if \f[I]path\f[R] is specified using a tree\-like format.
Like the ls wrapper, this is a wrapper around the \f[I]TREE(1)\f[R]
command.
.TP
shell
-Run keyringer on interactive mode from a built-in command-line prompt
+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.
.RS
check
Run maintenance checks in a keyring.
.SH SECRET MANIPULATION ACTIONS
-.PP
All secret manipulation actions operate upon a \f[I]secret\f[R] which is
the pathname of an encrypted file relative to the keyring with optional
-\f[V].asc\f[R] extension.
+\f[CR].asc\f[R] extension.
.PP
-If the \f[V].asc\f[R] extension is omitted, keyringer will add it at the
-end of the pathname.
+If the \f[CR].asc\f[R] extension is omitted, keyringer will add it at
+the end of the pathname.
.PP
No spaces are allowed in the secret name.
.PP
Append contents into a secret by decrypting the secret, appending lines
read from the standard input and encrypting again.
.TP
-append-batch <\f[I]secret\f[R]>
+append\-batch <\f[I]secret\f[R]>
Append contents into a secret, batch mode.
.TP
decrypt <\f[I]secret\f[R]>
edit <\f[I]secret\f[R]>
Edit a secret by temporarily decrypting it, opening the decrypted copy
into the text editor defined by the \f[I]$EDITOR\f[R] environment
-variable and then re-encrypting it.
+variable and then re\-encrypting it.
.RS
.PP
Please make sure to use an
-\f[I]\f[R]E\f[I]\f[R]D\f[I]\f[R]I\f[I]\f[R]T\f[I]\f[R]O\f[I]\f[R]R\f[I]\[u2005]*\[u2005]\f[R]w\f[I]\f[R]h\f[I]\f[R]i\f[I]\f[R]c\f[I]\f[R]h\f[I]\f[R]d\f[I]\f[R]o\f[I]\f[R]e\f[I]\f[R]s\f[I]\f[R]n\f[I]\f[R]o\f[I]\f[R]t\f[I]\f[R]l\f[I]\f[R]e\f[I]\f[R]a\f[I]\f[R]k\f[I]\f[R]d\f[I]\f[R]a\f[I]\f[R]t\f[I]\f[R]a\f[I]\f[R]l\f[I]\f[R]i\f[I]\f[R]k\f[I]\f[R]e\f[I]\f[R]h\f[I]\f[R]i\f[I]\f[R]s\f[I]\f[R]t\f[I]\f[R]o\f[I]\f[R]r\f[I]\f[R]y\f[I]\f[R]b\f[I]\f[R]u\f[I]\f[R]f\f[I]\f[R]f\f[I]\f[R]e\f[I]\f[R]r\f[I]\f[R]s\f[I].\f[R]K\f[I]\f[R]e\f[I]\f[R]y\f[I]\f[R]r\f[I]\f[R]i\f[I]\f[R]n\f[I]\f[R]g\f[I]\f[R]e\f[I]\f[R]r\f[I]\f[R]t\f[I]\f[R]r\f[I]\f[R]i\f[I]\f[R]e\f[I]\f[R]s\f[I]\f[R]t\f[I]\f[R]o\f[I]\f[R]d\f[I]\f[R]e\f[I]\f[R]t\f[I]\f[R]e\f[I]\f[R]c\f[I]\f[R]t\f[I]\f[R]i\f[I]\f[R]f\f[I]*EDITOR\f[R]
+\f[I]\f[R]E\f[I]\f[R]D\f[I]\f[R]I\f[I]\f[R]T\f[I]\f[R]O\f[I]\f[R]R\f[I] * \f[R]w\f[I]\f[R]h\f[I]\f[R]i\f[I]\f[R]c\f[I]\f[R]h\f[I]\f[R]d\f[I]\f[R]o\f[I]\f[R]e\f[I]\f[R]s\f[I]\f[R]n\f[I]\f[R]o\f[I]\f[R]t\f[I]\f[R]l\f[I]\f[R]e\f[I]\f[R]a\f[I]\f[R]k\f[I]\f[R]d\f[I]\f[R]a\f[I]\f[R]t\f[I]\f[R]a\f[I]\f[R]l\f[I]\f[R]i\f[I]\f[R]k\f[I]\f[R]e\f[I]\f[R]h\f[I]\f[R]i\f[I]\f[R]s\f[I]\f[R]t\f[I]\f[R]o\f[I]\f[R]r\f[I]\f[R]y\f[I]\f[R]b\f[I]\f[R]u\f[I]\f[R]f\f[I]\f[R]f\f[I]\f[R]e\f[I]\f[R]r\f[I]\f[R]s\f[I].\f[R]K\f[I]\f[R]e\f[I]\f[R]y\f[I]\f[R]r\f[I]\f[R]i\f[I]\f[R]n\f[I]\f[R]g\f[I]\f[R]e\f[I]\f[R]r\f[I]\f[R]t\f[I]\f[R]r\f[I]\f[R]i\f[I]\f[R]e\f[I]\f[R]s\f[I]\f[R]t\f[I]\f[R]o\f[I]\f[R]d\f[I]\f[R]e\f[I]\f[R]t\f[I]\f[R]e\f[I]\f[R]c\f[I]\f[R]t\f[I]\f[R]i\f[I]\f[R]f\f[I]*EDITOR\f[R]
is set to VIM and disables the \f[I].viminfo\f[R] file.
.RE
.TP
If \f[I]file\f[R] is actually a folder, keyringer will recursivelly
encrypt all it\[cq]s contents.
.TP
-encrypt-batch <\f[I]secret\f[R]> [\f[I]file\f[R]]
+encrypt\-batch <\f[I]secret\f[R]> [\f[I]file\f[R]]
Encrypt content, batch mode.
Behavior is identical to \f[I]encrypt\f[R] action, but less verbose.
Useful inside scripts.
.TP
-genkeys <\f[I]ssh\f[R]|\f[I]gpg\f[R]|\f[I]x509\f[R]|\f[I]x509-self\f[R]|\f[I]ssl\f[R]|\f[I]ssl-self\f[R]> [\f[I]options\f[R]]
-Wrapper to generate encryption key-pairs, useful for automated key
+genkeys <\f[I]ssh\f[R]|\f[I]gpg\f[R]|\f[I]x509\f[R]|\f[I]x509\-self\f[R]|\f[I]ssl\f[R]|\f[I]ssl\-self\f[R]> [\f[I]options\f[R]]
+Wrapper to generate encryption key\-pairs, useful for automated key
deployment.
.TP
-genpair <\f[I]ssh\f[R]|\f[I]gpg\f[R]|\f[I]x509\f[R]|\f[I]x509-self\f[R]|\f[I]ssl\f[R]|\f[I]ssl-self\f[R]> [\f[I]options\f[R]]
+genpair <\f[I]ssh\f[R]|\f[I]gpg\f[R]|\f[I]x509\f[R]|\f[I]x509\-self\f[R]|\f[I]ssl\f[R]|\f[I]ssl\-self\f[R]> [\f[I]options\f[R]]
Alias for \f[I]genkeys\f[R] action.
.TP
open <\f[I]secret\f[R]>
-Decrypt a secret into a temporary folder and open it using xdg-open,
+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.
.RS
.RE
.TP
recrypt <\f[I]secret\f[R]>
-Re-encrypts a secret by decrypting it and encrypting it again.
+Re\-encrypts a secret by decrypting it and encrypting it again.
Useful when users are added into the recipient configuration.
.RS
.PP
If no \f[I]secret\f[R] is given, all secrets in the repository are
-re-encrypted.
+re\-encrypted.
.RE
.TP
clip [\f[I]query\f[R]]
Copy the first line of a secret to the clipboard, following
-password-store convention.
+password\-store convention.
.RS
.PP
If the query does not exactly match an existing secret, a interactive
.RS
.PP
User preferences are settings which are saved in the user\[cq]s
-keyringer folder (\f[V]$HOME/.keyringer/\f[R]), and not shared with the
+keyringer folder (\f[CR]$HOME/.keyringer/\f[R]), and not shared with the
other users.
.PP
Preferences are written using the \f[I]KEY=VALUE\f[R] syntax.
help
Alias for usage action.
.TP
-recipients <\f[I]ls\f[R]|\f[I]edit\f[R]> <\f[I]recipients-file\f[R]>
+recipients <\f[I]ls\f[R]|\f[I]edit\f[R]> <\f[I]recipients\-file\f[R]>
List, create or edit recipients configuration.
.RS
.PP
aliases.
.PP
Keyringer uses a default recipients file, but specifying a custom
-\f[I]recipients-file\f[R] pathname will override this default.
+\f[I]recipients\-file\f[R] pathname will override this default.
.PP
For instance, if a user encrypts a secret to a file in the keyring
repository\[cq]s \f[I]accounting\f[R] folder, a
-\f[I]recipients-file\f[R] under \f[I]accounting\f[R] will be used.
-Encrypting a secret into \f[I]accounting/bank-accounts\f[R] will result
-in a file \f[V]$KEYRING_FOLDER/keys/accounting/bank-accounts.asc\f[R]
+\f[I]recipients\-file\f[R] under \f[I]accounting\f[R] will be used.
+Encrypting a secret into \f[I]accounting/bank\-accounts\f[R] will result
+in a file \f[CR]$KEYRING_FOLDER/keys/accounting/bank\-accounts.asc\f[R]
encrypted using the public keys listed in the config
-file\f[V]$KEYRING_FOLDER/config/recipients/accounting\f[R].
+file\f[CR]$KEYRING_FOLDER/config/recipients/accounting\f[R].
.PP
Each line in a recipients file has entries in the format
`john\[at]doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where
Create or edit a recipients file.
.RS
.PP
-Editing happens using the editor specified by the \f[V]$EDITOR\f[R]
+Editing happens using the editor specified by the \f[CR]$EDITOR\f[R]
environment variable.
.PP
-The required parameter \f[I]recipients-file\f[R] is interpreted relative
-to the \f[V]$KEYRING_FOLDER/config/recipients/\f[R] folder.
+The required parameter \f[I]recipients\-file\f[R] is interpreted
+relative to the \f[CR]$KEYRING_FOLDER/config/recipients/\f[R] folder.
.RE
.RE
.SH FILES
Custom keyring options which will be applied for all users that use the
keyringer repository.
.SH LIMITATIONS
-.PP
Keyringer currently has the following limitations:
.IP "1." 3
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 \f[I]\[en]hidden-recipient\f[R] GnuPG
-option and encrypted repository options.
+configuration with support for the \f[I]\[en]hidden\-recipient\f[R]
+GnuPG option and encrypted repository options.
.RS 4
.PP
To mitigate that, it\[cq]s possible to keep the repo just atop of an
-encrypted and non-public place.
+encrypted and non\-public place.
.RE
.IP "2." 3
History is not rewritten by default when secrets are removed from a
use this feature carefully.
.RE
.SH SEE ALSO
-.PP
The \f[I]README\f[R] file distributed with Keyringer contains full
documentation.
.PP
The Keyringer source code and all documentation may be downloaded from
-<https://keyringer.pw>.
+\c
+.UR https://keyringer.pw
+.UE \c
+\&.
.SH AUTHORS
-Silvio Rhatto <rhatto@riseup.net>.
+Silvio Rhatto \c
+.MT rhatto@riseup.net
+.ME \c.
projects / keyringer.git / commitdiff