diff options
| -rw-r--r-- | debian/copyright | 13 | ||||
| -rw-r--r-- | development.mdwn | 38 | ||||
| -rw-r--r-- | index.mdwn | 17 | ||||
| -rw-r--r-- | share/man/keyringer.1 | 79 | ||||
| -rw-r--r-- | share/man/keyringer.1.mdwn | 139 |
5 files changed, 212 insertions, 74 deletions
diff --git a/debian/copyright b/debian/copyright index 0c7a7af..51157ee 100644 --- a/debian/copyright +++ b/debian/copyright @@ -11,29 +11,22 @@ Upstream Author(s): Silvio Rhatto <rhatto@riseup.net> Daniel Kahn Gillmor <dkg@fifthhorseman.net> Jamie McClelland <jm@mayfirst.org> + ricola <ricola@poivron.org> Copyright: <Copyright (C) 2009-2012 Silvio Rhatto> <Copyright (C) 2010 Daniel Kahn Gillmor> <Copyright (C) 2012 Jamie McClelland> + <Copyright (C) 2012 ricola> License: - GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 + GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 or greater The Debian packaging is: Copyright (C) 2012 Silvio Rhatto <rhatto@riseup.net> -# Please chose a license for your packaging work. If the program you package -# uses a mainstream license, using the same license is the safest choice. -# Please avoid to pick license terms that are more restrictive than the -# packaged work, as it may make Debian's contributions unacceptable upstream. -# If you just want it to be GPL version 3, leave the following lines in. - and is licensed under the GPL version 3, see "/usr/share/common-licenses/GPL-3". - -# Please also look if there are files or directories which have a -# different copyright/license attached and list them here. diff --git a/development.mdwn b/development.mdwn new file mode 100644 index 0000000..874a408 --- /dev/null +++ b/development.mdwn @@ -0,0 +1,38 @@ +[[!meta title="Keyringer: development guidelines"]] + +Preparing the source code: + + make build_man + +Commit and tag release: + + git checkout master + git commit -m "Keyringer 0.1" + git tag -s + git checkout upstream + git merge master + git checkout debian + git merge master + git push --tags + +Creating the `debian/` structure: + + dh_make -p keyringer_0.1 --createorig + +Creating a release file: + + git archive --format=tar HEAD | gzip >../tarballs/keyringer-0.1.tar.gz + +To generate a `keyringer_0.1.orig.tar.gz`-line file: + + dh_make -f ../tarballs/keyringer-0.1.tar.gz -p keyringer_0.1 + +Building a package from the git three using the upstream branch: + + git-buildpackage + +References: + +* [Using Git for Debian Packaging](http://www.eyrie.org/~eagle/notes/debian/git.html). +* [Building packages from the Git repository](http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.building.html). + @@ -164,15 +164,12 @@ Concepts Basic idea is: - - Encrypt stuff with ppl's gpg pubkeys and push the output in a git repo. + - Encrypt stuff with multiple users's gpg pubkeys and push the output in a git repo. - - Let ppl keep it in sync with the repo and the keys are shared :) + - Let users keep it in sync with the repo and the secrets are shared :) -For "key" it's meant anything as the script work with stdin and output things to -files, so it can be passphrases, private keys or other kind of info. - -It's possible to share keys using an encrypted mailing list, but the main -difficulty is to track the message where the keys are. +For "secrets" it's meant anything as the script work with stdin and output things to +files, so it can be passphrases, private keys or other kind of information. With theses scripts, the workflow is more or less like this: @@ -185,7 +182,7 @@ With theses scripts, the workflow is more or less like this: - You manually add it to git and push it to remote repositories. - - Optionally, other ppl pulls the changes but they dont need to + - Optionally, other users pulls the changes but they dont need to decrypt anything until they need to use the keys. So it's just gpg-encrypted data atop of a git repository (one can think of a @@ -216,3 +213,7 @@ Optional dependencies if you want to manage ssl keys: - [OpenSSL](http://www.openssl.org) +Development guidelines +---------------------- + +See [development](development). 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 |