Minor fixes.
[gnupg.git] / doc / gpgsm.texi
index 4d91bda..ab2aae8 100644 (file)
@@ -8,43 +8,70 @@
 @cindex command options
 @cindex options, GPGSM command
 
-@c man begin DESCRIPTION
-
-@sc{gpgsm} is a tool similar to @sc{gpg} to provide digital encryption
-and signing servicesd on X.509 certificates and the CMS protocoll.  It
-is mainly used as a backend for S/MIME mail processing.  @sc{gpgsm}
-includes a full features certificate management and complies with all
-rules defined for the German Sphinx project.
-
-@c man end
-
-@xref{Option Index}, for an index to GPGSM's commands and options.
+@manpage gpgsm.1
+@ifset manverb
+.B gpgsm
+\- CMS encryption and signing tool
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  gpgsm
+.RB [ \-\-homedir
+.IR dir ]
+.RB [ \-\-options
+.IR file ]
+.RI [ options ]  
+.I command
+.RI [ args ]
+@end ifset
+
+
+@mansect description
+@command{gpgsm} is a tool similar to @command{gpg} to provide digital
+encryption and signing servicesd on X.509 certificates and the CMS
+protocol.  It is mainly used as a backend for S/MIME mail processing.
+@command{gpgsm} includes a full features certificate management and
+complies with all rules defined for the German Sphinx project.
+
+@manpause
+@xref{Option Index}, for an index to @command{GPGSM}'s commands and options.
+@mancont
 
 @menu
 * GPGSM Commands::        List of all commands.
 * GPGSM Options::         List of all options.
+* GPGSM Configuration::   Configuration files.
 * GPGSM Examples::        Some usage examples.
 
 Developer information:
-* Unattended Usage::      Using @sc{gpgsm} from other programs.
+* Unattended Usage::      Using @command{gpgsm} from other programs.
 * GPGSM Protocol::        The protocol the server mode uses.
 @end menu
 
-@c man begin COMMANDS
-
+@c *******************************************
+@c ***************            ****************
+@c ***************  COMMANDS  ****************
+@c ***************            ****************
+@c *******************************************
+@mansect commands
 @node GPGSM Commands
 @section Commands
 
-Commands are not distinguished from options execpt for the fact that
-only one one command is allowed.
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
 
 @menu
-* General Commands::        Commands not specific to the functionality.
-* Operational Commands::    Commands to select the type of operation.
-* Certificate Management::  How to manage certificates.
+* General GPGSM Commands::        Commands not specific to the functionality.
+* Operational GPGSM Commands::    Commands to select the type of operation.
+* Certificate Management::        How to manage certificates.
 @end menu
 
-@node General Commands
+
+@c *******************************************
+@c **********  GENERAL COMMANDS  *************
+@c *******************************************
+@node General GPGSM Commands
 @subsection Commands not specific to the function
 
 @table @gnupgtabopt
@@ -58,6 +85,10 @@ abbreviate this command.
 Print a usage message summarizing the most usefule command-line options.
 Not that you can abbreviate this command.
 
+@item --warranty
+@opindex warranty
+Print warranty information.
+
 @item --dump-options
 @opindex dump-options
 Print a list of all available options and commands.  Not that you can
@@ -65,25 +96,28 @@ abbreviate this command.
 @end table
 
 
-
-@node Operational Commands
+@c *******************************************
+@c ********  OPERATIONAL COMMANDS  ***********
+@c *******************************************
+@node Operational GPGSM Commands
 @subsection Commands to select the type of operation
 
 @table @gnupgtabopt
 @item --encrypt
 @opindex encrypt
-Perform an encryption.
+Perform an encryption.  The keys the data is encrypted too must be set
+using the option @option{--recipient}.
 
 @item --decrypt
 @opindex decrypt
-Perform a decryption; the type of input is automatically detmerined.  It
+Perform a decryption; the type of input is automatically determined.  It
 may either be in binary form or PEM encoded; automatic determination of
 base-64 encoding is not done.
 
 @item --sign
 @opindex sign
 Create a digital signature.  The key used is either the fist one found
-in the keybox or thise set with the -u option
+in the keybox or those set with the @option{--local-user} option.
 
 @item --verify
 @opindex verify
