From 85d7c3258505b7f065e30d62024d22c796077726 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Thu, 24 Oct 2013 21:32:57 -0200 Subject: Manpage update --- share/man/keyringer.1 | 64 ++++++++++++++++++++++++++++++++++------------ share/man/keyringer.1.mdwn | 63 ++++++++++++++++++++++++++++++++------------- 2 files changed, 93 insertions(+), 34 deletions(-) (limited to 'share/man') diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index 9b6a2f5..c140dc5 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -1,4 +1,4 @@ -.TH KEYRINGER 1 "Sep 10, 2013" "Keyringer User Manual" +.TH KEYRINGER 1 "Oct 24, 2013" "Keyringer User Manual" .SH NAME .PP keyringer - encrypted and distributed secret sharing software @@ -7,8 +7,14 @@ keyringer - encrypted and distributed secret sharing software keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]... .SH DESCRIPTION .PP -Keyringer lets you manage and share secrets using GPG and git with -custom commands to encrypt, decrypt, recrypt, create key pairs, etc. +Keyringer lets you manage and share secrets using GnuPG and Git in a +distributed fashion. +.PP +It has custom commands to encrypt, decrypt and recrypt secrets as well +as create key pairs and supports encryption to multiple recipients and +groups of different recipients to ensure the same repository can be +shared with a workgroup but allowing to keep some secrets available just +to subsets of that group. .PP Secrets are encrypted using GPG and added to a git tree so later then can be synced with remote branches. @@ -58,10 +64,12 @@ No spaces are allowed in the secret name. .PP 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. +Instead, the user has to manually commit the changes using the git +wrapper action. .PP -append <\f[I]secret\f[]> : Append contents into a secret. +append <\f[I]secret\f[]> : Append contents into a secret by decrypting +the secret, appending lines read from the standard input and encrypting +again. .PP append-batch <\f[I]secret\f[]> : Append contents into a secret, batch mode. @@ -71,10 +79,12 @@ decrypt <\f[I]secret\f[]> : Decrypts a secret into standard output. del <\f[I]secret\f[]> : 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. .PP -edit <\f[I]secret\f[]> : Edits a secret by temporarily decrypting it, +Please note that this command \f[B]does not remove the secret from the +git history.\f[] To completely remove a file from a keyring, you should +also rewrite the git history by yourself. +.PP +edit <\f[I]secret\f[]> : Edit a secret by temporarily decrypting it, opening the decrypted copy into the text editor defined by the \f[I]$EDITOR\f[] environment variable and then recrypting it again. .PP @@ -88,7 +98,12 @@ genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]> [\f[I]options\f[]] : Wrapper to generete encryption keypairs, useful for automated key deployment. .PP -open <\f[I]secret\f[]> : Open a secret using xdg-open. +open <\f[I]secret\f[]> : Decrypt a secret into a temporary folder and +opening it using xdg-open which then tries to figure out the file type +and calling the associated application. +.PP +After the application exits, keyringer encrypts the temporary decrypted +file again into the secret file. .PP recrypt <\f[I]secret\f[]> : Recrypts a secret by decrypting it and recrypting again. @@ -108,6 +123,10 @@ saved into the repository, making it available for all users with access to the repository and hence is a \f[I]global\f[] configuration stanza for a given keyring. .PP +Options are written using the \f[I]KEY=VALUE\f[] syntax. +All lines starting with the hash (#) character are interpreted as +comments. +.PP preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add \f[I]user\f[] preferences for a given repository. .PP @@ -115,11 +134,18 @@ User preferences are specific configurations for the keyring which are saved into the user\[aq]s keyringer folder (\f[C]$HOME/.keyringer/\f[]) hence not shared with the other users. .PP -recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List -or edit recipient configuration. +Preferences are written using the \f[I]KEY=VALUE\f[] syntax. +All lines starting with the hash (#) character are interpreted as +comments. +.PP +usage : Show keyringer usage information. +.PP +recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List, +create or edit recipient configuration. .PP Recipient files are lists of OpenPGP public key fingerprints which are -used by keyringer when encrypting secrets. +used by keyringer when encrypting secrets and associated with email +aliases. .PP Keyringer uses a default recipient file and supports custom \f[I]recipient-files\f[] which overrides the default recipient file @@ -133,19 +159,25 @@ will result in a file \f[C]$KEYRING_FOLDER/keys/accounting/bank-accounts.asc\f[] encrypted using the public keys listed in \f[C]$KEYRING_FOLDER/config/recipients/accounting\f[] config file. +.PP +Each line in a recipients file has entries in the form of +\[aq]john\@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq], where +\f[I]john\@doe.com\f[] is an alias for the GPG public key whose +fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[] +.PP +All lines starting with the hash (#) character are interpreted as +comments. .SS OPTIONS .PP ls : List all existing recipient files. .PP edit : Create or edit a recipient-file. .PP -Edition happens using the editor specified by the \f[C]$EDITOR\f[] +Editing happens using the editor specified by the \f[C]$EDITOR\f[] environment variable. .PP The required parameter \f[I]recipient-file\f[] is taken relativelly from the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder. -.PP -usage : Show keyringer usage information. .SH FILES .PP $HOME/.keyringer/config : User\[aq]s main configuration file used to map diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index d7fb2a6..e4713bd 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -1,6 +1,6 @@ % KEYRINGER(1) Keyringer User Manual % Silvio Rhatto -% Sep 10, 2013 +% Oct 24, 2013 # NAME @@ -12,11 +12,17 @@ keyringer <*keyring*> <*action*> [*options*]... # DESCRIPTION -Keyringer lets you manage and share secrets using GPG and git with custom -commands to encrypt, decrypt, recrypt, create key pairs, etc. +Keyringer lets you manage and share secrets using GnuPG and Git in a +distributed fashion. -Secrets are encrypted using GPG and added to a git tree so later then can -be synced with remote branches. +It has custom commands to encrypt, decrypt and recrypt secrets as well as +create key pairs and supports encryption to multiple recipients and groups of +different recipients to ensure the same repository can be shared with a +workgroup but allowing to keep some secrets available just to subsets of that +group. + +Secrets are encrypted using GPG and added to a git tree so later then can be +synced with remote branches. # ACTIONS @@ -58,11 +64,12 @@ pathname. No spaces are allowed in the secret name. 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. +Instead, the user has to manually commit the changes using the git wrapper +action. append <*secret*> -: Append contents into a 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. @@ -72,11 +79,14 @@ decrypt <*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. + 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 by yourself. edit <*secret*> -: Edits a secret by temporarily decrypting it, opening the decrypted copy into the +: Edit 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. @@ -91,7 +101,11 @@ genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*] : Wrapper to generete encryption keypairs, useful for automated key deployment. open <*secret*> -: Open a secret using xdg-open. +: Decrypt a secret into a temporary folder and opening it using xdg-open which + then tries to figure out the file type and calling the associated application. + + After the application exits, keyringer encrypts the temporary decrypted file + again into the secret file. recrypt <*secret*> : Recrypts a secret by decrypting it and recrypting again. Useful when users are added @@ -110,6 +124,9 @@ options <*ls*|*edit*|*add*> 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. + 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. @@ -117,11 +134,17 @@ preferences <*ls*|*edit*|*add*> saved into the user's keyringer folder (`$HOME/.keyringer/`) hence 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. + recipients <*ls*|*edit*> <*recipient-file*> -: List or edit recipient configuration. +: List, create or edit recipient configuration. Recipient files are lists of OpenPGP public key fingerprints which are used - by keyringer when encrypting secrets. + by keyringer when encrypting secrets and associated with email aliases. Keyringer uses a default recipient file and supports custom *recipient-files* which overrides the default recipient file according to it's matching pathname. @@ -134,6 +157,13 @@ recipients <*ls*|*edit*> <*recipient-file*> public keys listed in `$KEYRING_FOLDER/config/recipients/accounting` config file. + Each line in a recipients file has entries in the form of + 'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where *john@doe.com* + is an alias for the GPG public key whose fingerprint is + *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.* + + All lines starting with the hash (#) character are interpreted as comments. + ### OPTIONS ls @@ -142,15 +172,12 @@ ls edit : Create or edit a recipient-file. - Edition happens using the editor specified by the `$EDITOR` + Editing 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 -- cgit v1.2.3 From bfc4231e2beb7507e4de5a3533b9e9dd7ed2e926 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Fri, 25 Oct 2013 20:45:37 -0200 Subject: Manpage formatting --- share/man/keyringer.1 | 174 +++++++++++++++++++++++++++++---------------- share/man/keyringer.1.mdwn | 158 ++++++++++++++++++++-------------------- 2 files changed, 191 insertions(+), 141 deletions(-) (limited to 'share/man') diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index c140dc5..c9c923b 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -27,12 +27,13 @@ Repository lookup and manipulation actions. Secret manipulation actions. .IP "3." 3 Configuration actions. -.SS REPOSITORY LOOKUP AND MANIPULATION ACTIONS -.PP -init <\f[I]path\f[]> [\f[I]remote\f[]] : Initialize a new keyringer -repository. +.SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS +.TP +.B 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. +.RS .PP After initialization, \f[I]path\f[] will contain a folder structure for storing secrets and metadata (user aka recipients, groups of recipients, @@ -40,18 +41,23 @@ etc). .PP 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 -git <\f[I]action\f[]> <\f[I]options\f[]> : Git wrapper that operates -from the toplevel keyring repository. +.RE +.TP +.B 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. +.RS +.RE +.TP +.B 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 +.RS +.RE +.SH 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 @@ -66,57 +72,87 @@ 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. -.PP -append <\f[I]secret\f[]> : Append contents into a secret by decrypting -the secret, appending lines read from the standard input and encrypting -again. -.PP -append-batch <\f[I]secret\f[]> : Append contents into a secret, batch -mode. -.PP -decrypt <\f[I]secret\f[]> : Decrypts a secret into standard output. -.PP -del <\f[I]secret\f[]> : Removes a secret using git. +.TP +.B append <\f[I]secret\f[]> +Append contents into a secret by decrypting the secret, appending lines +read from the standard input and encrypting again. +.RS +.RE +.TP +.B append-batch <\f[I]secret\f[]> +Append contents into a secret, batch mode. +.RS +.RE +.TP +.B decrypt <\f[I]secret\f[]> +Decrypts a secret into standard output. +.RS +.RE +.TP +.B del <\f[I]secret\f[]> +Removes a secret using git. After deleting a secret a git commit and push is still needed to update remote repositories. +.RS .PP Please note that this command \f[B]does not remove the secret from the git history.\f[] To completely remove a file from a keyring, you should also rewrite the git history by yourself. -.PP -edit <\f[I]secret\f[]> : Edit a secret by temporarily decrypting it, -opening the decrypted copy into the text editor defined by the -\f[I]$EDITOR\f[] environment variable and then recrypting it again. -.PP -encrypt [\f[I]file\f[]] <\f[I]secret\f[]> : Encrypts content from -standard input or \f[I]file\f[] into \f[I]secret\f[] pathname. +.RE +.TP +.B edit <\f[I]secret\f[]> +Edit a secret by temporarily decrypting it, opening the decrypted copy +into the text editor defined by the \f[I]$EDITOR\f[] environment +variable and then recrypting it again. +.RS +.RE +.TP +.B encrypt [\f[I]file\f[]] <\f[I]secret\f[]> +Encrypts content from standard input or \f[I]file\f[] into +\f[I]secret\f[] pathname. No spaces are supported in the \f[I]file\f[] name. -.PP -encrypt-batch <\f[I]secret\f[]> : Encrypt content, batch mode. -.PP -genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]> -[\f[I]options\f[]] : Wrapper to generete encryption keypairs, useful for -automated key deployment. -.PP -open <\f[I]secret\f[]> : Decrypt a secret into a temporary folder and -opening it using xdg-open which then tries to figure out the file type -and calling the associated application. +.RS +.RE +.TP +.B encrypt-batch <\f[I]secret\f[]> +Encrypt content, batch mode. +.RS +.RE +.TP +.B genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]> +[\f[I]options\f[]] +Wrapper to generete encryption keypairs, useful for automated key +deployment. +.RS +.RE +.TP +.B open <\f[I]secret\f[]> +Decrypt a secret into a temporary folder and opening it using xdg-open +which then tries to figure out the file type and calling the associated +application. +.RS .PP After the application exits, keyringer encrypts the temporary decrypted file again into the secret file. -.PP -recrypt <\f[I]secret\f[]> : Recrypts a secret by decrypting it and -recrypting again. +.RE +.TP +.B recrypt <\f[I]secret\f[]> +Recrypts a secret by decrypting it and 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. -.SS CONFIGURATION ACTIONS -.PP -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\f[] options. +.RS +.RE +.SH CONFIGURATION ACTIONS +.TP +.B commands +List available actions, useful for shell completion and syntax check. +.RS +.RE +.TP +.B options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> +List, edit or add miscelaneous \f[I]repository\f[] options. +.RS .PP Repository options are specific configurations for the keyring which are saved into the repository, making it available for all users with access @@ -126,9 +162,11 @@ for a given keyring. Options are written using the \f[I]KEY=VALUE\f[] syntax. All lines starting with the hash (#) character are interpreted as comments. -.PP -preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> : List, edit or add -\f[I]user\f[] preferences for a given repository. +.RE +.TP +.B preferences <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> +List, edit or add \f[I]user\f[] preferences for a given repository. +.RS .PP User preferences are specific configurations for the keyring which are saved into the user\[aq]s keyringer folder (\f[C]$HOME/.keyringer/\f[]) @@ -137,11 +175,16 @@ hence not shared with the other users. Preferences are written using the \f[I]KEY=VALUE\f[] syntax. All lines starting with the hash (#) character are interpreted as comments. -.PP -usage : Show keyringer usage information. -.PP -recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> : List, -create or edit recipient configuration. +.RE +.TP +.B usage +Show keyringer usage information. +.RS +.RE +.TP +.B recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> +List, create or edit recipient configuration. +.RS .PP Recipient files are lists of OpenPGP public key fingerprints which are used by keyringer when encrypting secrets and associated with email @@ -167,17 +210,24 @@ fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[] .PP All lines starting with the hash (#) character are interpreted as comments. +.RE .SS OPTIONS -.PP -ls : List all existing recipient files. -.PP -edit : Create or edit a recipient-file. +.TP +.B ls +List all existing recipient files. +.RS +.RE +.TP +.B edit +Create or edit a recipient-file. +.RS .PP Editing happens using the editor specified by the \f[C]$EDITOR\f[] environment variable. .PP The required parameter \f[I]recipient-file\f[] is taken relativelly from the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder. +.RE .SH FILES .PP $HOME/.keyringer/config : User\[aq]s main configuration file used to map diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index e4713bd..d77fb92 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -32,28 +32,28 @@ 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 - clone an existing repository. +: 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). + After initialization, *path* will contain a folder structure for storing secrets + and metadata (user aka recipients, groups of recipients, etc). - Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to - find the keyring by it's alias. + Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to + find the keyring by it's alias. 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. +: 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 paths - if *path* is specified. Like the git wrapper, this is a wrapper around the *LS(1)* - command. +: 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 +# SECRET MANIPULATION ACTIONS All secret manipulation actions operates upon a *secret* which is the pathname of an encrypted file relative to keyring with optional `.asc` extension. @@ -68,127 +68,127 @@ 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 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. +: Append contents into a secret, batch mode. decrypt <*secret*> -: Decrypts a secret into standard output. +: 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. +: 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 by yourself. + 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 by yourself. 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 recrypting it - again. +: Edit 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* pathname. No spaces - are supported in the *file* name. +: Encrypts content from standard input or *file* into *secret* pathname. No spaces + are supported in the *file* name. encrypt-batch <*secret*> -: Encrypt content, batch mode. +: Encrypt content, batch mode. genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*] -: Wrapper to generete encryption keypairs, useful for automated key deployment. +: Wrapper to generete encryption keypairs, useful for automated key deployment. open <*secret*> -: Decrypt a secret into a temporary folder and opening it using xdg-open which - then tries to figure out the file type and calling the associated application. +: Decrypt a secret into a temporary folder and opening it using xdg-open which + then tries to figure out the file type and calling the associated application. - After the application exits, keyringer encrypts the temporary decrypted file - again into the secret file. + After the application exits, keyringer encrypts the temporary decrypted file + again into the secret file. 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 - are re-encrypted. +: 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 + are re-encrypted. -## CONFIGURATION ACTIONS +# CONFIGURATION ACTIONS commands -: List available actions, useful for shell completion and syntax check. +: 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. + 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. - Options are written using the *KEY=VALUE* syntax. All lines starting with the - hash (#) character are interpreted as comments. + 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. +: 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. + 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. - Preferences are written using the *KEY=VALUE* syntax. All lines starting with the - hash (#) character are interpreted as comments. + Preferences are written using the *KEY=VALUE* syntax. All lines starting with the + hash (#) character are interpreted as comments. usage -: Show keyringer usage information. +: Show keyringer usage information. recipients <*ls*|*edit*> <*recipient-file*> -: List, create or edit recipient configuration. +: List, create or edit recipient configuration. - Recipient files are lists of OpenPGP public key fingerprints which are used - by keyringer when encrypting secrets and associated with email aliases. + Recipient 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 recipient file and supports custom *recipient-files* which - overrides the default recipient file according to it's matching pathname. + 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. + 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. - Each line in a recipients file has entries in the form of - 'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where *john@doe.com* - is an alias for the GPG public key whose fingerprint is - *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.* + Each line in a recipients file has entries in the form of + 'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where *john@doe.com* + is an alias for the GPG public key whose fingerprint is + *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.* - All lines starting with the hash (#) character are interpreted as comments. + All lines starting with the hash (#) character are interpreted as comments. -### OPTIONS +## OPTIONS ls -: List all existing recipient files. +: List all existing recipient files. edit -: Create or edit a recipient-file. +: Create or edit a recipient-file. - Editing happens using the editor specified by the `$EDITOR` - environment variable. + Editing 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. + The required parameter *recipient-file* is taken relativelly + from the `$KEYRING_FOLDER/config/recipients/` folder. # FILES $HOME/.keyringer/config -: User's main configuration file used to map alias names to keyrings. +: User's main configuration file used to map alias names to keyrings. $HOME/.keyringer/*keyring* -: User preferences for the keyringer aliased *keyring* 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. +: Custom keyring options which will be applied for all users that use + the keyringer repository. # LIMITATIONS -- cgit v1.2.3 From e52add756e7d6d79516e96639dd020303fc93348 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Fri, 25 Oct 2013 21:13:22 -0200 Subject: Manpage: limitations --- index.mdwn | 2 ++ share/man/keyringer.1 | 11 +++++---- share/man/keyringer.1.mdwn | 61 +++++++++++++++++++++++++++++++++++----------- 3 files changed, 55 insertions(+), 19 deletions(-) (limited to 'share/man') diff --git a/index.mdwn b/index.mdwn index 5985cf6..cc70d60 100644 --- a/index.mdwn +++ b/index.mdwn @@ -4,6 +4,8 @@ Keyringer lets you manage and share secrets using GPG and git with custom commands to encrypt, decrypt, recrypt, create key pairs, etc. - Project page: [https://keyringer.pw](https://keyringer.pw) +- Manpage: [keyringer.1](share/man/keyringer.1) +- License: [GPLv3+](LICENSE). - Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac) - Tor hidden service: [http://y6ntvl5bzs3c7ffa.onion](http://y6ntvl5bzs3c7ffa.onion) - Releases: [https://keyringer.pw/releases](releases) diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index c9c923b..9f9f835 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -210,15 +210,15 @@ fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[] .PP All lines starting with the hash (#) character are interpreted as comments. -.RE -.SS OPTIONS +.PP +Parameters to the \f[I]recipients\f[] subcommand are: .TP -.B ls +.B \f[I]ls\f[] List all existing recipient files. .RS .RE .TP -.B edit +.B \f[I]edit\f[] Create or edit a recipient-file. .RS .PP @@ -228,6 +228,7 @@ environment variable. The required parameter \f[I]recipient-file\f[] is taken relativelly from the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder. .RE +.RE .SH FILES .PP $HOME/.keyringer/config : User\[aq]s main configuration file used to map @@ -247,4 +248,4 @@ documentation. The Keyringer source code and all documentation may be downloaded from . .SH AUTHORS -Silvio Rhatto. +Silvio Rhatto . diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index d77fb92..7e79b35 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -1,6 +1,6 @@ % KEYRINGER(1) Keyringer User Manual -% Silvio Rhatto -% Oct 24, 2013 +% Silvio Rhatto +% Oct 25, 2013 # NAME @@ -28,9 +28,13 @@ synced with remote branches. Keyringer has three types of actions: -1. Repository lookup and manipulation actions. -2. Secret manipulation actions. -3. Configuration actions. +1. Repository lookup and manipulation actions, which handles repository initialization, + content tracking and navigation. + +2. Secret manipulation actions, which takes care of encrypting, decrypting and other + read/write operations on secrets. + +3. Configuration actions, handling repository metadata. # REPOSITORY LOOKUP AND MANIPULATION ACTIONS @@ -164,19 +168,19 @@ recipients <*ls*|*edit*> <*recipient-file*> All lines starting with the hash (#) character are interpreted as comments. -## OPTIONS + Parameters to the *recipients* action are: -ls -: List all existing recipient files. + *ls* + : List all existing recipient files. -edit -: Create or edit a recipient-file. + *edit* + : Create or edit a recipient-file. - Editing happens using the editor specified by the `$EDITOR` - environment variable. + Editing 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. + The required parameter *recipient-file* is taken relativelly + from the `$KEYRING_FOLDER/config/recipients/` folder. # FILES @@ -192,6 +196,35 @@ $KEYRING_FOLDER/config/options # LIMITATIONS +Keyringer currently has the following limitations: + +* Metadata is not encrypted, meaning that an attacker with access to a keyringer + repository knows all public key IDs are 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 *--hidden-recipient* GnuPG + option. + +* History is not rewritten by default when secrets are removed from a keyringer + repository. After a secret is removed with *del* action, it will still be + available in the repository history even after a commit. This is by design + due to the following reasons: + + 1. 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 is someone + mistakenly overwrites a secret. + + 2. 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 attack 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. + # SEE ALSO The *README* file distributed with Keyringer contains full documentation. -- cgit v1.2.3 From b348d0e911eef62732ebb01a63ad4ce59fbb4695 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Fri, 25 Oct 2013 21:13:44 -0200 Subject: Manpage: limitations (2) --- share/man/keyringer.1 | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) (limited to 'share/man') diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index 9f9f835..822c54e 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -1,4 +1,4 @@ -.TH KEYRINGER 1 "Oct 24, 2013" "Keyringer User Manual" +.TH KEYRINGER 1 "Oct 25, 2013" "Keyringer User Manual" .SH NAME .PP keyringer - encrypted and distributed secret sharing software @@ -22,11 +22,13 @@ can be synced with remote branches. .PP Keyringer has three types of actions: .IP "1." 3 -Repository lookup and manipulation actions. +Repository lookup and manipulation actions, which handles repository +initialization, content tracking and navigation. .IP "2." 3 -Secret manipulation actions. +Secret manipulation actions, which takes care of encrypting, decrypting +and other read/write operations on secrets. .IP "3." 3 -Configuration actions. +Configuration actions, handling repository metadata. .SH REPOSITORY LOOKUP AND MANIPULATION ACTIONS .TP .B init <\f[I]path\f[]> [\f[I]remote\f[]] @@ -211,7 +213,7 @@ fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[] All lines starting with the hash (#) character are interpreted as comments. .PP -Parameters to the \f[I]recipients\f[] subcommand are: +Parameters to the \f[I]recipients\f[] action are: .TP .B \f[I]ls\f[] List all existing recipient files. @@ -240,6 +242,38 @@ aliased \f[I]keyring\f[] keyring. $KEYRING_FOLDER/config/options : 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 \[bu] 2 +Metadata is not encrypted, meaning that an attacker with access to a +keyringer repository knows all public key IDs are 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 \f[I]--hidden-recipient\f[] GnuPG option. +.IP \[bu] 2 +History is not rewritten by default when secrets are removed from a +keyringer repository. +After a secret is removed with \f[I]del\f[] action, it will still be +available in the repository history even after a commit. +This is by design due to the following reasons: +.IP "1." 3 +It\[aq]s the default behavior of the Git content tracker. +Forcing the deletion by default could break the expected behavior and +hence limit the repository\[aq]s backup features, which can be helpful +is someone mistakenly overwrites a secret. +.IP "2." 3 +History rewriting cannot be considered a security measure against the +unauthorized access to a secret as it doesn\[aq]t automatically update +all working copies of the repository. +.RS 4 +.PP +In the case that the secret is a passphrase, the recommended measure +against such attack is to change the passphrase, making useless the +knowledge of the previous secret. +.PP +Users wishing to edit their repository history should proceed manually +using the \f[I]git\f[] action. +.RE .SH SEE ALSO .PP The \f[I]README\f[] file distributed with Keyringer contains full -- cgit v1.2.3 From 95416da3c798fb915c6a1d3ea515dd4bdb3d4437 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Fri, 25 Oct 2013 21:14:50 -0200 Subject: Manpage formatting --- index.mdwn | 2 +- share/man/keyringer.1.mdwn | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) (limited to 'share/man') diff --git a/index.mdwn b/index.mdwn index cc70d60..a26f903 100644 --- a/index.mdwn +++ b/index.mdwn @@ -5,7 +5,7 @@ commands to encrypt, decrypt, recrypt, create key pairs, etc. - Project page: [https://keyringer.pw](https://keyringer.pw) - Manpage: [keyringer.1](share/man/keyringer.1) -- License: [GPLv3+](LICENSE). +- License: [GPLv3+](LICENSE) - Issue tracker: [https://keyringer.pw/trac](https://keyringer.pw/trac) - Tor hidden service: [http://y6ntvl5bzs3c7ffa.onion](http://y6ntvl5bzs3c7ffa.onion) - Releases: [https://keyringer.pw/releases](releases) diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index 7e79b35..6b7915e 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -198,23 +198,23 @@ $KEYRING_FOLDER/config/options Keyringer currently has the following limitations: -* Metadata is not encrypted, meaning that an attacker with access to a keyringer +1. Metadata is not encrypted, meaning that an attacker with access to a keyringer repository knows all public key IDs are 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 *--hidden-recipient* GnuPG option. -* History is not rewritten by default when secrets are removed from a keyringer +2. History is not rewritten by default when secrets are removed from a keyringer repository. After a secret is removed with *del* action, it will still be available in the repository history even after a commit. This is by design due to the following reasons: - 1. It's the default behavior of the Git content tracker. Forcing the + - 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 is someone mistakenly overwrites a secret. - 2. History rewriting cannot be considered a security measure against the + - 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. -- cgit v1.2.3 From 75a1e30ead416c1e48b11ab416c4b32a3a15555d Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Fri, 25 Oct 2013 21:15:20 -0200 Subject: Manpage formatting (2) --- share/man/keyringer.1 | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'share/man') diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index 822c54e..0f6e62d 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -244,28 +244,28 @@ applied for all users that use the keyringer repository. .SH LIMITATIONS .PP Keyringer currently has the following limitations: -.IP \[bu] 2 +.IP "1." 3 Metadata is not encrypted, meaning that an attacker with access to a keyringer repository knows all public key IDs are 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 \f[I]--hidden-recipient\f[] GnuPG option. -.IP \[bu] 2 +.IP "2." 3 History is not rewritten by default when secrets are removed from a keyringer repository. After a secret is removed with \f[I]del\f[] action, it will still be available in the repository history even after a commit. This is by design due to the following reasons: -.IP "1." 3 +.IP \[bu] 2 It\[aq]s the default behavior of the Git content tracker. Forcing the deletion by default could break the expected behavior and hence limit the repository\[aq]s backup features, which can be helpful is someone mistakenly overwrites a secret. -.IP "2." 3 +.IP \[bu] 2 History rewriting cannot be considered a security measure against the unauthorized access to a secret as it doesn\[aq]t automatically update all working copies of the repository. -.RS 4 +.RS 2 .PP In the case that the secret is a passphrase, the recommended measure against such attack is to change the passphrase, making useless the -- cgit v1.2.3 From a063767e242051895afd9e44f6bcdcdeebc9eaef Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Sat, 26 Oct 2013 13:47:26 -0200 Subject: Minor manpage fix --- share/man/keyringer.1.mdwn | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'share/man') diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index 6b7915e..ab2242d 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -106,10 +106,10 @@ genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*] open <*secret*> : Decrypt a secret into a temporary folder and opening it using xdg-open which - then tries to figure out the file type and calling the associated application. + tries to figure out the file type and then calling the associated application. After the application exits, keyringer encrypts the temporary decrypted file - again into the secret file. + again into the secret file and deletes the temporary file. recrypt <*secret*> : Recrypts a secret by decrypting it and recrypting again. Useful when users are added -- cgit v1.2.3 From 03fee91e968daa553a197feb89eada9caa406d10 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Sun, 27 Oct 2013 14:29:00 -0200 Subject: Manpage english review (thanks Justin B Rye from debian-l10n-english) (#5) --- share/man/keyringer.1.mdwn | 107 +++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 56 deletions(-) (limited to 'share/man') diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index ab2242d..396e44d 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -15,23 +15,22 @@ keyringer <*keyring*> <*action*> [*options*]... Keyringer lets you manage and share secrets using GnuPG and Git in a distributed fashion. -It has custom commands to encrypt, decrypt and recrypt secrets as well as -create key pairs and supports encryption to multiple recipients and groups of -different recipients to ensure the same repository can be shared with a -workgroup but allowing to keep some secrets available just to subsets of that -group. +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 GPG and added to a git tree so later then can be -synced with remote branches. +Secrets are encrypted using GPG 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 handles repository initialization, +1. Repository lookup and manipulation actions, which handle repository initialization, content tracking and navigation. -2. Secret manipulation actions, which takes care of encrypting, decrypting and other +2. Secret manipulation actions, which take care of encrypting, decrypting and other read/write operations on secrets. 3. Configuration actions, handling repository metadata. @@ -45,12 +44,12 @@ init <*path*> [*remote*] After initialization, *path* will contain a folder structure for storing secrets and metadata (user aka recipients, groups of recipients, etc). - Also, an entry on `$HOME/.keyringer/config` will be added allowing keyringer to - find the keyring by it's alias. + Also, an entry will be added to `$HOME/.keyringer/config` allowing keyringer to + find the keyring by its alias. 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. + *GIT(1)* subcommand with this action to have it applied in the keyring repository. ls <*path*> : List contents from the toplevel repository *keys* folder or from relative paths @@ -59,10 +58,10 @@ ls <*path*> # SECRET MANIPULATION ACTIONS -All secret manipulation actions operates upon a *secret* which is the pathname -of an encrypted file relative to keyring with optional `.asc` extension. +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 ommited, keyringer will add it in the end of the +If the `.asc` extension is omitted, keyringer will add it at the end of the pathname. No spaces are allowed in the secret name. @@ -82,17 +81,16 @@ 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 +: 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 by yourself. + 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. 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 recrypting it - again. + text editor defined by the *$EDITOR* environment variable and then re-encrypting it. encrypt [*file*] <*secret*> : Encrypts content from standard input or *file* into *secret* pathname. No spaces @@ -102,18 +100,18 @@ encrypt-batch <*secret*> : Encrypt content, batch mode. genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*] -: Wrapper to generete encryption keypairs, useful for automated key deployment. +: Wrapper to generate encryption key-pairs, useful for automated key deployment. open <*secret*> -: Decrypt a secret into a temporary folder and opening it using xdg-open which - tries to figure out the file type and then calling the associated application. +: 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. 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 +: 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. # CONFIGURATION ACTIONS @@ -122,11 +120,11 @@ 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 miscellaneous *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. + 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. @@ -134,9 +132,8 @@ options <*ls*|*edit*|*add*> 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. + 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. @@ -144,24 +141,22 @@ preferences <*ls*|*edit*|*add*> usage : Show keyringer usage information. -recipients <*ls*|*edit*> <*recipient-file*> -: List, create or edit recipient configuration. +recipients <*ls*|*edit*> <*recipients-file*> +: List, create or edit recipients configuration. - Recipient files are lists of OpenPGP public key fingerprints which are used + 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 recipient file and supports custom *recipient-files* which - overrides the default recipient file according to it's matching pathname. + Keyringer uses a default recipients file, but specifying a custom *recipients-file* + pathname will override this default. - 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. + 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 form of + Each line in a recipients file has entries in the format 'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where *john@doe.com* is an alias for the GPG public key whose fingerprint is *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.* @@ -171,16 +166,16 @@ recipients <*ls*|*edit*> <*recipient-file*> Parameters to the *recipients* action are: *ls* - : List all existing recipient files. + : List all existing recipients files. *edit* - : Create or edit a recipient-file. + : Create or edit a recipients file. Editing 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. + The required parameter *recipients-file* is interpreted relative + to the `$KEYRING_FOLDER/config/recipients/` folder. # FILES @@ -199,19 +194,19 @@ $KEYRING_FOLDER/config/options Keyringer currently has the following limitations: 1. Metadata is not encrypted, meaning that an attacker with access to a keyringer - repository knows all public key IDs are used for encryption and which secrets + 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 *--hidden-recipient* GnuPG + the repository configuration with support for the *--hidden-recipient* GnuPG option. 2. History is not rewritten by default when secrets are removed from a keyringer - repository. After a secret is removed with *del* action, it will still be + 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 - due to the following reasons: + 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 is someone + 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 @@ -219,7 +214,7 @@ Keyringer currently has the following limitations: working copies of the repository. In the case that the secret is a passphrase, the recommended measure - against such attack is to change the passphrase, making useless the + 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 -- cgit v1.2.3 From e53aba05b0a18c39b5f75267318694d2073248f2 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Sun, 10 Nov 2013 22:44:58 -0200 Subject: Changing encrypt syntax, rebuilding manpage --- lib/keyringer/actions/encrypt | 22 +++++- lib/keyringer/functions | 14 ++-- share/man/keyringer.1 | 166 +++++++++++++++++++++--------------------- share/man/keyringer.1.mdwn | 4 +- 4 files changed, 111 insertions(+), 95 deletions(-) (limited to 'share/man') diff --git a/lib/keyringer/actions/encrypt b/lib/keyringer/actions/encrypt index 6b9c061..d9d8f96 100755 --- a/lib/keyringer/actions/encrypt +++ b/lib/keyringer/actions/encrypt @@ -7,11 +7,27 @@ LIB="`dirname $0`/../functions" source "$LIB" || exit 1 +# Usage +function keyringer_usage_encrypt { + echo "Usage: keyringer $BASENAME [file]" +} + +# Alias for keyringer_usage_encrypt +function keyringer_usage_encrypt_batch { + keyringer_usage_encrypt $* +} + +# Usage +if [ -z "$2" ]; then + keyringer_action_usage + exit 1 +fi + # Aditional parameters if [ ! -z "$3" ]; then - shift 1 + keyringer_get_new_file $2 + shift 2 UNENCRYPTED_FILE="$*" - keyringer_get_new_file $* if [ ! -f "$UNENCRYPTED_FILE" ]; then echo "Error: cannot encrypt $UNENCRYPTED_FILE: file not found." @@ -45,7 +61,7 @@ if [ "$err" != "0" ]; then fi if [ "$UNENCRYPTED_FILE" != "-" ]; then - echo "Now make to wipe the non-encrypted $UNENCRYPTED_FILE." + echo "Done. PLEASE WIPE the non-encrypted $UNENCRYPTED_FILE." fi # Stage diff --git a/lib/keyringer/functions b/lib/keyringer/functions index 67b5122..bf2977d 100755 --- a/lib/keyringer/functions +++ b/lib/keyringer/functions @@ -347,14 +347,16 @@ function keyringer_get_new_file { fi # Sanitize and complete file name - FILE="`echo $FILE | sed -e s/[^A-Za-z0-9.\/]/_/g`" - FILE="$(keyringer_filename "$FILE")" + FILE="`echo $FILE | sed -e s/[^A-Za-z0-9.\/\-]/_/g`" - # Warn user about file name change:w - if [ "`basename "$*"`" != "$FILE" ]; then + # Warn user about file name change + if [ "`basename $*`" != "`basename $FILE`" ]; then echo "Sanitizing destination filename to `basename $FILE`" fi - + + # Complete file name + FILE="$(keyringer_filename "$FILE")" + if [ -z "$*" ]; then keyringer_action_usage exit 1 @@ -365,7 +367,7 @@ function keyringer_get_new_file { function keyringer_get_command { # Aditional parameters COMMAND="$1" - + if [ -z "$COMMAND" ]; then keyringer_action_usage command exit 1 diff --git a/share/man/keyringer.1 b/share/man/keyringer.1 index 0f6e62d..c3fbc54 100644 --- a/share/man/keyringer.1 +++ b/share/man/keyringer.1 @@ -10,22 +10,22 @@ keyringer <\f[I]keyring\f[]> <\f[I]action\f[]> [\f[I]options\f[]]... Keyringer lets you manage and share secrets using GnuPG and Git in a distributed fashion. .PP -It has custom commands to encrypt, decrypt and recrypt secrets as well -as create key pairs and supports encryption to multiple recipients and -groups of different recipients to ensure the same repository can be -shared with a workgroup but allowing to keep some secrets available just -to subsets of that group. -.PP -Secrets are encrypted using GPG and added to a git tree so later then -can be synced with remote branches. +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. +.PP +Secrets are encrypted using GPG 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 handles repository +Repository lookup and manipulation actions, which handle repository initialization, content tracking and navigation. .IP "2." 3 -Secret manipulation actions, which takes care of encrypting, decrypting +Secret manipulation actions, which take care of encrypting, decrypting and other read/write operations on secrets. .IP "3." 3 Configuration actions, handling repository metadata. @@ -41,14 +41,14 @@ After initialization, \f[I]path\f[] will contain a folder structure for storing secrets and metadata (user aka recipients, groups of recipients, etc). .PP -Also, an entry on \f[C]$HOME/.keyringer/config\f[] will be added -allowing keyringer to find the keyring by it\[aq]s alias. +Also, an entry will be added to \f[C]$HOME/.keyringer/config\f[] +allowing keyringer to find the keyring by its alias. .RE .TP .B 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. +You can issue any \f[I]GIT(1)\f[] subcommand with this action to have it +applied in the keyring repository. .RS .RE .TP @@ -61,11 +61,11 @@ command. .RE .SH 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 operate upon a \f[I]secret\f[] which is +the pathname of an encrypted file relative to the keyring with optional \f[C]\&.asc\f[] extension. .PP -If the \f[C]\&.asc\f[] extension is ommited, keyringer will add it in +If the \f[C]\&.asc\f[] extension is omitted, keyringer will add it at the end of the pathname. .PP No spaces are allowed in the secret name. @@ -92,27 +92,27 @@ Decrypts a secret into standard output. .RE .TP .B del <\f[I]secret\f[]> -Removes a secret using git. +Removes a secret using Git. After deleting a secret a git commit and push is still needed to update remote repositories. .RS .PP Please note that this command \f[B]does not remove the secret from the -git history.\f[] To completely remove a file from a keyring, you should -also rewrite the git history by yourself. +Git history.\f[] To completely remove a file from a keyring, you should +also rewrite the Git history yourself. .RE .TP .B edit <\f[I]secret\f[]> Edit a secret by temporarily decrypting it, opening the decrypted copy into the text editor defined by the \f[I]$EDITOR\f[] environment -variable and then recrypting it again. +variable and then re-encrypting it. .RS .RE .TP -.B encrypt [\f[I]file\f[]] <\f[I]secret\f[]> +.B encrypt <\f[I]secret\f[]> [\f[I]file\f[]] Encrypts content from standard input or \f[I]file\f[] into \f[I]secret\f[] pathname. -No spaces are supported in the \f[I]file\f[] name. +No spaces are supported in the \f[I]secret\f[] name. .RS .RE .TP @@ -123,24 +123,24 @@ Encrypt content, batch mode. .TP .B genpair <\f[I]ssh\f[]|\f[I]gpg\f[]|\f[I]ssl\f[]|\f[I]ssl-self\f[]> [\f[I]options\f[]] -Wrapper to generete encryption keypairs, useful for automated key +Wrapper to generate encryption key-pairs, useful for automated key deployment. .RS .RE .TP .B open <\f[I]secret\f[]> -Decrypt a secret into a temporary folder and opening it using xdg-open -which then tries to figure out the file type and calling the associated +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 .PP After the application exits, keyringer encrypts the temporary decrypted -file again into the secret file. +file again into the secret file and deletes the temporary file. .RE .TP .B recrypt <\f[I]secret\f[]> -Recrypts a secret by decrypting it and recrypting again. -Useful when users are added into recipient configuration. +Re-encrypts a secret by decrypting it and encrypting it again. +Useful when users are added into the recipient configuration. If no \f[I]secret\f[] is given, all secrets in the repository are re-encrypted. .RS @@ -153,13 +153,12 @@ List available actions, useful for shell completion and syntax check. .RE .TP .B options <\f[I]ls\f[]|\f[I]edit\f[]|\f[I]add\f[]> -List, edit or add miscelaneous \f[I]repository\f[] options. +List, edit or add miscellaneous \f[I]repository\f[] options. .RS .PP -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 \f[I]global\f[] configuration stanza -for a given keyring. +Repository options are settings which are saved in the repository as a +\f[I]global\f[] configuration stanza for a given keyring, shared by all +users with access to the repository. .PP Options are written using the \f[I]KEY=VALUE\f[] syntax. All lines starting with the hash (#) character are interpreted as @@ -170,9 +169,9 @@ comments. List, edit or add \f[I]user\f[] preferences for a given repository. .RS .PP -User preferences are specific configurations for the keyring which are -saved into the user\[aq]s keyringer folder (\f[C]$HOME/.keyringer/\f[]) -hence not shared with the other users. +User preferences are settings which are saved in the user\[aq]s +keyringer folder (\f[C]$HOME/.keyringer/\f[]), and not shared with the +other users. .PP Preferences are written using the \f[I]KEY=VALUE\f[] syntax. All lines starting with the hash (#) character are interpreted as @@ -184,53 +183,51 @@ Show keyringer usage information. .RS .RE .TP -.B recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipient-file\f[]> -List, create or edit recipient configuration. +.B recipients <\f[I]ls\f[]|\f[I]edit\f[]> <\f[I]recipients-file\f[]> +List, create or edit recipients configuration. .RS .PP -Recipient files are lists of OpenPGP public key fingerprints which are +Recipients files are lists of OpenPGP public key fingerprints which are used by keyringer when encrypting secrets and associated with email aliases. .PP -Keyringer uses a default recipient file and supports custom -\f[I]recipient-files\f[] which overrides the default recipient file -according to it\[aq]s matching pathname. -.PP -For instance, a the \f[I]recipient-file\f[] called \f[I]accounting\f[] -will be used wherever a user encrypts a secret to a file residing from -the \f[I]accounting\f[] folder in the keyring repository. -In that case, encrypting a secret into \f[I]accounting/bank-accounts\f[] -will result in a file -\f[C]$KEYRING_FOLDER/keys/accounting/bank-accounts.asc\f[] encrypted -using the public keys listed in -\f[C]$KEYRING_FOLDER/config/recipients/accounting\f[] config file. -.PP -Each line in a recipients file has entries in the form of -\[aq]john\@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq], where -\f[I]john\@doe.com\f[] is an alias for the GPG public key whose -fingerprint is \f[I]XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.\f[] -.PP -All lines starting with the hash (#) character are interpreted as -comments. -.PP -Parameters to the \f[I]recipients\f[] action are: -.TP -.B \f[I]ls\f[] -List all existing recipient files. -.RS +Keyringer uses a default recipients file, but specifying a custom +\f[I]recipients-file\f[] pathname will override this default. +For instance, if a user encrypts a secret to a file in the keyring +repository\[aq]s \f[I]accounting\f[] folder, a \f[I]recipients-file\f[] +under \f[I]accounting\f[] will be used. +Encrypting a secret into \f[I]accounting/bank-accounts\f[] will result +in a file .RE -.TP -.B \f[I]edit\f[] -Create or edit a recipient-file. -.RS .PP -Editing happens using the editor specified by the \f[C]$EDITOR\f[] -environment variable. -.PP -The required parameter \f[I]recipient-file\f[] is taken relativelly from -the \f[C]$KEYRING_FOLDER/config/recipients/\f[] folder. -.RE -.RE +\f[C]$KEYRING_FOLDER/keys/accounting/bank-accounts.asc\f[] encrypted +using the public keys listed in the config +file\f[C]$KEYRING_FOLDER/config/recipients/accounting\f[]. +.IP +.nf +\f[C] +Each\ line\ in\ a\ recipients\ file\ has\ entries\ in\ the\ format +\[aq]john\@doe.com\ XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\[aq],\ where\ *john\@doe.com* +is\ an\ alias\ for\ the\ GPG\ 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. +\f[] +.fi .SH FILES .PP $HOME/.keyringer/config : User\[aq]s main configuration file used to map @@ -246,21 +243,22 @@ applied for all users that use the keyringer repository. Keyringer currently has the following limitations: .IP "1." 3 Metadata is not encrypted, meaning that an attacker with access to a -keyringer repository knows all public key IDs are used for encryption -and which secrets are encrypted to which keys. +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 \f[I]--hidden-recipient\f[] GnuPG option. +configuration with support for the \f[I]--hidden-recipient\f[] GnuPG +option. .IP "2." 3 History is not rewritten by default when secrets are removed from a keyringer repository. -After a secret is removed with \f[I]del\f[] action, it will still be +After a secret is removed with the \f[I]del\f[] action, it will still be available in the repository history even after a commit. -This is by design due to the following reasons: +This is by design for the following reasons: .IP \[bu] 2 It\[aq]s the default behavior of the Git content tracker. Forcing the deletion by default could break the expected behavior and hence limit the repository\[aq]s backup features, which can be helpful -is someone mistakenly overwrites a secret. +if someone mistakenly overwrites a secret. .IP \[bu] 2 History rewriting cannot be considered a security measure against the unauthorized access to a secret as it doesn\[aq]t automatically update @@ -268,7 +266,7 @@ all working copies of the repository. .RS 2 .PP In the case that the secret is a passphrase, the recommended measure -against such attack is to change the passphrase, making useless the +against such attacks is to change the passphrase, making useless the knowledge of the previous secret. .PP Users wishing to edit their repository history should proceed manually diff --git a/share/man/keyringer.1.mdwn b/share/man/keyringer.1.mdwn index 396e44d..ee035e3 100644 --- a/share/man/keyringer.1.mdwn +++ b/share/man/keyringer.1.mdwn @@ -92,9 +92,9 @@ 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. -encrypt [*file*] <*secret*> +encrypt <*secret*> [*file*] : Encrypts content from standard input or *file* into *secret* pathname. No spaces - are supported in the *file* name. + are supported in the *secret* name. encrypt-batch <*secret*> : Encrypt content, batch mode. -- cgit v1.2.3 From f51ab08305fe8aea78925468911756a672005396 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Sun, 10 Nov 2013 23:23:38 -0200 Subject: Adding keyringer.pot --- development.mdwn | 8 + share/man/keyringer.pot | 603 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 611 insertions(+) create mode 100644 share/man/keyringer.pot (limited to 'share/man') diff --git a/development.mdwn b/development.mdwn index edd41ed..43aeedb 100644 --- a/development.mdwn +++ b/development.mdwn @@ -113,6 +113,14 @@ Teardown: rm ~/.keyringer/test sed -i -e '/^test=/d' ~/.keyringer/config +Translation +----------- + +Run just once: + + cd share/man + po4a-gettextize -f text -m keyringer.1.mdwn -p keyringer.pot + References ---------- diff --git a/share/man/keyringer.pot b/share/man/keyringer.pot new file mode 100644 index 0000000..4078028 --- /dev/null +++ b/share/man/keyringer.pot @@ -0,0 +1,603 @@ +# SOME DESCRIPTIVE TITLE +# Copyright (C) YEAR Free Software Foundation, Inc. +# This file is distributed under the same license as the PACKAGE package. +# FIRST AUTHOR , YEAR. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PACKAGE VERSION\n" +"POT-Creation-Date: 2013-11-10 23:20-0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"Language: \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=CHARSET\n" +"Content-Transfer-Encoding: 8bit\n" + +#. type: Plain text +#: keyringer.1.mdwn:4 +msgid "" +"% KEYRINGER(1) Keyringer User Manual % Silvio Rhatto % " +"Oct 25, 2013" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:6 +msgid "# NAME" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:8 +msgid "keyringer - encrypted and distributed secret sharing software" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:10 +msgid "# SYNOPSIS" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:12 +msgid "keyringer <*keyring*> <*action*> [*options*]..." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:14 +msgid "# DESCRIPTION" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:17 +msgid "" +"Keyringer lets you manage and share secrets using GnuPG and Git in a " +"distributed fashion." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:22 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:25 +msgid "" +"Secrets are encrypted using GPG and added to a Git tree so that they can be " +"synced with remote branches later." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:27 +msgid "# ACTIONS" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:29 +msgid "Keyringer has three types of actions:" +msgstr "" + +#. type: Bullet: '1. ' +#: keyringer.1.mdwn:32 +msgid "" +"Repository lookup and manipulation actions, which handle repository " +"initialization, content tracking and navigation." +msgstr "" + +#. type: Bullet: '2. ' +#: keyringer.1.mdwn:35 +msgid "" +"Secret manipulation actions, which take care of encrypting, decrypting and " +"other read/write operations on secrets." +msgstr "" + +#. type: Bullet: '3. ' +#: keyringer.1.mdwn:37 +msgid "Configuration actions, handling repository metadata." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:39 +msgid "# REPOSITORY LOOKUP AND MANIPULATION ACTIONS" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:43 +#, no-wrap +msgid "" +"init <*path*> [*remote*]\n" +": Initialize a new keyringer repository. If a *remote* URL is specified, " +"keyringer will\n" +" clone an existing repository.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:46 +#, no-wrap +msgid "" +" After initialization, *path* will contain a folder structure for storing " +"secrets\n" +" and metadata (user aka recipients, groups of recipients, etc).\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:49 +#, no-wrap +msgid "" +" Also, an entry will be added to `$HOME/.keyringer/config` allowing " +"keyringer to\n" +" find the keyring by its alias.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:53 +#, no-wrap +msgid "" +"git <*action*> <*options*>\n" +": Git wrapper that operates from the toplevel keyring repository. You can " +"issue any\n" +" *GIT(1)* subcommand with this action to have it applied in the keyring " +"repository.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:58 +#, no-wrap +msgid "" +"ls <*path*>\n" +": List contents from the toplevel repository *keys* folder or from " +"relative paths\n" +" if *path* is specified. Like the git wrapper, this is a wrapper around " +"the *LS(1)*\n" +" command.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:60 +msgid "# SECRET MANIPULATION ACTIONS" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:63 +msgid "" +"All secret manipulation actions operate upon a *secret* which is the " +"pathname of an encrypted file relative to the keyring with optional `.asc` " +"extension." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:66 +msgid "" +"If the `.asc` extension is omitted, keyringer will add it at the end of the " +"pathname." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:68 +msgid "No spaces are allowed in the secret name." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:72 +msgid "" +"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." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:76 +#, no-wrap +msgid "" +"append <*secret*>\n" +": Append contents into a secret by decrypting the secret, appending lines " +"read\n" +" from the standard input and encrypting again.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:79 +#, no-wrap +msgid "" +"append-batch <*secret*>\n" +": Append contents into a secret, batch mode.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:82 +#, no-wrap +msgid "" +"decrypt <*secret*>\n" +": Decrypts a secret into standard output.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:86 +#, no-wrap +msgid "" +"del <*secret*>\n" +": Removes a secret using Git. After deleting a secret a git commit and " +"push is still\n" +" needed to update remote repositories.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:90 +#, no-wrap +msgid "" +" Please note that this command **does not remove the secret from the Git " +"history.**\n" +" To completely remove a file from a keyring, you should also rewrite the " +"Git\n" +" history yourself.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:94 +#, no-wrap +msgid "" +"edit <*secret*>\n" +": Edit a secret by temporarily decrypting it, opening the decrypted copy " +"into the \n" +" text editor defined by the *$EDITOR* environment variable and then " +"re-encrypting it.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:98 +#, no-wrap +msgid "" +"encrypt <*secret*> [*file*]\n" +": Encrypts content from standard input or *file* into *secret* " +"pathname. No spaces\n" +" are supported in the *secret* name.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:101 +#, no-wrap +msgid "" +"encrypt-batch <*secret*>\n" +": Encrypt content, batch mode.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:104 +#, no-wrap +msgid "" +"genpair <*ssh*|*gpg*|*ssl*|*ssl-self*> [*options*]\n" +": Wrapper to generate encryption key-pairs, useful for automated key " +"deployment.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:108 +#, no-wrap +msgid "" +"open <*secret*>\n" +": Decrypt a secret into a temporary folder and open it using xdg-open, " +"which\n" +" tries to figure out the file type and then calls the associated " +"application.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:111 +#, no-wrap +msgid "" +" After the application exits, keyringer encrypts the temporary decrypted " +"file\n" +" again into the secret file and deletes the temporary file.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:116 +#, no-wrap +msgid "" +"recrypt <*secret*>\n" +": Re-encrypts a secret by decrypting it and encrypting it again. Useful " +"when users are added\n" +" into the recipient configuration. If no *secret* is given, all secrets " +"in the repository\n" +" are re-encrypted.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:118 +msgid "# CONFIGURATION ACTIONS" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:121 +#, no-wrap +msgid "" +"commands\n" +": List available actions, useful for shell completion and syntax check.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:124 +#, no-wrap +msgid "" +"options <*ls*|*edit*|*add*>\n" +": List, edit or add miscellaneous *repository* options.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:128 +#, no-wrap +msgid "" +" Repository options are settings which are saved in the repository as a " +"*global*\n" +" configuration stanza for a given keyring, shared by all users with " +"access to\n" +" the repository.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:131 +#, no-wrap +msgid "" +" Options are written using the *KEY=VALUE* syntax. All lines starting " +"with the\n" +" hash (#) character are interpreted as comments.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:134 +#, no-wrap +msgid "" +"preferences <*ls*|*edit*|*add*>\n" +": List, edit or add *user* preferences for a given repository.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:137 +#, no-wrap +msgid "" +" User preferences are settings which are saved in the user's keyringer " +"folder\n" +" (`$HOME/.keyringer/`), and not shared with the other users.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:140 +#, no-wrap +msgid "" +" Preferences are written using the *KEY=VALUE* syntax. All lines starting " +"with the\n" +" hash (#) character are interpreted as comments.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:143 +#, no-wrap +msgid "" +"usage\n" +": Show keyringer usage information.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:146 +#, no-wrap +msgid "" +"recipients <*ls*|*edit*> <*recipients-file*>\n" +": List, create or edit recipients configuration.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:149 +#, no-wrap +msgid "" +" Recipients files are lists of OpenPGP public key fingerprints which are " +"used\n" +" by keyringer when encrypting secrets and associated with email " +"aliases.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:152 +#, no-wrap +msgid "" +" Keyringer uses a default recipients file, but specifying a custom " +"*recipients-file*\n" +" pathname will override this default.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:158 +#, no-wrap +msgid "" +" For instance, if a user encrypts a secret to a file in the keyring " +"repository's\n" +" *accounting* folder, a *recipients-file* under *accounting* will be " +"used.\n" +" Encrypting a secret into *accounting/bank-accounts* will result in a " +"file\n" +" `$KEYRING_FOLDER/keys/accounting/bank-accounts.asc` encrypted using the " +"public\n" +" keys listed in the config " +"file`$KEYRING_FOLDER/config/recipients/accounting`.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:163 +#, no-wrap +msgid "" +" Each line in a recipients file has entries in the format\n" +" 'john@doe.com XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX', where " +"*john@doe.com*\n" +" is an alias for the GPG public key whose fingerprint is\n" +" *XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.*\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:165 +#, no-wrap +msgid "" +" All lines starting with the hash (#) character are interpreted as " +"comments.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:167 +#, no-wrap +msgid " Parameters to the *recipients* action are:\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:170 +#, no-wrap +msgid "" +" *ls*\n" +" : List all existing recipients files.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:173 +#, no-wrap +msgid "" +" *edit*\n" +" : Create or edit a recipients file.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:176 +#, no-wrap +msgid "" +" Editing happens using the editor specified by the `$EDITOR`\n" +" environment variable.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:179 +#, no-wrap +msgid "" +" The required parameter *recipients-file* is interpreted relative\n" +" to the `$KEYRING_FOLDER/config/recipients/` folder.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:181 +msgid "# FILES" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:184 +msgid "" +"$HOME/.keyringer/config : User's main configuration file used to map alias " +"names to keyrings." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:187 +msgid "" +"$HOME/.keyringer/*keyring* : User preferences for the keyringer aliased " +"*keyring* keyring." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:191 +#, no-wrap +msgid "" +"$KEYRING_FOLDER/config/options\n" +": Custom keyring options which will be applied for all users that use\n" +" the keyringer repository.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:193 +msgid "# LIMITATIONS" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:195 +msgid "Keyringer currently has the following limitations:" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:201 +#, no-wrap +msgid "" +"1. Metadata is not encrypted, meaning that an attacker with access to a " +"keyringer\n" +" repository can discover all public key IDs used for encryption, and which " +"secrets\n" +" are encrypted to which keys. This can be improved in the future by " +"encrypting\n" +" the repository configuration with support for the *--hidden-recipient* " +"GnuPG\n" +" option.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:206 +#, no-wrap +msgid "" +"2. History is not rewritten by default when secrets are removed from a " +"keyringer\n" +" repository. After a secret is removed with the *del* action, it will still " +"be\n" +" available in the repository history even after a commit. This is by " +"design\n" +" for the following reasons:\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:211 +#, no-wrap +msgid "" +" - It's the default behavior of the Git content tracker. Forcing the\n" +" deletion by default could break the expected behavior and hence limit\n" +" the repository's backup features, which can be helpful if someone\n" +" mistakenly overwrites a secret.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:215 +#, no-wrap +msgid "" +" - History rewriting cannot be considered a security measure against the\n" +" unauthorized access to a secret as it doesn't automatically update " +"all\n" +" working copies of the repository.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:219 +#, no-wrap +msgid "" +" In the case that the secret is a passphrase, the recommended measure\n" +" against such attacks is to change the passphrase, making useless the\n" +" knowledge of the previous secret.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:222 +#, no-wrap +msgid "" +" Users wishing to edit their repository history should proceed " +"manually\n" +" using the *git* action.\n" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:224 +msgid "# SEE ALSO" +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:226 +msgid "The *README* file distributed with Keyringer contains full documentation." +msgstr "" + +#. type: Plain text +#: keyringer.1.mdwn:228 +msgid "" +"The Keyringer source code and all documentation may be downloaded from " +"." +msgstr "" -- cgit v1.2.3 From 4bf0e9291000e9dae057b887c00a4a167f17ffa4 Mon Sep 17 00:00:00 2001 From: Silvio Rhatto Date: Sun, 10 Nov 2013 23:34:43 -0200 Subject: Updating ChangeLog and .pot description --- ChangeLog | 2 ++ share/man/keyringer.pot | 19 +++++++++---------- 2 files changed, 11 insertions(+), 10 deletions(-) (limited to 'share/man') diff --git a/ChangeLog b/ChangeLog index bf7fdd6..37e520f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,7 @@ 2013-11-10 - Silvio Rhatto + Added keyringer.pot for easy manpage translation (closes #5). + Changed encrypt syntax Fix handing of file names with spaces (#20) diff --git a/share/man/keyringer.pot b/share/man/keyringer.pot index 4078028..2e32952 100644 --- a/share/man/keyringer.pot +++ b/share/man/keyringer.pot @@ -1,19 +1,18 @@ -# SOME DESCRIPTIVE TITLE -# Copyright (C) YEAR Free Software Foundation, Inc. -# This file is distributed under the same license as the PACKAGE package. -# FIRST AUTHOR , YEAR. +# Keyringer translation source +# Copyright (C) 2013 Keyringer Developers +# This file is distributed under the same license as the keyringer package. +# Silvio Rhatto , 2013. # -#, fuzzy msgid "" msgstr "" -"Project-Id-Version: PACKAGE VERSION\n" +"Project-Id-Version: Keyringer\n" "POT-Creation-Date: 2013-11-10 23:20-0100\n" -"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" -"Last-Translator: FULL NAME \n" -"Language-Team: LANGUAGE \n" +"PO-Revision-Date: 2013-11-10 23:20-0100\n" +"Last-Translator: Keyringer Developers \n" +"Language-Team: Keyringer Developers \n" "Language: \n" "MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=CHARSET\n" +"Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #. type: Plain text -- cgit v1.2.3