From 5c0574c296ba0a1f0951f5d217f05fad0f1fcb00 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Thu, 5 Sep 2013 23:59:23 -0300 Subject: Adding initial development guidelines --- development.mdwn | 38 ++++++++++++++++++++++++++++++++++++++ index.mdwn | 4 ++++ 2 files changed, 42 insertions(+) create mode 100644 development.mdwn 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). + diff --git a/index.mdwn b/index.mdwn index 7ed01a6..f147d44 100644 --- a/index.mdwn +++ b/index.mdwn @@ -216,3 +216,7 @@ Optional dependencies if you want to manage ssl keys: - [OpenSSL](http://www.openssl.org) +Development guidelines +---------------------- + +See [development](development). -- cgit v1.2.3 From fa8858356ec9521795b86e677fd768f51789abbf Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Tue, 10 Sep 2013 14:00:42 -0300 Subject: Manpage: add init action and other changes --- index.mdwn | 13 ++++------ share/man/keyringer.1.mdwn | 63 +++++++++++++++++++++++++++++++++------------- 2 files changed, 50 insertions(+), 26 deletions(-) diff --git a/index.mdwn b/index.mdwn index f147d44..a9077c1 100644 --- a/index.mdwn +++ b/index.mdwn @@ -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 diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index 14ae687..e2e5ba7 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -15,30 +15,34 @@ 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. -usage -: Show usage information. +ls <*path*> +: List contents from the toplevel repository *keys* folder or from relative *path*. ## SECRET MANIPULATION ACTIONS @@ -83,13 +87,36 @@ recrypt <*SECRET*> 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*. + +preferences <*ls*|*edit*|*add*> +: List, edit or add *user options* for a given repository. + +recipients <*ls*|*edit*> <*recipient-file*> +: List or edit recipient configuration. + +usage +: Show 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_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 -- cgit v1.2.3 From 81f40da2218a3535f9cdd618f40b0b1afe48fa2a Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Tue, 10 Sep 2013 14:09:43 -0300 Subject: Manpage: more on git and ls actions --- share/man/keyringer.1.mdwn | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index e2e5ba7..6dc81c0 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -39,18 +39,22 @@ init <*path*> [*remote*] find the keyring by it's alias. git <*action*> <*options*> -: Git wrapper that operates from the toplevel keyring repository. +: 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. ls <*path*> -: List contents from the toplevel repository *keys* folder or from relative *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. 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 contents into a secret. -- cgit v1.2.3 From 9757393b4bd23f32b38cfc83b621221bde08397a Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Tue, 10 Sep 2013 15:24:50 -0300 Subject: Manpage: minor changes --- share/man/keyringer.1 | 79 +++++++++++++++++++++++++++++++++------------- share/man/keyringer.1.mdwn | 7 ++-- 2 files changed, 62 insertions(+), 24 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 6dc81c0..f6c1c84 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 @@ -26,7 +26,7 @@ Keyringer has three types of actions: 2. Secret manipulation actions. 3. Configuration actions. -# REPOSITORY LOOKUP AND MANIPULATION ACTIONS +## REPOSITORY LOOKUP AND MANIPULATION ACTIONS init <*path*> [*remote*] : Initialize a new keyringer repository. If a *remote* URL is specified, keyringer will @@ -52,6 +52,9 @@ ls <*path*> 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 using the git wrapper action. -- cgit v1.2.3 From b3cb10a7ad0512563ddd35fcc1490aceb3ee37be Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Tue, 10 Sep 2013 15:26:59 -0300 Subject: Manpage: change SECRET for secret --- share/man/keyringer.1.mdwn | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index f6c1c84..021875e 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -49,7 +49,7 @@ ls <*path*> ## 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 @@ -59,39 +59,39 @@ Secret manipulation actions do not commit changes into the secret repository. 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*> +edit <*secret*> : Edits a secret by temporarily decrypting it, opening the decrypted copy into *$EDITOR* 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*. -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. ## CONFIGURATION ACTIONS -- cgit v1.2.3 From 81eea6d2135ddf47954d79528e59e4c24b4cf164 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Tue, 10 Sep 2013 16:23:57 -0300 Subject: Manpage: describing options --- share/man/keyringer.1.mdwn | 51 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index 021875e..3abf8b8 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -74,11 +74,12 @@ del <*secret*> 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. +: 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*. +: Encrypts content from standard input or *file* into *secret* pathname. encrypt-batch <*secret*> : Encrypt content, batch mode. @@ -100,16 +101,52 @@ commands : List available actions, useful for shell completion and syntax check. options <*ls*|*edit*|*add*> -: List, edit or add miscelaneous *repository options*. +: 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 options* for a given repository. +: 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 usage information. +: Show keyringer usage information. # FILES @@ -117,7 +154,7 @@ $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*. +: User preferences for the keyringer aliased *keyring* keyring. $KEYRING_FOLDER/config/options : Custom keyring options which will be applied for all users that use -- cgit v1.2.3 From af51f2155f7b103ccf2752eac4ef580bc2fe67d4 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Thu, 12 Sep 2013 19:09:41 -0300 Subject: Fixing debian/copyright as of #10 --- debian/copyright | 13 +++---------- 1 file changed, 3 insertions(+), 10 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 Daniel Kahn Gillmor Jamie McClelland + ricola Copyright: + 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 -# 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. -- cgit v1.2.3