@@ -98,14 +132,15 @@ Run in server mode and wait for commands on the @code{stdin}.
 @opindex call-dirmngr
 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 filenames given as arguments should have an
-absulte path 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} should not contain spaces.
+stdout.  Please note that file names given as arguments should have an
+absulte 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}
+should not contain spaces.
 
 This is command is required for certain maintaining tasks of the dirmngr
-where a dirmngr must be able to call back to gpgsm.  See the Dirmngr
+where a dirmngr must be able to call back to @command{gpgsm}.  See the Dirmngr
 manual for details.
 
 @item --call-protect-tool @var{arguments}
@@ -120,42 +155,114 @@ use @samp{--help} to get a list of supported operations.
 @end table
 
 
+@c *******************************************
+@c *******  CERTIFICATE MANAGEMENT  **********
+@c *******************************************
 @node Certificate Management
-@subsection How to manage the certificate and keys
+@subsection How to manage the certificates and keys
 
 @table @gnupgtabopt
 @item --gen-key
 @opindex gen-key
-Generate a new key and a certificate request.
+This command allows the interactive creation of a certifcate signing
+request.  It is commonly used along with the @option{--output} option to
+save the created CSR into a file.
 
 @item --list-keys
+@itemx -k 
 @opindex list-keys
 List all available certificates stored in the local key database.
+Note that the displayed data might be reformatted for better human
+readability and illegal characters are replaced by safe substitutes.
 
 @item --list-secret-keys
+@itemx -K
 @opindex list-secret-keys
-List all available keys whenre a secret key is available.
+List all available certificates for which a corresponding a secret key
+is available.
 
 @item --list-external-keys @var{pattern}
 @opindex list-keys
 List certificates matching @var{pattern} using an external server.  This
-utilies the @code{dirmngr} service.  
+utilizes the @code{dirmngr} service.  
+
+@item --list-chain
+@opindex list-chain
+Same as @option{--list-keys} but also prints all keys making up the chain.
+
+
+@item --dump-cert
+@itemx --dump-keys
+@opindex dump-cert
+@opindex dump-keys
+List all available certificates stored in the local key database using a
+format useful mainly for debugging.
+
+@item --dump-chain
+@opindex dump-chain
+Same as @option{--dump-keys} but also prints all keys making up the chain.
+
+@item --dump-secret-keys
+@opindex dump-secret-keys
+List all available certificates for which a corresponding a secret key
+is available using a format useful mainly for debugging.
+
+@item --dump-external-keys @var{pattern}
+@opindex dump-external-keys
+List certificates matching @var{pattern} using an external server.
+This utilizes the @code{dirmngr} service.  It uses a format useful
+mainly for debugging.
+
+@item --keydb-clear-some-cert-flags
+@opindex keydb-clear-some-cert-flags
+This is a debugging aid to reset certain flags in the key database
+which are used to cache certain certificate stati.  It is especially
+useful if a bad CRL or a weird running OCSP reponder did accidently
+revoke certificate.  There is no security issue with this command
+because @command{gpgsm} always make sure that the validity of a certificate is
+checked right before it is used.
 
 @item --delete-keys @var{pattern}
 @opindex delete-keys
-Delete the keys matching @var{pattern}.
+Delete the keys matching @var{pattern}.  Note that there is no command
+to delete the secret part of the key directly.  In case you need to do
+this, you should run the command @code{gpgsm --dump-secret-keys KEYID}
+before you delete the key, copy the string of hex-digits in the
+``keygrip'' line and delete the file consisting of these hex-digits
+and the suffix @code{.key} from the @file{private-keys-v1.d} directory
+below our GnuPG home directory (usually @file{~/.gnupg}).
 
 @item --export [@var{pattern}]
 @opindex export
 Export all certificates stored in the Keybox or those specified by the
