From 2a53ab094cdbda58869e32bd4f8abef004224f2d Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Thu, 20 Oct 2016 22:12:23 -0400 Subject: [PATCH] Add some docs about using gpg-agent with pwmd. --- doc/pwmd.html | 43 +++++++++++++++++++++++++++++++++++-------- doc/pwmd.texi | 43 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 70 insertions(+), 16 deletions(-) diff --git a/doc/pwmd.html b/doc/pwmd.html index 7bf83fa3..6a30ec43 100644 --- a/doc/pwmd.html +++ b/doc/pwmd.html @@ -203,16 +203,43 @@ Next: , Previ

pwmd uses GpgME for encryption, decryption and signing of the -OpenPGP data file. GpgME itself makes use of gpg for -these operations so some configuration of gpg may also be needed. +OpenPGP data file. GpgME itself makes use of gpg for these +operations so some configuration of gpg may be needed. Pwmd spawns +a separate gpg-agent process when gpg_homedir +(see Configuration) is not set to an instance of an already running +gpg-agent. Any gpg configuration options that you need set should be +put in ~/.pwmd/.gnupg/gpg.conf or the gpg.conf file located in +gpg_homedir. The same is true for the gpg-agent.conf file to set +any required gpg-agent options.

It is recommended to pass the --allow-preset-passphrase -command line option to gpg-agent. Doing so allows pwmd +option to gpg-agent. Doing so allows pwmd cache pushing on startup. It is also recommended to pass the ---allow-loopback-pinentry to gpg-agent. This option allows -a passphrase to be inquired from pwmd when a pinentry is -unavailable to the client (see TLS). See Configuration for details -about the gpg_homedir parameter. +--allow-loopback-pinentry to gpg-agent (this is the default +as of gnupg-2.1.15). This option allows a passphrase to be inquired from +pwmd when a pinentry is unavailable to the client +(see TLS). +

+

While pwmd has its own cache settings for an XML document, +gpg-agent has cache settings for the keys used for crypto operations +of a data file. Specifically the ignore-cache-for-signing, +default-cache-ttl and max-cache-ttl options. These gpg-agent +options may need to be adjusted depending on your usage needs. For example, +the OPEN command may not require a passphrase to open a data file do to +the gpg-agent having a cached key even though the ISCACHED command +returns an error indicating the data file is not cached; which usually means a +passphrase would be required. +

+

If you would like to use a keypair from your default gnupg keyring located in +~/.gnupg, but would still like to use a separate gpg-agent process (the +default), you would need to first export the public key from the default +keyring then import it into the keyring that pwmd uses. You can do this by +first exporting the public key, then use the --homedir ~/.pwmd/.gnupg +option of gpg to import it into the new keyring. For private keys, +you would need to copy the private key associated with the exported public key +to ~/.pwmd/.gnupg/private-keys-v1.d. If the private key is stored on +a smartcard you can also use the KEYINFO --learn command +(see KEYINFO).

pwmd is executed as follows: @@ -350,7 +377,7 @@ default options for new or unspecified file sections.

The configuration file can be reloaded by sending the SIGHUP signal to -a pwmd process. Some security sensitive settings may not be used +a pwmd process. Some security sensitive settings may not be changed until pwmd is restarted.

diff --git a/doc/pwmd.texi b/doc/pwmd.texi index 3356d97e..caa3e698 100644 --- a/doc/pwmd.texi +++ b/doc/pwmd.texi @@ -176,16 +176,43 @@ ACL. @mancont @mansect options @command{pwmd} uses GpgME for encryption, decryption and signing of the -OpenPGP data file. GpgME itself makes use of @command{gpg} for -these operations so some configuration of @command{gpg} may also be needed. +OpenPGP data file. GpgME itself makes use of @command{gpg} for these +operations so some configuration of @command{gpg} may be needed. Pwmd spawns +a separate @command{gpg-agent} process when @var{gpg_homedir} +(@pxref{Configuration}) is not set to an instance of an already running +gpg-agent. Any @command{gpg} configuration options that you need set should be +put in @var{~/.pwmd/.gnupg/gpg.conf} or the @var{gpg.conf} file located in +@var{gpg_homedir}. The same is true for the @var{gpg-agent.conf} file to set +any required @command{gpg-agent} options. It is recommended to pass the @option{--allow-preset-passphrase} -command line option to @command{gpg-agent}. Doing so allows @command{pwmd} +option to @command{gpg-agent}. Doing so allows @command{pwmd} cache pushing on startup. It is also recommended to pass the -@option{--allow-loopback-pinentry} to @command{gpg-agent}. This option allows -a passphrase to be inquired from @command{pwmd} when a @command{pinentry} is -unavailable to the client (@pxref{TLS}). @xref{Configuration} for details -about the @var{gpg_homedir} parameter. +@option{--allow-loopback-pinentry} to @command{gpg-agent} (this is the default +as of gnupg-2.1.15). This option allows a passphrase to be inquired from +@command{pwmd} when a @command{pinentry} is unavailable to the client +(@pxref{TLS}). + +While @command{pwmd} has its own cache settings for an XML document, +@command{gpg-agent} has cache settings for the keys used for crypto operations +of a data file. Specifically the @option{ignore-cache-for-signing}, +@option{default-cache-ttl} and @option{max-cache-ttl} options. These gpg-agent +options may need to be adjusted depending on your usage needs. For example, +the @code{OPEN} command may not require a passphrase to open a data file do to +the gpg-agent having a cached key even though the @code{ISCACHED} command +returns an error indicating the data file is not cached; which usually means a +passphrase would be required. + +If you would like to use a keypair from your default gnupg keyring located in +~/.gnupg, but would still like to use a separate gpg-agent process (the +default), you would need to first export the public key from the default +keyring then import it into the keyring that pwmd uses. You can do this by +first exporting the public key, then use the @option{--homedir ~/.pwmd/.gnupg} +option of @command{gpg} to import it into the new keyring. For private keys, +you would need to copy the private key associated with the exported public key +to @var{~/.pwmd/.gnupg/private-keys-v1.d}. If the private key is stored on +a smartcard you can also use the @code{KEYINFO --learn} command +(@pxref{KEYINFO}). @cindex Running @command{pwmd} @command{pwmd} is executed as follows: @@ -302,7 +329,7 @@ A tilde @code{~} will be expanded to the home directory of the user starting @cindex Reloading the configuration file The configuration file can be reloaded by sending the @emph{SIGHUP} signal to -a @command{pwmd} process. Some security sensitive settings may not be used +a @command{pwmd} process. Some security sensitive settings may not be changed until @command{pwmd} is restarted. @cindex Global configuration options -- 2.11.4.GIT