Adding upstream version 2.2.40.upstream/2.2.40

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1696 insertions, 0 deletions

diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi
new file mode 100644
index 0000000..ba91aed
--- /dev/null
+++ b/doc/gpgsm.texi
@@ -0,0 +1,1696 @@
+@c Copyright (C) 2002 Free Software Foundation, Inc.
+@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
+@cindex command options
+@cindex options, GPGSM command
+
+@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 services 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 featured 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 @command{gpgsm} from other programs.
+* GPGSM Protocol::        The protocol the server mode uses.
+@end menu
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  COMMANDS  ****************
+@c ***************            ****************
+@c *******************************************
+@mansect commands
+@node GPGSM Commands
+@section Commands
+
+Commands are not distinguished from options except for the fact that
+only one command is allowed.
+
+@menu
+* 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
+
+
+@c *******************************************
+@c **********  GENERAL COMMANDS  *************
+@c *******************************************
+@node General GPGSM Commands
+@subsection Commands not specific to the function
+
+@table @gnupgtabopt
+@item --version
+@opindex version
+Print the program version and licensing information.  Note that you
+cannot abbreviate this command.
+
+@item --help, -h
+@opindex help
+Print a usage message summarizing the most useful command-line options.
+Note that you cannot abbreviate this command.
+
+@item --warranty
+@opindex warranty
+Print warranty information.  Note that you cannot abbreviate this
+command.
+
+@item --dump-options
+@opindex dump-options
+Print a list of all available options and commands.  Note that you cannot
+abbreviate this command.
+@end table
+
+
+@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.  The keys the data is encrypted to must be set
+using the option @option{--recipient}.
+
+@item --decrypt
+@opindex decrypt
+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 those set with the @option{--local-user} option.
+
+@item --verify
+@opindex verify
+Check a signature file for validity.  Depending on the arguments a
+detached signature may also be checked.
+
+@item --server
+@opindex server
+Run in server mode and wait for commands on the @code{stdin}.
+
+@item --call-dirmngr @var{command} [@var{args}]
+@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 file names given as arguments should have an
+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}
+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 @command{gpgsm}.  See the Dirmngr
+manual for details.
+
+@item --call-protect-tool @var{arguments}
+@opindex call-protect-tool
+Certain maintenance operations are done by an external program call
+@command{gpg-protect-tool}; this is usually not installed in a directory
+listed in the PATH variable.  This command provides a simple wrapper to
+access this tool.  @var{arguments} are passed verbatim to this command;
+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 certificates and keys
+
+@table @gnupgtabopt
+@item --generate-key
+@opindex generate-key
+@itemx --gen-key
+@opindex gen-key
+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.
+
+@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 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
+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 responder did accidentally
+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}.  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}. 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.  Ephemeral
+certificate are only exported if all @var{pattern} are given as
+fingerprints or keygrips.
+
+@item --export-secret-key-p12 @var{key-id}
+@opindex export-secret-key-p12
+Export the private key and the certificate identified by @var{key-id}
+using the 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 proper transport security should be used
+to convey the exported key.  (@xref{option --p12-charset}.)
+
+@item --export-secret-key-p8 @var{key-id}
+@itemx --export-secret-key-raw @var{key-id}
+@opindex export-secret-key-p8
+@opindex export-secret-key-raw
+Export the private key of the certificate identified by @var{key-id}
+with any encryption stripped.  The @code{...-raw} command exports in
+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.
+
+@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 @command{gpg-agent}
+and in turn the @command{scdaemon}.
+
+@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
+smartcard is not yet supported.
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  OPTIONS   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect options
+@node GPGSM Options
+@section Option Summary
+
+@command{GPGSM} features a bunch of options to control the exact behaviour
+and to change the default configuration.
+
+@menu
+* Configuration Options::   How to change the configuration.
+* Certificate Options::     Certificate related options.
+* Input and Output::        Input and Output.
+* CMS Options::             How to change how the CMS is created.
+* Esoteric Options::        Doing things one usually do not want to do.
+@end menu
+
+
+@c *******************************************
+@c ********  CONFIGURATION OPTIONS  **********
+@c *******************************************
+@node Configuration Options
+@subsection How to change the configuration
+
+These options are used to change the configuration and are usually found
+in the option file.
+
+@table @gnupgtabopt
+
+@anchor{gpgsm-option --options}
+@item --options @var{file}
+@opindex options
+Reads configuration from @var{file} instead of from the default
+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
+@opindex v
+@opindex verbose
+Outputs additional information while running.
+You can increase the verbosity by giving several
+verbose commands to @command{gpgsm}, such as @samp{-vv}.
+
+@item --keyserver @var{string}
+@opindex keyserver
+This is a deprecated option.  It was used to add an LDAP server to use
+for X.509 certificate and CRL lookup.  The alias @option{--ldapserver}
+existed from version 2.2.28 to 2.2.33 but is now entirely ignored.
+
+LDAP servers must be given in the configuration for @command{dirmngr}.
+
+
+@item --policy-file @var{filename}
+@opindex policy-file
+Change the default name of the policy file to @var{filename}.
+
+@item --agent-program @var{file}
+@opindex agent-program
+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.
+
+@item --dirmngr-program @var{file}
+@opindex dirmngr-program
+Specify a dirmngr program to be used for @acronym{CRL} checks.  The
+default value is @file{@value{BINDIR}/dirmngr}.
+
+@item --prefer-system-dirmngr
+@opindex prefer-system-dirmngr
+This option is obsolete and ignored.
+
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
+@item --no-autostart
+@opindex no-autostart
+Do not start the gpg-agent or the dirmngr if it has not yet been
+started and its service is required.  This option is mostly useful on
+machines where the connection to gpg-agent has been redirected to
+another machines.  If dirmngr is required on the remote machine, it
+may be started manually using @command{gpgconf --launch dirmngr}.
+
+@item --no-secmem-warning
+@opindex no-secmem-warning
+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}.
+Use @file{socket://} to log to socket.
+
+@end table
+
+
+@c *******************************************
+@c ********  CERTIFICATE OPTIONS  ************
+@c *******************************************
+@node Certificate Options
+@subsection Certificate related options
+
+@table @gnupgtabopt
+
+@item  --enable-policy-checks
+@itemx --disable-policy-checks
+@opindex enable-policy-checks
+@opindex disable-policy-checks
+By default policy checks are enabled.  These options may be used to
+change it.
+
+@item  --enable-crl-checks
+@itemx --disable-crl-checks
+@opindex enable-crl-checks
+@opindex disable-crl-checks
+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 and
+also to avoid that new certificates introduce a web bug by including a
+certificate specific CRL DP.  The disable option also disables an
+issuer certificate lookup via the authorityInfoAccess property of the
+certificate; the @option{--enable-issuer-key-retrieve} can be used
+to make use of that property anyway.
+
+@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 will not 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 intervals (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-issuer-based-crl-check
+@opindex enable-issuer-based-crl-check
+Run a CRL check even for certificates which do not have any CRL
+distribution point.  This requires that a suitable LDAP server has
+been configured in Dirmngr and that the CRL can be found using the
+issuer.  This option reverts to what GnuPG did up to version 2.2.20.
+This option is in general not useful.
+
+@item  --enable-ocsp
+@itemx --disable-ocsp
+@opindex enable-ocsp
+@opindex disable-ocsp
+By 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 will not succeed.  Note, that you have to allow OCSP
+requests in Dirmngr's configuration too (option
+@option{--allow-ocsp}) and configure Dirmngr properly.  If you do not 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 to 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.
+
+
+@anchor{gpgsm-option --validation-model}
+@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), "chain" which forces the
+use of the chain model and "steed" for a new simplified 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.
+
+@item --ignore-cert-extension @var{oid}
+@opindex ignore-cert-extension
+Add @var{oid} to the list of ignored certificate extensions.  The
+@var{oid} is expected to be in dotted decimal form, like
+@code{2.5.29.3}.  This option may be used more than once.  Critical
+flagged certificate extensions matching one of the OIDs in the list
+are treated as if they are actually handled and thus the certificate
+will not be rejected due to an unknown critical extension.  Use this
+option with care because extensions are usually flagged as critical
+for a reason.
+
+@end table
+
+@c *******************************************
+@c ***********  INPUT AND OUTPUT  ************
+@c *******************************************
+@node Input and Output
+@subsection Input and Output
+
+@table @gnupgtabopt
+@item --armor
+@itemx -a
+@opindex armor
+Create PEM encoded output.  Default is binary output.
+
+@item --base64
+@opindex base64
+Create Base-64 encoded output; i.e. PEM without the header lines.
+
+@item --assume-armor
+@opindex assume-armor
+Assume the input data is PEM encoded.  Default is to autodetect the
+encoding but this is may fail.
+
+@item --assume-base64
+@opindex assume-base64
+Assume the input data is plain base-64 encoded.
+
+@item --assume-binary
+@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
+will not 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
+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.
+
+
+@anchor{gpgsm-option --with-key-data}
+@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 file name of the
+secret key.  Implies @code{--with-colons}.
+
+@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.
+
+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.
+
+
+@item --with-md5-fingerprint
+For standard key listings, also print the MD5 fingerprint of the
+certificate.
+
+@item --with-keygrip
+Include the keygrip in standard key listings.  Note that the keygrip is
+always listed in @option{--with-colons} mode.
+
+@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 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 and all other positive values include up to @var{n}
+certificates starting with the signer cert.  The default is -2.
+
+@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{AES} (2.16.840.1.101.3.4.1.2).
+
+@item --digest-algo @code{name}
+Use @code{name} as the message digest algorithm.  Usually this
+algorithm is deduced from the respective signing certificate.  This
+option forces the use of the given algorithm and may lead to severe
+interoperability problems.
+
+@end table
+
+
+
+@c *******************************************
+@c ********  ESOTERIC OPTIONS  ***************
+@c *******************************************
+@node Esoteric Options
+@subsection Doing things one usually do not 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 announced digest
+algorithms to properly hash the data.  As a workaround this option may
+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}.
+
+@item --compliance @var{string}
+@opindex compliance
+Set the compliance mode.  Valid values are shown when using "help" for
+@var{string}.
+
+@item --min-rsa-length @var{n}
+@opindex min-rsa-length
+This option adjusts the compliance mode "de-vs" for stricter key size
+requirements.  For example, a value of 3000 turns rsa2048 and dsa2048
+keys into non-VS-NfD compliant keys.
+
+@item --require-compliance
+@opindex require-compliance
+To check that data has been encrypted according to the rules of the
+current compliance mode, a gpgsm user needs to evaluate the status
+lines.  This is allows frontends to handle compliance check in a more
+flexible way.  However, for scripted use the required evaluation of
+the status-line requires quite some effort; this option can be used
+instead to make sure that the gpgsm process exits with a failure if
+the compliance rules are not fulfilled.  Note that this option has
+currently an effect only in "de-vs" mode.
+
+@item --ignore-cert-with-oid @var{oid}
+@opindex ignore-cert-with-oid
+Add @var{oid} to the list of OIDs to be checked while reading
+certificates from smartcards. The @var{oid} is expected to be in
+dotted decimal form, like @code{2.5.29.3}.  This option may be used
+more than once.  As of now certificates with an extended key usage
+matching one of those OIDs are ignored during a @option{--learn-card}
+operation and not imported.  This option can help to keep the local
+key database clear of unneeded certificates stored on smartcards.
+
+@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.  Alternatively @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.  Note
+that they are included anyway if the key specification for a listing
+is given as fingerprint or keygrip.
+
+@item --compatibility-flags @var{flags}
+@opindex compatibility-flags
+Set compatibility flags to work around problems due to non-compliant
+certificates or data.  The @var{flags} are given as a comma separated
+list of flag names and are OR-ed together.  The special flag "none"
+clears the list and allows to start over with an empty list.  To get a
+list of available flags the sole word "help" can be used.
+
+@item --debug-level @var{level}
+@opindex debug-level
+Select the debug level for investigating problems. @var{level} may be
+a numeric value or by a keyword:
+
+@table @code
+@item none
+No debugging at all.  A value of less than 1 may be used instead of
+the keyword.
+@item basic
+Some basic debug messages.  A value between 1 and 2 may be used
+instead of the keyword.
+@item advanced
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
+@item expert
+Even more detailed messages.  A value between 6 and 8 may be used
+instead of the keyword.
+@item guru
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword.  The creation of hash tracing files is
+only enabled if the keyword is used.
+@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; 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 overridden by
+@code{--debug-level}.
+
+@item --debug-all
+@opindex debug-all
+Same as @code{--debug=0xffffffff}
+
+@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 @command{gpgsm} ignore all notAfter dates, this is used by the regression
+tests.
+
+@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 --request-origin @var{origin}
+@opindex request-origin
+Tell gpgsm to assume that the operation ultimately originated at
+@var{origin}.  Depending on the origin certain restrictions are applied
+and the Pinentry may include an extra note on the origin.  Supported
+values for @var{origin} are: @code{local} which is the default,
+@code{remote} to indicate a remote origin or @code{browser} for an
+operation requested by a web browser.
+
+@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
+@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
+name may be changed on the command line (@pxref{gpgsm-option --options}).
+You should backup this file.
+
+
+@item 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
+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.  You should backup
+this file.
+
+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
+@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
+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.
+
+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{@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.
+
+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
+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
+@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
+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
+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
+@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
+(e.g. @file{@value{DATADIR}/com-certs.pem}).
+
+@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 a small
+helper script is provided to create these files (@pxref{addgnupghome}).
+
+For internal purposes @command{gpgsm} creates and maintains a few other files;
+they all live in the current home directory (@pxref{option
+--homedir}).  Only @command{gpgsm} may modify these files.
+
+
+@table @file
+@item 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
+@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
+@efindex S.gpg-agent
+If this file exists
+@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 listening port) is the standard way of
+connecting the @command{gpg-agent}.
+
+@end table
+
+
+@c *******************************************
+@c ***************            ****************
+@c ***************  EXAMPLES  ****************
+@c ***************            ****************
+@c *******************************************
+@mansect examples
+@node GPGSM Examples
+@section Examples
+
+@example
+$ gpgsm -er goo@@bar.net <plaintext >ciphertext
+@end example
+
+
+@c *******************************************
+@c ***************              **************
+@c ***************  UNATTENDED  **************
+@c ***************              **************
+@c *******************************************
+@manpause
+@node Unattended Usage
+@section Unattended Usage
+
+@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
+@code{--status-fd} option.
+
+@menu
+* Automated signature checking::  Automated signature checking.
+* CSR and certificate creation::  CSR and certificate creation.
+@end menu
+
+@node Automated signature checking
+@subsection Automated signature checking
+
+It is very important to understand the semantics used with signature
+verification.  Checking a signature is not as simple as it may sound and
+so the operation is a bit complicated.  In most cases it is required
+to look at several status lines.  Here is a table of all cases a signed
+message may have:
+
+@table @asis
+@item The signature is valid
+This does mean that the signature has been successfully verified, the
+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 @command{gpgsm} will issue
+these status codes:
+  @table @asis
+  @item signature valid and nothing did expire
+  @code{GOODSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
+  @item signature valid but at least one certificate has expired
+  @code{EXPKEYSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
+  @item signature valid but expired
+  @code{EXPSIG}, @code{VALIDSIG}, @code{TRUST_FULLY}
+  Note, that this case is currently not implemented.
+  @end table
+
+@item The signature is invalid
+This means that the signature verification failed (this is an indication
+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}
+  @item  @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER}
+  @end table
+
+@item Error verifying a signature
+For some reason the signature could not be verified, i.e. it cannot be
+decided whether the signature is valid or invalid.  A common reason for
+this is a missing certificate.
+
+@end table
+
+@node CSR and certificate creation
+@subsection CSR and certificate creation
+
+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:
+
+@itemize @bullet
+@item Text only, line length is limited to about 1000 characters.
+@item UTF-8 encoding must be used to specify non-ASCII characters.
+@item Empty lines are ignored.
+@item Leading and trailing while space is ignored.
+@item A hash sign as the first non white space character indicates
+a comment line.
+@item Control statements are indicated by a leading percent sign, the
+arguments are separated by white space from the keyword.
+@item Parameters are specified by a keyword, followed by a colon.  Arguments
+are separated by white space.
+@item The first parameter must be @samp{Key-Type}, control statements
+may be placed anywhere.
+@item
+The order of the parameters does not matter except for @samp{Key-Type}
+which must be the first parameter.  The parameters are only used for
+the generated CSR/certificate; parameters from previous sets are not
+used.  Some syntactically checks may be performed.
+@item
+Key generation takes place when either the end of the parameter file
+is reached, the next @samp{Key-Type} parameter is encountered or at the
+control statement @samp{%commit} is encountered.
+@end itemize
+
+@noindent
+Control statements:
+
+@table @asis
+
+@item %echo @var{text}
+Print @var{text} as diagnostic.
+
+@item %dry-run
+Suppress actual key generation (useful for syntax checking).
+
+@item %commit
+Perform the key generation.  Note that an implicit commit is done at
+the next @asis{Key-Type} parameter.
+
+@c  %certfile <filename>
+@c      [Not yet implemented!]
+@c	Do not write the certificate to the keyDB but to <filename>.
+@c      This must be given before the first
+@c	commit to take place, duplicate specification of the same filename
+@c	is ignored, the last filename before a commit is used.
+@c	The filename is used until a new filename is used (at commit points)
+@c	and all keys are written to that file.	If a new filename is given,
+@c	this file is created (and overwrites an existing one).
+@c	Both control statements must be given.
+@end table
+
+@noindent
+General Parameters:
+
+@table @asis
+
+@item Key-Type: @var{algo}
+Starts a new parameter block by giving the type of the primary
+key. The algorithm must be capable of signing.  This is a required
+parameter.  The only supported value for @var{algo} is @samp{rsa}.
+
+@item Key-Length: @var{nbits}
+The requested length of a generated key in bits.  Defaults to 3072.
+
+@item Key-Grip: @var{hexstring}
+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}
+Space or comma delimited list of key usage, allowed values are
+@samp{encrypt}, @samp{sign} and @samp{cert}.  This is used to generate
+the keyUsage extension.  Please make sure that the algorithm is
+capable of this usage.  Default is to allow encrypt and sign.
+
+@item Name-DN: @var{subject-name}
+This is the Distinguished Name (DN) of the subject in RFC-2253 format.
+
+@item Name-Email: @var{string}
+This is an email address for the altSubjectName.  This parameter is
+optional but may occur several times to add several email addresses to
+a certificate.
+
+@item Name-DNS: @var{string}
+The is an DNS name for the altSubjectName.  This parameter is optional
+but may occur several times to add several DNS names to a certificate.
+
+@item Name-URI: @var{string}
+This is an URI for the altSubjectName.  This parameter is optional but
+may occur several times to add several URIs to a certificate.
+@end table
+
+@noindent
+Additional parameters used to create a certificate (in contrast to a
+certificate signing request):
+
+@table @asis
+
+@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 arbitrary length.  The special value @samp{random} can be
+used to create a 64 bit random serial number.
+
+@item Issuer-DN: @var{issuer-name}
+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.
+
+@item Creation-Date: @var{iso-date}
+@itemx Not-Before: @var{iso-date}
+Set the notBefore date of the certificate.  Either a date like
+@samp{1986-04-26} or @samp{1986-04-26 12:00} or a standard ISO
+timestamp like @samp{19860426T042640} may be used.  The time is
+considered to be UTC.  If it is not given the current date is used.
+
+@item Expire-Date: @var{iso-date}
+@itemx Not-After: @var{iso-date}
+Set the notAfter date of the certificate.  Either a date like
+@samp{2063-04-05} or @samp{2063-04-05 17:00} or a standard ISO
+timestamp like @samp{20630405T170000} may be used.  The time is
+considered to be UTC.  If it is not given a default value in the not
+too far future is used.
+
+@item Signing-Key: @var{keygrip}
+This gives the keygrip of the key used to sign the certificate.  If it
+is not given a self-signed certificate will be created.  For
+compatibility with future versions, it is suggested to prefix the
+keygrip with a @samp{&}.
+
+@item Hash-Algo: @var{hash-algo}
+Use @var{hash-algo} for this CSR or certificate.  The supported hash
+algorithms are: @samp{sha1}, @samp{sha256}, @samp{sha384} and
+@samp{sha512}; they may also be specified with uppercase letters.  The
+default is @samp{sha256}.
+
+@end table
+
+@c *******************************************
+@c ***************           *****************
+@c ***************  ASSSUAN  *****************
+@c ***************           *****************
+@c *******************************************
+@node GPGSM Protocol
+@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
+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.
+
+@menu
+* GPGSM ENCRYPT::         Encrypting a message.
+* GPGSM DECRYPT::         Decrypting a message.
+* GPGSM SIGN::            Signing a message.
+* GPGSM VERIFY::          Verifying a message.
+* GPGSM GENKEY::          Generating a key.
+* GPGSM LISTKEYS::        List available keys.
+* 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 OPTION::          Session options.
+@end menu
+
+
+@node GPGSM ENCRYPT
+@subsection Encrypting a Message
+
+Before encryption can be done the recipient must be set using the
+command:
+
+@example
+  RECIPIENT @var{userID}
+@end example
+
+Set the recipient for the encryption.  @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
+the recipient cannot be used, the encryption will then not be done for
+this recipient.  If the policy is not to encrypt at all if not all
+recipients are valid, the client has to take care of this.  All
+@code{RECIPIENT} commands are cumulative until a @code{RESET} or an
+successful @code{ENCRYPT} command.
+
+@example
+  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.  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 advise the server that the
+input data is in @acronym{PEM} format, @code{--base64} advises that a
+raw base-64 encoding is used, @code{--binary} advises of raw binary
+input (@acronym{BER}).  If none of these options is used, the server
+tries to figure out the used encoding, but this may not always be
+correct.
+
+@example
+  OUTPUT FD[=@var{n}] [--armor|--base64]
+@end example
+
+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 the client
+should consider this session failed.
+
+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
+
+@example
+  ENCRYPT
+@end example
+
+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.  @command{GPGSM} does ensure that there
+will not 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
+been done while setting the recipients.  The input and output pipes are
+closed.
+
+
+@node GPGSM DECRYPT
+@subsection Decrypting a message
+
+Input and output FDs are set the same way as in encryption, but
+@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.
+
+The decryption is done by using the command
+
+@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
+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.
+
+
+@node GPGSM SIGN
+@subsection Signing a Message
+
+Signing is usually done with these commands:
+
+@example
+  INPUT FD[=@var{n}] [--armor|--base64|--binary]
+@end example
+
+This tells @command{GPGSM} to read the data to sign from file descriptor @var{n}.
+
+@example
+  OUTPUT FD[=@var{m}] [--armor|--base64]
+@end example
+
+Write the output to file descriptor @var{m}.  If a detached signature is
+requested, only the signature is written.
+
+@example
+  SIGN [--detached]
+@end example
+
+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
+the configuration file.  To get finer control over the keys, it is
+possible to use the command
+
+@example
+  SIGNER @var{userID}
+@end example
+
+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
+the key cannot be used, the signature will then not be created using
+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
+contrast to the @code{RECIPIENT} command.
+
+
+@node GPGSM VERIFY
+@subsection Verifying a Message
+
+To verify a message the command:
+
+@example
+  VERIFY
+@end example
+
+is used. It does a verify operation on the message send to the input FD.
+The result is written out using status lines.  If an output FD was
+given, the signed text will be written to that.  If the signature is a
+detached one, the server will inquire about the signed material and the
+client must provide it.
+
+@node GPGSM GENKEY
+@subsection Generating a Key
+
+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
+@command{GPGSM} can be used to restrict the use of this command.
+
+@example
+  GENKEY
+@end example
+
+@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:
+
+@example
+    S: INQUIRE KEY_PARAM native
+    C: D foo:fgfgfg
+    C: D bar
+    C: END
+@end example
+
+Please note that the server may send Status info lines while reading the
+data lines from the client.  After this the key generation takes place
+and the server eventually does send an ERR or OK response.  Status lines
+may be issued as a progress indicator.
+
+
+@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:
+
+@example
+  LISTKEYS  @var{pattern}
+@end example
+
+is used.  To allow multiple patterns (which are ORed during the search)
+quoting is required: Spaces are to be translated into "+" or into "%20";
+in turn this requires that the usual escape quoting rules are done.
+
+@example
+  LISTSECRETKEYS @var{pattern}
+@end example
+
+Lists only the keys where a secret key is available.
+
+The list commands are affected by the option
+
+@example
+  OPTION list-mode=@var{mode}
+@end example
+
+where mode may be:
+@table @code
+@item 0
+Use default (which is usually the same as 1).
+@item 1
+List only the internal keys.
+@item 2
+List only the external keys.
+@item 3
+List internal and external keys.
+@end table
+
+Note that options are valid for the entire session.
+
+
+@node GPGSM EXPORT
+@subsection Export certificates
+
+To export certificate from the internal key database the command:
+
+@example
+  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.
+
+If the @option{--data} option has not been given, the format of the
+output depends on what was set with the @code{OUTPUT} command.  When using
+@acronym{PEM} encoding a few informational lines are prepended.
+
+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
+in the same way as with the @code{OUTPUT} command.
+
+
+@node GPGSM IMPORT
+@subsection Import certificates
+
+To import certificates into the internal key database, the command
+
+@example
+  IMPORT [--re-import]
+@end example
+
+is used.  The data is expected on the file descriptor set with the
+@code{INPUT} command.  Certain checks are performed on the
+certificate.  Note that the code will also handle PKCS#12 files and
+import private keys; a helper program is used for that.
+
+With the option @option{--re-import} the input data is expected to a be
+a linefeed separated list of fingerprints.  The command will re-import
+the corresponding certificates; that is they are made permanent by
+removing their ephemeral flag.
+
+
+@node GPGSM DELETE
+@subsection Delete certificates
+
+To delete a certificate the command
+
+@example
+  DELKEYS @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 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
+
+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.
+@item agent-check
+Return OK if the agent is running.
+@item cmd_has_option @var{cmd} @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.
+@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
+certificates, 0 does not include any certificates, 1 includes only the
+signers certificate 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
+@ifset isman
+@command{gpg2}(1),
+@command{gpg-agent}(1)
+@end ifset
+@include see-also-note.texi