-optional @var{pattern}.  When using along with the @code{--armor} option
-a few informational lines are prepended before each block.
+optional @var{pattern}. Those pattern consist of a list of user ids
+(@pxref{how-to-specify-a-user-id}).  When used along with the
+@option{--armor} option a few informational lines are prepended before
+each block.  There is one limitation: As there is no commonly agreed
+upon way to pack more than one certificate into an ASN.1 structure, the
+binary export (i.e. without using @option{armor}) works only for the
+export of one certificate.  Thus it is required to specify a
+@var{pattern} which yields exactly one certificate.
+
+@item --export-secret-key-p12 @var{key-id}
+@opindex export
+Export the private key and the certificate identified by @var{key-id} in
+a PKCS#12 format. When using along 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})
+
+@item --import [@var{files}]
+@opindex import
+Import the certificates from the PEM or binary encoded files as well as
+from signed-only messages.  This command may also be used to import a
+secret key from a PKCS#12 file.
 
 @item --learn-card
 @opindex learn-card
 Read information about the private keys from the smartcard and import
-the certificates from there.  This command utilizes the @sc{gpg-agent}
-and in turn the @sc{scdaemon}.
+the certificates from there.  This command utilizes the @command{gpg-agent}
+and in turn the @command{scdaemon}.
 
 @item --passwd @var{user_id}
 @opindex passwd
@@ -166,10 +273,16 @@ smartcard is not yet supported.
 @end table
 
 
+@c *******************************************
+@c ***************            ****************
+@c ***************  OPTIONS   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect options
 @node GPGSM Options
 @section Option Summary
 
-GPGSM comes features a bunch ofoptions to control the exact behaviour
+@command{GPGSM} comes features a bunch ofoptions to control the exact behaviour
 and to change the default configuration.
 
 @menu 
@@ -180,8 +293,10 @@ and to change the default configuration.
 * Esoteric Options::        Doing things one usually don't want to do.
 @end menu
 
-@c man begin OPTIONS
 
+@c *******************************************
+@c ********  CONFIGURATION OPTIONS  **********
+@c *******************************************
 @node Configuration Options
 @subsection How to change the configuration
 
@@ -193,7 +308,12 @@ in the option file.
 @item --options @var{file}
 @opindex options
 Reads configuration from @var{file} instead of from the default
-per-user configuration file.
+per-user configuration file.  The default configuration file is named
+@file{gpgsm.conf} and expected in the @file{.gnupg} directory directly
+below the home directory of the user.
+
+@include opt-homedir.texi
+
 
 @item -v
 @item --verbose
@@ -201,7 +321,7 @@ per-user configuration file.
 @opindex verbose
 Outputs additional information while running.
 You can increase the verbosity by giving several
-verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+verbose commands to @command{gpgsm}, such as @samp{-vv}.
 
 @item --policy-file @var{filename}
 @opindex policy-file
@@ -221,15 +341,30 @@ 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 can't be connected.
 
+@item --prefer-system-dirmngr
+@opindex prefer-system-dirmngr
+If a system wide @command{dirmngr} is running in daemon mode, first try
+to connect to this one.  Fallback to a pipe based server if this does
+not work.  Under Windows this option is ignored because the system dirmngr is
+always used.
+
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
 @item --no-secmem-warning
 @opindex no-secmem-warning
 Don't print a warning when the so called "secure memory" can't be used.
 
-
+@item --log-file @var{file}
+@opindex log-file
+When running in server mode, append all logging output to @var{file}.
 
 @end table
 
 
+@c *******************************************
+@c ********  CERTIFICATE OPTIONS  ************
+@c *******************************************
 @node Certificate Options
 @subsection Certificate related options
 
@@ -250,8 +385,70 @@ By default the @acronym{CRL} checks are enabled and the DirMngr is used
 to check for revoked certificates.  The disable option is most useful
 with an off-line network connection to suppress this check.
 
