dirmngr: Make t-http.c work again with gnutls.
[gnupg.git] / doc / gpgsm.texi
index 9f16f82..b92eaea 100644 (file)
@@ -2,6 +2,8 @@
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
 @c This is part of the GnuPG manual.
 @c For copying conditions, see the file gnupg.texi.
 
+@include defs.inc
+
 @node Invoking GPGSM
 @chapter Invoking GPGSM
 @cindex GPGSM command options
 @node Invoking GPGSM
 @chapter Invoking GPGSM
 @cindex GPGSM command options
@@ -106,7 +108,7 @@ abbreviate this command.
 @table @gnupgtabopt
 @item --encrypt
 @opindex encrypt
 @table @gnupgtabopt
 @item --encrypt
 @opindex encrypt
-Perform an encryption.  The keys the data is encrypted too must be set
+Perform an encryption.  The keys the data is encrypted to must be set
 using the option @option{--recipient}.
 
 @item --decrypt
 using the option @option{--recipient}.
 
 @item --decrypt
@@ -134,7 +136,7 @@ Run in server mode and wait for commands on the @code{stdin}.
 Behave as a Dirmngr client issuing the request @var{command} with the
 optional list of @var{args}.  The output of the Dirmngr is printed
 stdout.  Please note that file names given as arguments should have an
 Behave as a Dirmngr client issuing the request @var{command} with the
 optional list of @var{args}.  The output of the Dirmngr is printed
 stdout.  Please note that file names given as arguments should have an
