diff options
Diffstat (limited to 'share/man')
| -rw-r--r-- | share/man/keyringer.1 | 79 | ||||
| -rw-r--r-- | share/man/keyringer.1.mdwn | 139 |
2 files changed, 162 insertions, 56 deletions
diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index 2eaa30d..66ed9cc 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -1,4 +1,4 @@ -.TH KEYRINGER 1 "August 17, 2013" "Keyringer User Manual" +.TH KEYRINGER 1 "Sep 10, 2013" "Keyringer User Manual" .SH NAME .PP keyringer - encrypted and distributed secret sharing software @@ -9,39 +9,55 @@ keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]... .PP Keyringer lets you manage and share secrets using GPG and git with custom commands to encrypt, decrypt, recrypt, create key pairs, etc. +.PP +Secrets are encrypted using GPG and added to a git tree so later then +can be synced with remote branches. .SH ACTIONS .PP Keyringer has three types of actions: .IP "1." 3 -Configuration actions. +Repository lookup and manipulation actions. .IP "2." 3 Secret manipulation actions. .IP "3." 3 -Repository lookup and manipulation actions. -.SS CONFIGURATION ACTIONS -.PP -commands : List available actions, useful for shell completion and -syntax check. +Configuration actions. +.SS REPOSITORY LOOKUP AND MANIPULATION ACTIONS .PP -options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add -miscelaneous \f[I]repository options\f[]. +init <\f[I]path\f[]> [\f[I]remote\f[]] : Initialize a new keyringer +repository. +If a \f[I]remote\f[] URL is specified, keyringer will clone an existing +repository. .PP -preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add -\f[I]user options\f[] for a given repository. +After initialization, \f[I]path\f[] will contain a folder structure for +storing secrets and metadata (user aka recipients, groups of recipients, +etc). .PP -recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List -or edit recipient configuration. +Also, an entry on \f[C]$HOME/.keyringer/config\f[] will be added +allowing keyringer to find the keyring by it\[aq]s alias. .PP -usage : Show usage information. +git <\f[I]action\f[]> <\f[I]options\f[]> : Git wrapper that operates +from the toplevel keyring repository. +You can issue any \f[I]GIT(1)\f[] subcommand with this action that it +will be applied into the keyring repository. +.PP +ls <\f[I]path\f[]> : List contents from the toplevel repository +\f[I]keys\f[] folder or from relative paths if \f[I]path\f[] is +specified. +Like the git wrapper, this is a wrapper around the \f[I]LS(1)\f[] +command. .SS SECRET MANIPULATION ACTIONS .PP -All secret manipulation actions operates upon a \f[I]SECRET\f[], which -is the pathname of an encrypted file relative to keyring with optional +All secret manipulation actions operates upon a \f[I]SECRET\f[] which is +the pathname of an encrypted file relative to keyring with optional \f[C]\&.asc\f[] extension. .PP +If the \f[C]\&.asc\f[] extension is ommited, keyringer will add it in +the end of the pathname. +.PP Secret manipulation actions do not commit changes into the secret repository. -After any manipulation, the user has to manually commit the changes. +After any manipulation, the user has to manually commit the changes +using the git wrapper action. .PP append <\f[I]SECRET\f[]> : Append contents into a secret. .PP @@ -76,13 +92,32 @@ recrypting again. Useful when users are added into recipient configuration. If no \f[I]SECRET\f[] is given, all secrets in the repository are re-encrypted. -.SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS +.SS CONFIGURATION ACTIONS .PP -git <\f[I]action\f[]> <\f[I]options\f[]> : Git wrapper that operates -from the toplevel keyring repository. +commands : List available actions, useful for shell completion and +syntax check. +.PP +options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add +miscelaneous \f[I]repository options\f[]. +.PP +preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add +\f[I]user options\f[] for a given repository. +.PP +recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List +or edit recipient configuration. +.PP +usage : Show usage information. +.SH FILES +.PP +$HOME/.keyringer/config : User\[aq]s main configuration file used to map +alias names to keyrings. +.PP +$HOME/.keyringer/\f[I]keyring\f[] : User preferences for the keyringer +aliased \f[I]keyring\f[]. .PP -ls <\f[I]PATH\f[]> : List contents from the toplevel repository -\f[I]keys\f[] folder or from relative \f[I]PATH\f[]. +$KEYRING_FOLDER/config/options : Custom keyring options which will be +applied for all users that use the keyringer repository. +.SH LIMITATIONS .SH SEE ALSO .PP The \f[I]README\f[] file distributed with Keyringer contains full diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index 14ae687..3abf8b8 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -1,6 +1,6 @@ % KEYRINGER(1) Keyringer User Manual % Silvio Rhatto -% August 17, 2013 +% Sep 10, 2013 # NAME @@ -15,81 +15,152 @@ keyringer <*keyring*> <*action*> [*options*]... Keyringer lets you manage and share secrets using GPG and git with custom commands to encrypt, decrypt, recrypt, create key pairs, etc. +Secrets are encrypted using GPG and added to a git tree so later then can +be synced with remote branches. + # ACTIONS Keyringer has three types of actions: -1. Configuration actions. +1. Repository lookup and manipulation actions. 2. Secret manipulation actions. -3. Repository lookup and manipulation actions. +3. Configuration actions. -## CONFIGURATION ACTIONS +## REPOSITORY LOOKUP AND MANIPULATION ACTIONS -commands -: List available actions, useful for shell completion and syntax check. +init <*path*> [*remote*] +: Initialize a new keyringer repository. If a *remote* URL is specified, keyringer will + clone an existing repository. -options <*ls*|*edit*|*add*> -: List, edit or add miscelaneous *repository options*. + After initialization, *path* will contain a folder structure for storing secrets + and metadata (user aka recipients, groups of recipients, etc). -preferences <*ls*|*edit*|*add*> -: List, edit or add *user options* for a given repository. + Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to + find the keyring by it's alias. -recipients <*ls*|*edit*> <*recipient-file*> -: List or edit recipient configuration. +git <*action*> <*options*> +: Git wrapper that operates from the toplevel keyring repository. You can issue any + *GIT(1)* subcommand with this action that it will be applied into the keyring repository. -usage -: Show usage information. +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. ## SECRET MANIPULATION ACTIONS -All secret manipulation actions operates upon a *SECRET*, which is the pathname +All secret manipulation actions operates upon a *secret* which is the pathname of an encrypted file relative to keyring with optional `.asc` extension. +If the `.asc` extension is ommited, keyringer will add it in the end of the +pathname. + Secret manipulation actions do not commit changes into the secret repository. -After any manipulation, the user has to manually commit the changes. +After any manipulation, the user has to manually commit the changes using the +git wrapper action. -append <*SECRET*> +append <*secret*> : Append contents into a secret. -append-batch <*SECRET*> +append-batch <*secret*> : Append contents into a secret, batch mode. -decrypt <*SECRET*> +decrypt <*secret*> : Decrypts a secret into standard output. -del <*SECRET*> +del <*secret*> : Removes a secret using git. After deleting a secret a git commit and push is still needed to update remote repositories. To completely remove a file from a keyring, you should also rewrite the git history by yourself. -edit <*SECRET*> -: Edits a secret by temporarily decrypting it, opening the decrypted copy into *$EDITOR* - and then recrypting it again. +edit <*secret*> +: Edits a secret by temporarily decrypting it, opening the decrypted copy into the + text editor defined by the *$EDITOR* environment variable and then recrypting it + again. -encrypt [*file*] <*SECRET*> -: Encrypts content from standard input or *file* into *SECRET*. +encrypt [*file*] <*secret*> +: Encrypts content from standard input or *file* into *secret* pathname. -encrypt-batch <*SECRET*> +encrypt-batch <*secret*> : Encrypt content, batch mode. genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*] : Wrapper to generete encryption keypairs, useful for automated key deployment. -open <*SECRET*> +open <*secret*> : Open a secret using xdg-open. -recrypt <*SECRET*> +recrypt <*secret*> : Recrypts a secret by decrypting it and recrypting again. Useful when users are added - into recipient configuration. If no *SECRET* is given, all secrets in the repository + into recipient configuration. If no *secret* is given, all secrets in the repository are re-encrypted. -# REPOSITORY LOOKUP AND MANIPULATION ACTIONS +## CONFIGURATION ACTIONS -git <*action*> <*options*> -: Git wrapper that operates from the toplevel keyring repository. +commands +: List available actions, useful for shell completion and syntax check. + +options <*ls*|*edit*|*add*> +: List, edit or add miscelaneous *repository* options. + + Repository options are specific configurations for the keyring which are + saved into the repository, making it available for all users with access to the + repository and hence is a *global* configuration stanza for a given keyring. + +preferences <*ls*|*edit*|*add*> +: List, edit or add *user* preferences for a given repository. + + User preferences are specific configurations for the keyring which are + saved into the user's keyringer folder (`$HOME/.keyringer/`) hence not + shared with the other users. + +recipients <*ls*|*edit*> <*recipient-file*> +: List or edit recipient configuration. + + Recipient files are lists of OpenPGP public key fingerprints which are used + by keyringer when encrypting secrets. + + Keyringer uses a default recipient file and supports custom *recipient-files* which + overrides the default recipient file according to it's matching pathname. + + For instance, a the *recipient-file* called *accounting* will be used + wherever a user encrypts a secret to a file residing from the *accounting* + folder in the keyring repository. In that case, 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 `$KEYRING_FOLDER/config/recipients/accounting` config + file. + +### OPTIONS + +ls +: List all existing recipient files. + +edit +: Create or edit a recipient-file. + + Edition happens using the editor specified by the `$EDITOR` + environment variable. + + The required parameter *recipient-file* is taken relativelly + from the `$KEYRING_FOLDER/config/recipients/` folder. + +usage +: Show keyringer usage information. + +# 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. -ls <*PATH*> -: List contents from the toplevel repository *keys* folder or from relative *PATH*. +# LIMITATIONS # SEE ALSO |