+@item  --enable-trusted-cert-crl-check
+@itemx --disable-trusted-cert-crl-check
+@opindex enable-trusted-cert-crl-check
+@opindex disable-trusted-cert-crl-check
+By default the @acronym{CRL} for trusted root certificates are checked
+like for any other certificates.  This allows a CA to revoke its own
+certificates voluntary without the need of putting all ever issued
+certificates into a CRL.  The disable option may be used to switch this
+extra check off.  Due to the caching done by the Dirmngr, there won't be
+any noticeable performance gain.  Note, that this also disables possible
+OCSP checks for trusted root certificates.  A more specific way of
+disabling this check is by adding the ``relax'' keyword to the root CA
+line of the @file{trustlist.txt}
+
+
+@item --force-crl-refresh
+@opindex force-crl-refresh
+Tell the dirmngr to reload the CRL for each request.  For better
+performance, the dirmngr will actually optimize this by suppressing
+the loading for short time intervalls (e.g. 30 minutes). This option
+is useful to make sure that a fresh CRL is available for certificates
+hold in the keybox.  The suggested way of doing this is by using it
+along with the option @option{--with-validation} for a key listing
+command.  This option should not be used in a configuration file. 
+
+@item  --enable-ocsp
+@itemx --disable-ocsp
+@opindex enable-ocsp
+@opindex disable-ocsp
+Be default @acronym{OCSP} checks are disabled.  The enable option may
+be used to enable OCSP checks via Dirmngr.  If @acronym{CRL} checks
+are also enabled, CRLs will be used as a fallback if for some reason an
+OCSP request won't succeed.  Note, that you have to allow OCSP
+requests in Dirmngr's configuration too (option 
+@option{--allow-ocsp} and configure dirmngr properly.  If you don't do
+so you will get the error code @samp{Not supported}.
+
+@item --auto-issuer-key-retrieve
+@opindex auto-issuer-key-retrieve
+If a required certificate is missing while validating the chain of
+certificates, try to load that certificate from an external location.
+This usually means that Dirmngr is employed t search for the
+certificate.  Note that this option makes a "web bug" like behavior
+possible.  LDAP server operators can see which keys you request, so by
+sending you a message signed by a brand new key (which you naturally
+will not have on your local keybox), the operator can tell both your IP
+address and the time when you verified the signature.
+
+
+@item --validation-model @var{name}
+@opindex validation-model
+This option changes the default validation model.  The only possible
+values are "shell" (which is the default) and "chain" which forces the
+use of the chain model.  The chain model is also used if an option in
+the @file{trustlist.txt} or an attribute of the certificate requests it.
+However the standard model (shell) is in that case always tried first.
+
+
+
 @end table
 
+@c *******************************************
+@c ***********  INPUT AND OUTPUT  ************
+@c *******************************************
 @node Input and Output
 @subsection Input and Output
 
@@ -279,6 +476,27 @@ Assume the input data is plain base-64 encoded.
 @opindex assume-binary
 Assume the input data is binary encoded.
 
+@anchor{option --p12-charset}
+@item --p12-charset @var{name}
+@opindex p12-charset
+@command{gpgsm} uses the UTF-8 encoding when encoding passphrases for
+PKCS#12 files.  This option may be used to force the passphrase to be
+encoded in the specified encoding @var{name}.  This is useful if the
+application used to import the key uses a different encoding and thus
+won't be able to import a file generated by @command{gpgsm}.  Commonly
+used values for @var{name} are @code{Latin1} and @code{CP850}.  Note
+that @command{gpgsm} itself automagically imports any file with a
+passphrase encoded to the most commonly used encodings.
+
+
+@item --default-key @var{user_id}
+@opindex default-key
+Use @var{user_id} as the standard key for signing.  This key is used if
+no other key has been defined as a signing key.  Note, that the first
+@option{--local-users} option also sets this key if it has not yet been
+set; however @option{--default-key} always overrides this.
+
+
 @item --local-user @var{user_id}
 @item -u @var{user_id}
 @opindex local-user
@@ -286,106 +504,367 @@ Assume the input data is binary encoded.
 Set the user(s) to be used for signing.  The default is the first
 secret key found in the database.
 
+
+@item --recipient @var{name}
+@itemx -r
+@opindex recipient
+Encrypt to the user id @var{name}.  There are several ways a user id
+may be given (@pxref{how-to-specify-a-user-id}).
+
+
+@item --output @var{file}
+@itemx -o @var{file}
+@opindex output
+Write output to @var{file}.  The default is to write it to stdout.
+
+
 @item --with-key-data
 @opindex with-key-data
 Displays extra information with the @code{--list-keys} commands.  Especially
 a line tagged @code{grp} is printed which tells you the keygrip of a