-absolute file name (i.e. commencing with @code{/} because they are
+absolute file name (i.e. commencing with @code{/}) because they are
 passed verbatim to the Dirmngr and the working directory of the
 Dirmngr might not be the same as the one of this client.  Currently it
 is not possible to pass data via stdin to the Dirmngr.  @var{command}
 passed verbatim to the Dirmngr and the working directory of the
 Dirmngr might not be the same as the one of this client.  Currently it
 is not possible to pass data via stdin to the Dirmngr.  @var{command}
@@ -163,22 +165,16 @@ use @samp{--help} to get a list of supported operations.
 @subsection How to manage the certificates and keys
 
 @table @gnupgtabopt
 @subsection How to manage the certificates and keys
 
 @table @gnupgtabopt
-@item --gen-key
+@item --generate-key
+@opindex generate-key
+@itemx --gen-key
 @opindex gen-key
 @opindex gen-key
-@ifclear gpgtwoone
--This command allows the creation of a certificate signing request.  It
--is commonly used along with the @option{--output} option to save the
--created CSR into a file.  If used with the @option{--batch} a parameter
--file is used to create the CSR.
-@end ifclear
-@ifset gpgtwoone
 This command allows the creation of a certificate signing request or a
 self-signed certificate.  It is commonly used along with the
 @option{--output} option to save the created CSR or certificate into a
 file.  If used with the @option{--batch} a parameter file is used to
 create the CSR or certificate and it is further possible to create
 non-self-signed certificates.
 This command allows the creation of a certificate signing request or a
 self-signed certificate.  It is commonly used along with the
 @option{--output} option to save the created CSR or certificate into a
 file.  If used with the @option{--batch} a parameter file is used to
 create the CSR or certificate and it is further possible to create
 non-self-signed certificates.
-@end ifset
 
 @item --list-keys
 @itemx -k
 
 @item --list-keys
 @itemx -k
@@ -264,9 +260,8 @@ Export the private key and the certificate identified by @var{key-id} in
 a PKCS#12 format. When used with the @code{--armor} option a few
 informational lines are prepended to the output.  Note, that the PKCS#12
 format is not very secure and this command is only provided if there is
 a PKCS#12 format. When used with the @code{--armor} option a few
 informational lines are prepended to the output.  Note, that the PKCS#12
 format is not very secure and this command is only provided if there is
-no other way to exchange the private key. (@pxref{option --p12-charset})
+no other way to exchange the private key. (@xref{option --p12-charset}.)
 
 
-@ifset gpgtwoone
 @item --export-secret-key-p8 @var{key-id}
 @itemx --export-secret-key-raw @var{key-id}
 @opindex export-secret-key-p8
 @item --export-secret-key-p8 @var{key-id}
 @itemx --export-secret-key-raw @var{key-id}
 @opindex export-secret-key-p8
@@ -277,7 +272,6 @@ PKCS#1 format; the @code{...-p8} command exports in PKCS#8 format.
 When used with the @code{--armor} option a few informational lines are
 prepended to the output.  These commands are useful to prepare a key
 for use on a TLS server.
 When used with the @code{--armor} option a few informational lines are
 prepended to the output.  These commands are useful to prepare a key
 for use on a TLS server.
-@end ifset
 
 @item --import [@var{files}]
 @opindex import
 
 @item --import [@var{files}]
 @opindex import
@@ -291,7 +285,9 @@ Read information about the private keys from the smartcard and import
 the certificates from there.  This command utilizes the @command{gpg-agent}
 and in turn the @command{scdaemon}.
 
 the certificates from there.  This command utilizes the @command{gpg-agent}
 and in turn the @command{scdaemon}.
 
-@item --passwd @var{user_id}
+@item --change-passphrase @var{user_id}
+@opindex change-passphrase
+@itemx --passwd @var{user_id}
 @opindex passwd
 Change the passphrase of the private key belonging to the certificate
 specified as @var{user_id}.  Note, that changing the passphrase/PIN of a
 @opindex passwd
 Change the passphrase of the private key belonging to the certificate
 specified as @var{user_id}.  Note, that changing the passphrase/PIN of a
@@ -361,18 +357,11 @@ Specify an agent program to be used for secret key operations.  The
 default value is determined by running the command @command{gpgconf}.
 Note that the pipe symbol (@code{|}) is used for a regression test
 suite hack and may thus not be used in the file name.
 default value is determined by running the command @command{gpgconf}.
 Note that the pipe symbol (@code{|}) is used for a regression test
 suite hack and may thus not be used in the file name.
-@ifclear gpgtwoone
-This is only used
-as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
-set or a running agent cannot be connected.
-@end ifclear
 
 @item --dirmngr-program @var{file}
 @opindex dirmngr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
 
 @item --dirmngr-program @var{file}
 @opindex dirmngr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
-default value is @file{/usr/sbin/dirmngr}.  This is only used as a
-fallback when the environment variable @code{DIRMNGR_INFO} is not set or
-a running dirmngr cannot be connected.
+default value is @file{@value{BINDIR}/dirmngr}.
 
 @item --prefer-system-dirmngr
 @opindex prefer-system-dirmngr
 
 @item --prefer-system-dirmngr
 @opindex prefer-system-dirmngr
@@ -399,6 +388,7 @@ Do not print a warning when the so called "secure memory" cannot be used.
 @item --log-file @var{file}
 @opindex log-file
 When running in server mode, append all logging output to @var{file}.
 @item --log-file @var{file}
 @opindex log-file
 When running in server mode, append all logging output to @var{file}.
+Use @file{socket://} to log to socket.
 
 @end table
 
 
 @end table
 
@@ -475,6 +465,7 @@ will not have on your local keybox), the operator can tell both your IP
 address and the time when you verified the signature.
 
 
 address and the time when you verified the signature.
 
 
+@anchor{gpgsm-option --validation-model}
 @item --validation-model @var{name}
 @opindex validation-model
 This option changes the default validation model.  The only possible
 @item --validation-model @var{name}
 @opindex validation-model
 This option changes the default validation model.  The only possible
@@ -567,6 +558,7 @@ may be given (@pxref{how-to-specify-a-user-id}).
 Write output to @var{file}.  The default is to write it to stdout.
 
 
 Write output to @var{file}.  The default is to write it to stdout.
 
 
+@anchor{gpgsm-option --with-key-data}
 @item --with-key-data
 @opindex with-key-data
 Displays extra information with the @code{--list-keys} commands.  Especially
 @item --with-key-data
 @opindex with-key-data
 Displays extra information with the @code{--list-keys} commands.  Especially
@@ -574,13 +566,14 @@ a line tagged @code{grp} is printed which tells you the keygrip of a
 key.  This string is for example used as the file name of the
 secret key.
 
 key.  This string is for example used as the file name of the
 secret key.
 
+@anchor{gpgsm-option --with-validation}
 @item --with-validation
 @opindex with-validation
 When doing a key listing, do a full validation check for each key and
 print the result.  This is usually a slow operation because it
 requires a CRL lookup and other operations.
 
 @item --with-validation
 @opindex with-validation
 When doing a key listing, do a full validation check for each key and
 print the result.  This is usually a slow operation because it
 requires a CRL lookup and other operations.
 
-When used along with --import, a validation of the certificate to
+When used along with @option{--import}, a validation of the certificate to
 import is done and only imported if it succeeds the test.  Note that
 this does not affect an already available certificate in the DB.
 This option is therefore useful to simply verify a certificate.
 import is done and only imported if it succeeds the test.  Note that
 this does not affect an already available certificate in the DB.
 This option is therefore useful to simply verify a certificate.
@@ -592,14 +585,12 @@ certificate.
 
 @item --with-keygrip
 Include the keygrip in standard key listings.  Note that the keygrip is
 
 @item --with-keygrip
 Include the keygrip in standard key listings.  Note that the keygrip is
-always listed in --with-colons mode.
+always listed in @option{--with-colons} mode.
 
 
-@ifset gpgtwoone
 @item --with-secret
 @opindex with-secret
 Include info about the presence of a secret key in public key listings
 done with @code{--with-colons}.
 @item --with-secret
 @opindex with-secret
 Include info about the presence of a secret key in public key listings
 done with @code{--with-colons}.
-@end ifset
 
 @end table
 
 
 @end table
 
@@ -607,7 +598,7 @@ done with @code{--with-colons}.
 @c *************  CMS OPTIONS  ***************
 @c *******************************************
 @node CMS Options
 @c *************  CMS OPTIONS  ***************
 @c *******************************************
 @node CMS Options
-@subsection How to change how the CMS is created.
+@subsection How to change how the CMS is created
 
 @table @gnupgtabopt
 @item --include-certs @var{n}
 
 @table @gnupgtabopt
 @item --include-certs @var{n}
@@ -638,7 +629,7 @@ interoperability problems.
 @c ********  ESOTERIC OPTIONS  ***************
 @c *******************************************
 @node Esoteric Options
 @c ********  ESOTERIC OPTIONS  ***************
 @c *******************************************
 @node Esoteric Options
-@subsection Doing things one usually do not want to do.
+@subsection Doing things one usually do not want to do
 
 
 @table @gnupgtabopt
 
 
 @table @gnupgtabopt
@@ -649,8 +640,8 @@ Sometimes signatures are broken in that they announce a different digest
 algorithm than actually used.  @command{gpgsm} uses a one-pass data
 processing model and thus needs to rely on the announced digest
 algorithms to properly hash the data.  As a workaround this option may
 algorithm than actually used.  @command{gpgsm} uses a one-pass data
 processing model and thus needs to rely on the announced digest
 algorithms to properly hash the data.  As a workaround this option may
-be used to tell gpg to also hash the data using the algorithm
-@var{name}; this slows processing down a little bit but allows to verify
+be used to tell @command{gpgsm} to also hash the data using the algorithm
+@var{name}; this slows processing down a little bit but allows verification of
 such broken signatures.  If @command{gpgsm} prints an error like
 ``digest algo 8 has not been enabled'' you may want to try this option,
 with @samp{SHA256} for @var{name}.
 such broken signatures.  If @command{gpgsm} prints an error like
 ``digest algo 8 has not been enabled'' you may want to try this option,
 with @samp{SHA256} for @var{name}.
@@ -716,7 +707,7 @@ memory allocation
 @item 6  (64)
 caching
 @item 7  (128)
 @item 6  (64)
 caching
 @item 7  (128)
-show memory statistics.
+show memory statistics
 @item 9  (512)
 write hashed data to files named @code{dbgmd-000*}
 @item 10 (1024)
 @item 9  (512)
 write hashed data to files named @code{dbgmd-000*}
 @item 10 (1024)
@@ -749,11 +740,33 @@ This is actually not a debugging option but only useful as such.  It
 lets @command{gpgsm} ignore all notAfter dates, this is used by the regression
 tests.
 
 lets @command{gpgsm} ignore all notAfter dates, this is used by the regression
 tests.
 
-@item --fixed-passphrase @var{string}
-@opindex fixed-passphrase
-Supply the passphrase @var{string} to the gpg-protect-tool.  This
-option is only useful for the regression tests included with this
-package and may be revised or removed at any time without notice.
+@item --passphrase-fd @code{n}
+@opindex passphrase-fd
+Read the passphrase from file descriptor @code{n}. Only the first line
+will be read from file descriptor @code{n}. If you use 0 for @code{n},
+the passphrase will be read from STDIN. This can only be used if only
+one passphrase is supplied.
+
+Note that this passphrase is only used if the option @option{--batch}
+has also been given.
+
+@item --pinentry-mode @code{mode}
+@opindex pinentry-mode
+Set the pinentry mode to @code{mode}.  Allowed values for @code{mode}
+are:
+@table @asis
+  @item default
+  Use the default of the agent, which is @code{ask}.
+  @item ask
+  Force the use of the Pinentry.
+  @item cancel
+  Emulate use of Pinentry's cancel button.
+  @item error
+  Return a Pinentry error (``No Pinentry'').
+  @item loopback
+  Redirect Pinentry queries to the caller.  Note that in contrast to
+  Pinentry the user is not prompted again if he enters a bad password.
+@end table
 
 @item --no-common-certs-import
 @opindex no-common-certs-import
 
 @item --no-common-certs-import
 @opindex no-common-certs-import
@@ -790,7 +803,7 @@ current home directory (@pxref{option --homedir}).
 @table @file
 
 @item gpgsm.conf
 @table @file
 
 @item gpgsm.conf
-@cindex gpgsm.conf
+@efindex gpgsm.conf
 This is the standard configuration file read by @command{gpgsm} on
 startup.  It may contain any valid long option; the leading two dashes
 may not be entered and the option may not be abbreviated.  This default
 This is the standard configuration file read by @command{gpgsm} on
 startup.  It may contain any valid long option; the leading two dashes
 may not be entered and the option may not be abbreviated.  This default
@@ -799,7 +812,7 @@ You should backup this file.
 
 
 @item policies.txt
 
 
 @item policies.txt
-@cindex policies.txt
+@efindex policies.txt
 This is a list of allowed CA policies.  This file should list the
 object identifiers of the policies line by line.  Empty lines and
 lines starting with a hash mark are ignored.  Policies missing in this
 This is a list of allowed CA policies.  This file should list the
 object identifiers of the policies line by line.  Empty lines and
 lines starting with a hash mark are ignored.  Policies missing in this
@@ -819,14 +832,14 @@ like this:
 @c man:.RE
 
 @item qualified.txt
 @c man:.RE
 
 @item qualified.txt
-@cindex qualified.txt
+@efindex qualified.txt
 This is the list of root certificates used for qualified certificates.
 They are defined as certificates capable of creating legally binding
 signatures in the same way as handwritten signatures are.  Comments
 start with a hash mark and empty lines are ignored.  Lines do have a
 length limit but this is not a serious limitation as the format of the
 This is the list of root certificates used for qualified certificates.
 They are defined as certificates capable of creating legally binding
 signatures in the same way as handwritten signatures are.  Comments
 start with a hash mark and empty lines are ignored.  Lines do have a
 length limit but this is not a serious limitation as the format of the
-entries is fixed and checked by gpgsm: A non-comment line starts with
-optional whitespace, followed by exactly 40 hex character, white space
+entries is fixed and checked by @command{gpgsm}: A non-comment line starts with
+optional whitespace, followed by exactly 40 hex characters, white space
 and a lowercased 2 letter country code.  Additional data delimited with
 by a white space is current ignored but might late be used for other
 purposes.
 and a lowercased 2 letter country code.  Additional data delimited with
 by a white space is current ignored but might late be used for other
 purposes.
@@ -836,14 +849,14 @@ mean that the certificate is trusted; in general the certificates listed
 in this file need to be listed also in @file{trustlist.txt}.
 
 This is a global file an installed in the data directory
 in this file need to be listed also in @file{trustlist.txt}.
 
 This is a global file an installed in the data directory
-(e.g. @file{/usr/share/gnupg/qualified.txt}).  GnuPG installs a suitable
+(e.g. @file{@value{DATADIR}/qualified.txt}).  GnuPG installs a suitable
 file with root certificates as used in Germany.  As new Root-CA
 certificates may be issued over time, these entries may need to be
 updated; new distributions of this software should come with an updated
 list but it is still the responsibility of the Administrator to check
 that this list is correct.
 
 file with root certificates as used in Germany.  As new Root-CA
 certificates may be issued over time, these entries may need to be
 updated; new distributions of this software should come with an updated
 list but it is still the responsibility of the Administrator to check
 that this list is correct.
 
-Everytime @command{gpgsm} uses a certificate for signing or verification
+Every time @command{gpgsm} uses a certificate for signing or verification
 this file will be consulted to check whether the certificate under
 question has ultimately been issued by one of these CAs.  If this is the
 case the user will be informed that the verified signature represents a
 this file will be consulted to check whether the certificate under
 question has ultimately been issued by one of these CAs.  If this is the
 case the user will be informed that the verified signature represents a
@@ -855,26 +868,26 @@ Because this software has not yet been approved for use with such
 certificates, appropriate notices will be shown to indicate this fact.
 
 @item help.txt
 certificates, appropriate notices will be shown to indicate this fact.
 
 @item help.txt
-@cindex help.txt
+@efindex help.txt
 This is plain text file with a few help entries used with
 @command{pinentry} as well as a large list of help items for
 @command{gpg} and @command{gpgsm}.  The standard file has English help
 texts; to install localized versions use filenames like @file{help.LL.txt}
 with LL denoting the locale.  GnuPG comes with a set of predefined help
 This is plain text file with a few help entries used with
 @command{pinentry} as well as a large list of help items for
 @command{gpg} and @command{gpgsm}.  The standard file has English help
 texts; to install localized versions use filenames like @file{help.LL.txt}
 with LL denoting the locale.  GnuPG comes with a set of predefined help
-files in the data directory (e.g. @file{/usr/share/gnupg/help.de.txt})
+files in the data directory (e.g. @file{@value{DATADIR}/gnupg/help.de.txt})
 and allows overriding of any help item by help files stored in the
 and allows overriding of any help item by help files stored in the
-system configuration directory (e.g. @file{/etc/gnupg/help.de.txt}).
+system configuration directory (e.g. @file{@value{SYSCONFDIR}/help.de.txt}).
 For a reference of the help file's syntax, please see the installed
 @file{help.txt} file.
 
 
 @item com-certs.pem
 For a reference of the help file's syntax, please see the installed
 @file{help.txt} file.
 
 
 @item com-certs.pem
-@cindex com-certs.pem
+@efindex com-certs.pem
 This file is a collection of common certificates used to populated a
 newly created @file{pubring.kbx}.  An administrator may replace this
 file with a custom one.  The format is a concatenation of PEM encoded
 X.509 certificates.  This global file is installed in the data directory
 This file is a collection of common certificates used to populated a
 newly created @file{pubring.kbx}.  An administrator may replace this
 file with a custom one.  The format is a concatenation of PEM encoded
 X.509 certificates.  This global file is installed in the data directory
-(e.g. @file{/usr/share/gnupg/com-certs.pem}).
+(e.g. @file{@value{DATADIR}/com-certs.pem}).
 
 @end table
 
 
 @end table
 
@@ -884,32 +897,28 @@ into the directory @file{/etc/skel/.gnupg/} so that newly created users
 start up with a working configuration.  For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
 start up with a working configuration.  For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
-For internal purposes gpgsm creates and maintains a few other files;
+For internal purposes @command{gpgsm} creates and maintains a few other files;
 they all live in in the current home directory (@pxref{option
 --homedir}).  Only @command{gpgsm} may modify these files.
 
 
 @table @file
 @item pubring.kbx
 they all live in in the current home directory (@pxref{option
 --homedir}).  Only @command{gpgsm} may modify these files.
 
 
 @table @file
 @item pubring.kbx
-@cindex pubring.kbx
+@efindex pubring.kbx
 This a database file storing the certificates as well as meta
 information.  For debugging purposes the tool @command{kbxutil} may be
 used to show the internal structure of this file.  You should backup
 this file.
 
 @item random_seed
 This a database file storing the certificates as well as meta
 information.  For debugging purposes the tool @command{kbxutil} may be
 used to show the internal structure of this file.  You should backup
 this file.
 
 @item random_seed
-@cindex random_seed
+@efindex random_seed
 This content of this file is used to maintain the internal state of the
 random number generator across invocations.  The same file is used by
 other programs of this software too.
 
 @item S.gpg-agent
 This content of this file is used to maintain the internal state of the
 random number generator across invocations.  The same file is used by
 other programs of this software too.
 
 @item S.gpg-agent
-@cindex S.gpg-agent
+@efindex S.gpg-agent
 If this file exists
 If this file exists
-@ifclear gpgtwoone
-and the environment variable @env{GPG_AGENT_INFO} is
-not set,
-@end ifclear
 @command{gpgsm} will first try to connect to this socket for
 accessing @command{gpg-agent} before starting a new @command{gpg-agent}
 instance.  Under Windows this socket (which in reality be a plain file
 @command{gpgsm} will first try to connect to this socket for
 accessing @command{gpg-agent} before starting a new @command{gpg-agent}
 instance.  Under Windows this socket (which in reality be a plain file
@@ -983,7 +992,7 @@ these status codes:
 
 @item The signature is invalid
 This means that the signature verification failed (this is an indication
 
 @item The signature is invalid
 This means that the signature verification failed (this is an indication
-of af a transfer error, a program error or tampering with the message).
+of a transfer error, a program error or tampering with the message).
 @command{gpgsm} issues one of these status codes sequences:
   @table @code
   @item  @code{BADSIG}
 @command{gpgsm} issues one of these status codes sequences:
   @table @code
   @item  @code{BADSIG}
@@ -1000,13 +1009,7 @@ this is a missing certificate.
 @node CSR and certificate creation
 @subsection CSR and certificate creation
 
 @node CSR and certificate creation
 @subsection CSR and certificate creation
 
-@ifclear gpgtwoone
-@strong{Please notice}: The immediate creation of certificates is only
-supported by GnuPG version 2.1 or later.  With a 2.0 version you may
-only create a CSR.
-@end ifclear
-
-The command @option{--gen-key} may be used along with the option
+The command @option{--generate-key} may be used along with the option
 @option{--batch} to either create a certificate signing request (CSR)
 or an X.509 certificate.  This is controlled by a parameter file; the
 format of this file is as follows:
 @option{--batch} to either create a certificate signing request (CSR)
 or an X.509 certificate.  This is controlled by a parameter file; the
 format of this file is as follows:
@@ -1076,7 +1079,7 @@ parameter.  The only supported value for @var{algo} is @samp{rsa}.
 The requested length of a generated key in bits.  Defaults to 2048.
 
 @item Key-Grip: @var{hexstring}
 The requested length of a generated key in bits.  Defaults to 2048.
 
 @item Key-Grip: @var{hexstring}
-This is optional and used to generate a CSR or certificatet for an
+This is optional and used to generate a CSR or certificate for an
 already existing key.  Key-Length will be ignored when given.
 
 @item Key-Usage: @var{usage-list}
 already existing key.  Key-Length will be ignored when given.
 
 @item Key-Usage: @var{usage-list}
@@ -1111,11 +1114,11 @@ certificate signing request):
 @item Serial: @var{sn}
 If this parameter is given an X.509 certificate will be generated.
 @var{sn} is expected to be a hex string representing an unsigned
 @item Serial: @var{sn}
 If this parameter is given an X.509 certificate will be generated.
 @var{sn} is expected to be a hex string representing an unsigned
-integer of arbitary length.  The special value @samp{random} can be
+integer of arbitrary length.  The special value @samp{random} can be
 used to create a 64 bit random serial number.
 
 @item Issuer-DN: @var{issuer-name}
 used to create a 64 bit random serial number.
 
 @item Issuer-DN: @var{issuer-name}
-This is the DN name of the issuer in rfc2253 format.  If it is not set
+This is the DN name of the issuer in RFC-2253 format.  If it is not set
 it will default to the subject DN and a special GnuPG extension will
 be included in the certificate to mark it as a standalone certificate.
 
 it will default to the subject DN and a special GnuPG extension will
 be included in the certificate to mark it as a standalone certificate.
 
@@ -1154,7 +1157,7 @@ default is @samp{sha256}.
 @c ***************           *****************
 @c *******************************************
 @node GPGSM Protocol
 @c ***************           *****************
 @c *******************************************
 @node GPGSM Protocol
-@section The Protocol the Server Mode Uses.
+@section The Protocol the Server Mode Uses
 
 Description of the protocol used to access @command{GPGSM}.
 @command{GPGSM} does implement the Assuan protocol and in addition
 
 Description of the protocol used to access @command{GPGSM}.
 @command{GPGSM} does implement the Assuan protocol and in addition
@@ -1177,7 +1180,9 @@ Assuan manual for details.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
+* GPGSM GETAUDITLOG::     Retrieve an audit log.
 * GPGSM GETINFO::         Information about the process
 * GPGSM GETINFO::         Information about the process
+* GPGSM OPTION::          Session options.
 @end menu
 
 
 @end menu
 
 
@@ -1226,11 +1231,11 @@ correct.
 
 Set the file descriptor to be used for the output (i.e. the encrypted
 message). Obviously the pipe must be open at that point, the server
 
 Set the file descriptor to be used for the output (i.e. the encrypted
 message). Obviously the pipe must be open at that point, the server
-establishes its own end.  If the server returns an error he client
+establishes its own end.  If the server returns an error the client
 should consider this session failed.
 
 should consider this session failed.
 
-The option armor encodes the output in @acronym{PEM} format, the
-@code{--base64} option applies just a base 64 encoding.  No option
+The option @option{--armor} encodes the output in @acronym{PEM} format, the
+@option{--base64} option applies just a base-64 encoding.  No option
 creates binary output (@acronym{BER}).
 
 The actual encryption is done using the command
 creates binary output (@acronym{BER}).
 
 The actual encryption is done using the command
@@ -1256,19 +1261,19 @@ closed.
 @subsection Decrypting a message
 
 Input and output FDs are set the same way as in encryption, but
 @subsection Decrypting a message
 
 Input and output FDs are set the same way as in encryption, but
-@code{INPUT} refers to the ciphertext and output to the plaintext. There
+@code{INPUT} refers to the ciphertext and @code{OUTPUT} to the plaintext. There
 is no need to set recipients.  @command{GPGSM} automatically strips any
 @acronym{S/MIME} headers from the input, so it is valid to pass an
 entire MIME part to the INPUT pipe.
 
 is no need to set recipients.  @command{GPGSM} automatically strips any
 @acronym{S/MIME} headers from the input, so it is valid to pass an
 entire MIME part to the INPUT pipe.
 
-The encryption is done by using the command
+The decryption is done by using the command
 
 @example
   DECRYPT
 @end example
 
 It performs the decrypt operation after doing some check on the internal
 
 @example
   DECRYPT
 @end example
 
 It performs the decrypt operation after doing some check on the internal
-state. (e.g. that all needed data has been set).  Because it utilizes
+state (e.g. that all needed data has been set).  Because it utilizes
 the GPG-Agent for the session key decryption, there is no need to ask
 the client for a protecting passphrase - GpgAgent takes care of this by
 requesting this from the user.
 the GPG-Agent for the session key decryption, there is no need to ask
 the client for a protecting passphrase - GpgAgent takes care of this by
 requesting this from the user.
@@ -1296,8 +1301,8 @@ requested, only the signature is written.
   SIGN [--detached]
 @end example
 
   SIGN [--detached]
 @end example
 
-Sign the data set with the INPUT command and write it to the sink set by
-OUTPUT.  With @code{--detached}, a detached signature is created
+Sign the data set with the @code{INPUT} command and write it to the sink set by
+@code{OUTPUT}.  With @code{--detached}, a detached signature is created
 (surprise).
 
 The key used for signing is the default one or the one specified in
 (surprise).
 
 The key used for signing is the default one or the one specified in
@@ -1308,7 +1313,7 @@ possible to use the command
   SIGNER @var{userID}
 @end example
 
   SIGNER @var{userID}
 @end example
 
-to the signer's key.  @var{userID} should be the
+to set the signer's key.  @var{userID} should be the
 internal representation of the key; the server may accept any other way
 of specification.  If this is a valid and trusted recipient the server
 does respond with OK, otherwise the return is an ERR with the reason why
 internal representation of the key; the server may accept any other way
 of specification.  If this is a valid and trusted recipient the server
 does respond with OK, otherwise the return is an ERR with the reason why
@@ -1317,13 +1322,13 @@ this key.  If the policy is not to sign at all if not all
 keys are valid, the client has to take care of this.  All
 @code{SIGNER} commands are cumulative until a @code{RESET} is done.
 Note that a @code{SIGN} does not reset this list of signers which is in
 keys are valid, the client has to take care of this.  All
 @code{SIGNER} commands are cumulative until a @code{RESET} is done.
 Note that a @code{SIGN} does not reset this list of signers which is in
-contrats to the @code{RECIPIENT} command.
+contrast to the @code{RECIPIENT} command.
 
 
 @node GPGSM VERIFY
 @subsection Verifying a Message
 
 
 
 @node GPGSM VERIFY
 @subsection Verifying a Message
 
-To verify a mesage the command:
+To verify a message the command:
 
 @example
   VERIFY
 
 @example
   VERIFY
@@ -1367,6 +1372,7 @@ may be issued as a progress indicator.
 
 @node GPGSM LISTKEYS
 @subsection List available keys
 
 @node GPGSM LISTKEYS
 @subsection List available keys
+@anchor{gpgsm-cmd listkeys}
 
 To list the keys in the internal database or using an external key
 provider, the command:
 
 To list the keys in the internal database or using an external key
 provider, the command:
@@ -1385,7 +1391,7 @@ in turn this requires that the usual escape quoting rules are done.
 
 Lists only the keys where a secret key is available.
 
 
 Lists only the keys where a secret key is available.
 
-The list commands  commands are affected by the option
+The list commands are affected by the option
 
 @example
   OPTION list-mode=@var{mode}
 
 @example
   OPTION list-mode=@var{mode}
@@ -1420,14 +1426,14 @@ required: Spaces are to be translated into "+" or into "%20"; in turn
 this requires that the usual escape quoting rules are done.
 
 If the @option{--data} option has not been given, the format of the
 this requires that the usual escape quoting rules are done.
 
 If the @option{--data} option has not been given, the format of the
-output depends on what was set with the OUTPUT command.  When using
+output depends on what was set with the @code{OUTPUT} command.  When using
 @acronym{PEM} encoding a few informational lines are prepended.
 
 @acronym{PEM} encoding a few informational lines are prepended.
 
-If the @option{--data} has been given, a target set via OUTPUT is
+If the @option{--data} has been given, a target set via @code{OUTPUT} is
 ignored and the data is returned inline using standard
 @code{D}-lines. This avoids the need for an extra file descriptor.  In
 this case the options @option{--armor} and @option{--base64} may be used
 ignored and the data is returned inline using standard
 @code{D}-lines. This avoids the need for an extra file descriptor.  In
 this case the options @option{--armor} and @option{--base64} may be used
-in the same way as with the OUTPUT command.
+in the same way as with the @code{OUTPUT} command.
 
 
 @node GPGSM IMPORT
 
 
 @node GPGSM IMPORT
@@ -1466,6 +1472,23 @@ this requires that the usual escape quoting rules are done.
 The certificates must be specified unambiguously otherwise an error is
 returned.
 
 The certificates must be specified unambiguously otherwise an error is
 returned.
 
+@node GPGSM GETAUDITLOG
+@subsection Retrieve an audit log
+@anchor{gpgsm-cmd getauditlog}
+
+This command is used to retrieve an audit log.
+
+@example
+GETAUDITLOG [--data] [--html]
+@end example
+
+If @option{--data} is used, the audit log is send using D-lines
+instead of being sent to the file descriptor given by an @code{OUTPUT}
+command.  If @option{--html} is used, the output is formatted as an
+XHTML block. This is designed to be incorporated into a HTML
+document.
+
+
 @node GPGSM GETINFO
 @subsection  Return information about the process
 
 @node GPGSM GETINFO
 @subsection  Return information about the process
 
@@ -1482,10 +1505,120 @@ Return the version of the program.
 @item pid
 Return the process id of the process.
 @item agent-check
 @item pid
 Return the process id of the process.
 @item agent-check
-Return success if the agent is running.
+Return OK if the agent is running.
 @item cmd_has_option @var{cmd} @var{opt}
 @item cmd_has_option @var{cmd} @var{opt}
-Return success if the command @var{cmd} implements the option @var{opt}.
+Return OK if the command @var{cmd} implements the option @var{opt}.
 The leading two dashes usually used with @var{opt} shall not be given.
 The leading two dashes usually used with @var{opt} shall not be given.
+@item offline
+Return OK if the connection is in offline mode.  This may be either
+due to a @code{OPTION offline=1} or due to @command{gpgsm} being
+started with option @option{--disable-dirmngr}.
+@end table
+
+@node GPGSM OPTION
+@subsection  Session options
+
+The standard Assuan option handler supports these options.
+
+@example
+OPTION @var{name}[=@var{value}]
+@end example
+
+These @var{name}s are recognized:
+
+@table @code
+
+@item putenv
+Change the session's environment to be passed via gpg-agent to
+Pinentry.  @var{value} is a string of the form
+@code{<KEY>[=[<STRING>]]}.  If only @code{<KEY>} is given the
+environment variable @code{<KEY>} is removed from the session
+environment, if @code{<KEY>=} is given that environment variable is
+set to the empty string, and if @code{<STRING>} is given it is set to
+that string.
+
+@item display
+@efindex DISPLAY
+Set the session environment variable @code{DISPLAY} is set to @var{value}.
+@item ttyname
+@efindex GPG_TTY
+Set the session environment variable @code{GPG_TTY} is set to @var{value}.
+@item ttytype
+@efindex TERM
+Set the session environment variable @code{TERM} is set to @var{value}.
+@item lc-ctype
+@efindex LC_CTYPE
+Set the session environment variable @code{LC_CTYPE} is set to @var{value}.
+@item lc-messages
+@efindex LC_MESSAGES
+Set the session environment variable @code{LC_MESSAGES} is set to @var{value}.
+@item xauthority
+@efindex XAUTHORITY
+Set the session environment variable @code{XAUTHORITY} is set to @var{value}.
+@item pinentry-user-data
+@efindex PINENTRY_USER_DATA
+Set the session environment variable @code{PINENTRY_USER_DATA} is set
+to @var{value}.
+
+@item include-certs
+This option overrides the command line option
+@option{--include-certs}.  A @var{value} of -2 includes all
+certificates except for the root certificate, -1 includes all
+certicates, 0 does not include any certicates, 1 includes only the
+signers certicate and all other positive values include up to
+@var{value} certificates starting with the signer cert.
+
+@item list-mode
+@xref{gpgsm-cmd listkeys}.
+
+@item list-to-output
+If @var{value} is true the output of the list commands
+(@pxref{gpgsm-cmd listkeys}) is written to the file descriptor set
+with the last @code{OUTPUT} command.  If @var{value} is false the output is
+written via data lines; this is the default.
+
+@item with-validation
+If @var{value} is true for each listed certificate the validation
+status is printed.  This may result in the download of a CRL or the
+user being asked about the trustworthiness of a root certificate.  The
+default is given by a command line option (@pxref{gpgsm-option
+--with-validation}).
+
+
+@item with-secret
+If @var{value} is true certificates with a corresponding private key
+are marked by the list commands.
+
+@item validation-model
+This option overrides the command line option
+@option{validation-model} for the session.
+(@xref{gpgsm-option --validation-model}.)
+
+@item with-key-data
+This option globally enables the command line option
+@option{--with-key-data}.  (@xref{gpgsm-option --with-key-data}.)
+
+@item enable-audit-log
+If @var{value} is true data to write an audit log is gathered.
+(@xref{gpgsm-cmd getauditlog}.)
+
+@item allow-pinentry-notify
+If this option is used notifications about the launch of a Pinentry
+are passed back to the client.
+
+@item with-ephemeral-keys
+If @var{value} is true ephemeral certificates are included in the
+output of the list commands.
+
+@item no-encrypt-to
+If this option is used all keys set by the command line option
+@option{--encrypt-to} are ignored.
+
+@item offline
+If @var{value} is true or @var{value} is not given all network access
+is disabled for this session.  This is the same as the command line
+option @option{--disable-dirmngr}.
+
 @end table
 
 @mansect see also
 @end table
 
 @mansect see also