-key.  This string is for example used as the filename of the
+key.  This string is for example used as the file name of the
 secret key.
 
+@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
+import is done and only imported if it succeeds the test.  Note that
+this does not affect an already available cwertificate in the DB.
+This option is therefore useful to simply verify a certificate.
+
+
+@item --with-md5-fingerprint
+For standard key listings, also print the MD5 fingerprint of the
+certificate.
+
 @end table
 
+@c *******************************************
+@c *************  CMS OPTIONS  ***************
+@c *******************************************
 @node CMS Options
 @subsection How to change how the CMS is created.
 
 @table @gnupgtabopt
 @item --include-certs @var{n}
+@opindex include-certs
 Using @var{n} of -2 includes all certificate except for the root cert,
 -1 includes all certs, 0 does not include any certs, 1 includes only
 the signers cert (this is the default) and all other positive
 values include up to @var{n} certificates starting with the signer cert.
+
+
+@item --cipher-algo @var{oid}
+@opindex cipher-algo
+Use the cipher algorithm with the ASN.1 object identifier @var{oid} for
+encryption.  For convenience the strings @code{3DES}, @code{AES} and
+@code{AES256} may be used instead of their OIDs.  The default is
+@code{3DES} (1.2.840.113549.3.7).
   
 @end table
 
 
 
+@c *******************************************
+@c ********  ESOTERIC OPTIONS  ***************
+@c *******************************************
 @node Esoteric Options
-@subsection Doing things one usually don't want todo.
+@subsection Doing things one usually don't want to do.
 
 
 @table @gnupgtabopt
 
+@item --extra-digest-algo @var{name}
+@opindex extra-digest-algo
+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 announcde 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
+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}.
+
+
 @item --faked-system-time @var{epoch}
 @opindex faked-system-time
 This option is only useful for testing; it sets the system time back or
 forth to @var{epoch} which is the number of seconds elapsed since the year
-1970.
+1970.  Alternativly @var{epoch} may be given as a full ISO time string
+(e.g. "20070924T154812").
+
+@item --with-ephemeral-keys
+@opindex with-ephemeral-keys
+Include ephemeral flagged keys in the output of key listings.
+
+@item --debug-level @var{level}
+@opindex debug-level
+Select the debug level for investigating problems. @var{level} may be
+one of:
+
+@table @code
+@item none
+no debugging at all.
+@item basic  
+some basic debug messages
+@item advanced
+more verbose debug messages
+@item expert
+even more detailed messages
+@item guru
+all of the debug messages you can get
+@end table
+
+How these messages are mapped to the actual debugging flags is not
+specified and may change with newer releases of this program. They are
+however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
 @opindex debug
-This option is only useful for debugging and the behaviour may change at
-any time without notice.  FLAGS are bit encoded and may be given in
-usual C-Syntax. The currently defined bits are:
-   @table @code
-   @item 0  (1)
-   X.509 or OpenPGP protocol related data
-   @item 1  (2)  
-   values of big number integers 
-   @item 2  (4)
-   low level crypto operations
-   @item 5  (32)
-   memory allocation
-   @item 6  (64)
-   caching
-   @item 7  (128)
-   show memory statistics.
-   @item 9  (512)
-   write hashed data to files named @code{dbgmd-000*}
-   @item 10 (1024)
-   trace Assuan protocol
-   @item 12 (4096)
-   bypass all certificate validation
-   @end table
+This option is only useful for debugging and the behaviour may change
+at any time without notice; using @code{--debug-levels} is the
+preferred method to select the debug verbosity.  FLAGS are bit encoded
+and may be given in usual C-Syntax. The currently defined bits are:
+
+@table @code
+@item 0  (1)
+X.509 or OpenPGP protocol related data
+@item 1  (2)  
+values of big number integers 
+@item 2  (4)
+low level crypto operations
+@item 5  (32)
+memory allocation
+@item 6  (64)
+caching
+@item 7  (128)
+show memory statistics.
+@item 9  (512)
+write hashed data to files named @code{dbgmd-000*}
+@item 10 (1024)
+trace Assuan protocol
+@end table
+
+Note, that all flags set using this option may get overriden by
+@code{--debug-level}.
 
 @item --debug-all
 @opindex debug-all
 Same as @code{--debug=0xffffffff}
 
-@item --debug-no-path-validation
-@opindex debug-no-path-validation
+@item --debug-allow-core-dump
+@opindex debug-allow-core-dump
+Usually @command{gpgsm} tries to avoid dumping core by well written code and by
+disabling core dumps for security reasons.  However, bugs are pretty
+durable beasts and to squash them it is sometimes useful to have a core
+dump.  This option enables core dumps unless the Bad Thing happened
+before the option parsing.
+
+@item --debug-no-chain-validation
+@opindex debug-no-chain-validation
+This is actually not a debugging option but only useful as such.  It
+lets @command{gpgsm} bypass all certificate chain validation checks.
+
+@item --debug-ignore-expiration
+@opindex debug-ignore-expiration
 This is actually not a debugging option but only useful as such.  It
-lets gpgsm bypass all certificate path validation checks.
+lets @command{gpgsm} ignore all notAfter dates, this is used by the regresssion
+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 --no-common-certs-import
+@opindex no-common-certs-import
+Suppress the import of common certificates on keybox creation.
 
 @end table
 
 All the long options may also be given in the configuration file after
 stripping off the two leading dashes.
 
+@c *******************************************
+@c ***************            ****************
+@c ***************  USER ID   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect how to specify a user id
+@ifset isman
+@include specify-user-id.texi
+@end ifset
+
+@c *******************************************
+@c ***************            ****************
+@c ***************   FILES    ****************
+@c ***************            ****************
+@c *******************************************
+@mansect files
+@node GPGSM Configuration
+@section Configuration files
+
+There are a few configuration files to control certain aspects of
+@command{gpgsm}'s operation. Unless noted, they are expected in the
+current home directory (@pxref{option --homedir}).
+
+@table @file
+
+@item gpgsm.conf
+@cindex 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
+name may be changed on the command line (@pxref{option
+  --options}).
+
+@item policies.txt
+@cindex 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
+file and not marked as critical in the certificate will print only a
+warning; certificates with policies marked as critical and not listed
+in this file will fail the signature verification.
+
+For example, to allow only the policy 2.289.9.9, the file should look
+like this:
+
+@c man:.RS
+@example
+# Allowed policies
+2.289.9.9  
+@end example
+@c man:.RE
+
+@item qualified.txt
+@cindex 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
+entries is fixed and checked by gpgsm: A non-comment line starts with
+optional whitespace, followed by exactly 40 hex character, 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.
+
+Note that even if a certificate is listed in this file, this does not
+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
+(e.g. @file{/usr/share/gnupg/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.
+
+Everytime @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
+legally binding (``qualified'') signature.  When creating a signature
+using such a certificate an extra prompt will be issued to let the user
+confirm that such a legally binding signature shall really be created.
+
+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
+@cindex 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
+files in the data directory (e.g. @file{/usr/share/gnupg/help.de.txt})
+and allows overriding of any help item by help files stored in the
+system configuration directory (e.g. @file{/etc/gnupg/help.de.txt}).
+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
+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/qualified.txt}).
+
+@end table
+
+@c man:.RE
+Note that on larger installations, it is useful to put predefined files
+into the directory @file{/etc/skel/.gnupg/} so that newly created users
+start up with a working configuration.  For existing users the a small
+helper script is provided to create these files (@pxref{addgnupghome}).
+
+For internal purposes gpgsm creates and maintaines 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
+@cindex 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.
+
+@item random_seed
+@cindex random_seed
+This content of this file is used to maintain the internal state of the
+random number generator accross invocations.  The same file is used by
+other programs of this software too.
+
+@item S.gpg-agent
+@cindex S.gpg-agent
+If this file exists and the environment variable @env{GPG_AGENT_INFO} is
+not set, @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
+describing a regular TCP litening port) is the standard way of
+connecting the @command{gpg-agent}.
 
+@end table
 
-@c 
-@c  Examples
-@c
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  EXAMPLES  ****************
+@c ***************            ****************
+@c *******************************************
+@mansect examples
 @node GPGSM Examples
 @section Examples
 
-@c man begin EXAMPLES
-
 @example
 $ gpgsm -er goo@@bar.net <plaintext >ciphertext
 @end example
 
-@c man end
 
+@c man end
 
 
-@c ---------------------------------
-@c    The machine interface
-@c --------------------------------
+@c *******************************************
+@c ***************              **************
+@c ***************  UNATTENDED  **************
+@c ***************              **************
+@c *******************************************
 @node Unattended Usage
 @section Unattended Usage
 
-@sc{gpgsm} is often used as a backend engine by other software.  To help
+@command{gpgsm} is often used as a backend engine by other software.  To help
 with this a machine interface has been defined to have an unambiguous
 way to do this.  This is most likely used with the @code{--server} command
 but may also be used in the standard operation mode by using the
@@ -411,7 +890,7 @@ certificates are all sane.  However there are two subcases with
 important information:  One of the certificates may have expired or a
 signature of a message itself as expired.  It is a sound practise to
 consider such a signature still as valid but additional information
-should be displayed.  Depending on the subcase @sc{gpgsm} will issue
+should be displayed.  Depending on the subcase @command{gpgsm} will issue
 these status codes:
   @table @asis 
   @item signature valid and nothing did expire
@@ -426,7 +905,7 @@ these status codes:
 @item The signature is invalid
 This means that the signature verification failed (this is an indication
 of af a transfer error, a programm error or tampering with the message).
-@sc{gpgsm} issues one of these status codes sequences:
+@command{gpgsm} issues one of these status codes sequences:
   @table @code
   @item  @code{BADSIG}
   @item  @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER}
@@ -440,18 +919,22 @@ this is a missing certificate.
 @end table
 
 
-@c 
-@c  Assuan Protocol
-@c
+@c *******************************************
+@c ***************           *****************
+@c ***************  ASSSUAN  *****************
+@c ***************           *****************
+@c *******************************************
+@manpause
 @node GPGSM Protocol
 @section The Protocol the Server Mode Uses.
 
-Description of the protocol used to access GPGSM.  GPGSM does implement
-the Assuan protocol and in addition provides a regular command line
-interface which exhibits a full client to this protocol (but uses
-internal linking).  To start gpgsm as a server the commandline "gpgsm
---server" must be used.  Additional options are provided to select the
-communication method (i.e. the name of the socket).
+Description of the protocol used to access @command{GPGSM}.
+@command{GPGSM} does implement the Assuan protocol and in addition
+provides a regular command line interface which exhibits a full client
+to this protocol (but uses internal linking).  To start
+@command{gpgsm} as a server the command line the option
+@code{--server} must be used.  Additional options are provided to
+select the communication method (i.e. the name of the socket).
 
 We assume that the connection has already been established; see the
 Assuan manual for details.
@@ -466,6 +949,7 @@ Assuan manual for details.
 * GPGSM EXPORT::          Export certificates.
 * GPGSM IMPORT::          Import certificates.
 * GPGSM DELETE::          Delete certificates.
+* GPGSM GETINFO::         Information about the process
 @end menu
 
 
@@ -490,13 +974,16 @@ recipients are valid, the client has to take care of this.  All
 successful @code{ENCRYPT} command.
 
 @example
-  INPUT FD=@var{n} [--armor|--base64|--binary]
+  INPUT FD[=@var{n}] [--armor|--base64|--binary]
 @end example
 
 Set the file descriptor for the message to be encrypted to @var{n}.
 Obviously the pipe must be open at that point, the server establishes
 its own end.  If the server returns an error the client should consider
-this session failed.
+this session failed.  If @var{n} is not given, this commands uses the
+last file descriptor passed to the application.
+@xref{fun-assuan_sendfd, ,the assuan_sendfd function,assuan,the Libassuan
+manual}, on how to do descriptor passing.
 
 The @code{--armor} option may be used to advice the server that the
 input data is in @acronym{PEM} format, @code{--base64} advices that a
@@ -506,7 +993,7 @@ tries to figure out the used encoding, but this may not always be
 correct.
 
 @example
-  OUTPUT FD=@var{n} [--armor|--base64]
+  OUTPUT FD[=@var{n}] [--armor|--base64]
 @end example
 
 Set the file descriptor to be used for the output (i.e. the encrypted
@@ -528,7 +1015,7 @@ It takes the plaintext from the @code{INPUT} command, writes to the
 ciphertext to the file descriptor set with the @code{OUTPUT} command,
 take the recipients from all the recipients set so far.  If this command
 fails the clients should try to delete all output currently done or
-otherwise mark it as invalid.  GPGSM does ensure that there won't be any
+otherwise mark it as invalid.  @command{GPGSM} does ensure that there won't be any
 security problem with leftover data on the output in this case.
 
 This command should in general not fail, as all necessary checks have
@@ -541,7 +1028,7 @@ closed.
 
 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
-is no need to set recipients.  GPGSM automatically strips any
+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.
 
@@ -564,13 +1051,13 @@ requesting this from the user.
 Signing is usually done with these commands:
 
 @example
-  INPUT FD=@var{n} [--armor|--base64|--binary]
+  INPUT FD[=@var{n}] [--armor|--base64|--binary]
 @end example
 
-This tells GPGSM to read the data to sign from file descriptor @var{n}.
+This tells @command{GPGSM} to read the data to sign from file descriptor @var{n}.
 
 @example
-  OUTPUT FD=@var{m} [--armor|--base64]
+  OUTPUT FD[=@var{m}] [--armor|--base64]
 @end example
 
 Write the output to file descriptor @var{m}.  If a detached signature is
@@ -625,14 +1112,14 @@ client must provide it.
 This is used to generate a new keypair, store the secret part in the
 @acronym{PSE} and the public key in the key database.  We will probably
 add optional commands to allow the client to select whether a hardware
-token is used to store the key.  Configuration options to GPGSM can be
-used to restrict the use of this command.
+token is used to store the key.  Configuration options to
+@command{GPGSM} can be used to restrict the use of this command.
 
 @example
   GENKEY 
 @end example
 
-GPGSM checks whether this command is allowed and then does an
+@command{GPGSM} checks whether this command is allowed and then does an
 INQUIRY to get the key parameters, the client should then send the
 key parameters in the native format:
 
@@ -696,16 +1183,22 @@ Note that options are valid for the entire session.
 To export certificate from the internal key database the command:
 
 @example
-  EXPORT @var{pattern}
+  EXPORT [--data [--armor] [--base64]] [--] @var{pattern}
 @end example
 
 is used.  To allow multiple patterns (which are ORed) quoting is
 required: Spaces are to be translated into "+" or into "%20"; in turn
 this requires that the usual escape quoting rules are done.
 
-The format of the output depends on what was set with the OUTPUT
-command.  When using @acronym{PEM} encoding a few informational lines
-are prepended.
+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
+@acronym{PEM} encoding a few informational lines are prepended.
+
+If the @option{--data} has been given, a target set via 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
+in the same way as with the OUTPUT command.
 
 
 @node GPGSM IMPORT
@@ -718,12 +1211,15 @@ To import certificates into the internal key database, the command
 @end example
 
 is used.  The data is expected on the file descriptor set with the
-@code{INPUT} command.  Certain checks are performend on the certificate.
+@code{INPUT} command.  Certain checks are performend on the
+certificate.  Note that the code will also handle PKCS\#12 files and
+import private keys; a helper program is used for that.
+
 
 @node GPGSM DELETE
 @subsection Delete certificates
 
-To delete certificate the command
+To delete certificate the command
 
 @example
   DELKEYS @var{pattern}
@@ -736,3 +1232,26 @@ this requires that the usual escape quoting rules are done.
 The certificates must be specified unambiguously otherwise an error is
 returned.
 
+@node GPGSM GETINFO
+@subsection  Return information about the process
+
+This is a multipurpose function to return a variety of information.
+
+@example
+GETINFO @var{what}
+@end example
+
+The value of @var{what} specifies the kind of information returned:
+@table @code
+@item version
+Return the version of the program.
+@item pid
+Return the process id of the process.
+@end table
+
+@mansect see also
+@ifset isman
+@command{gpg2}(1), 
+@command{gpg-agent}(1)
+@end ifset
+@include see-also-note.texi