Reworked passing of envars to Pinentry.
[gnupg.git] / doc / gpgsm.texi
index beedab7..e784f71 100644 (file)
@@ -8,21 +8,40 @@
 @cindex command options
 @cindex options, GPGSM command
 
-@c man begin DESCRIPTION
-
+@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
-protocoll.  It is mainly used as a backend for S/MIME mail processing.
+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.
 
-@c man end
-
+@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:
@@ -30,60 +49,76 @@ Developer information:
 * 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
 @item --version
 @opindex version
-Print the program version and licensing information.  Not that you can
-abbreviate this command.
+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 usefule command-line options.
-Not that you can abbreviate this command.
+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.  Not that you can
+Print a list of all available options and commands.  Note that you cannot
 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
@@ -121,13 +156,19 @@ 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 creation of a certificate signing request.  It
+is commonly used along with the @option{--output} option to save the
+created CSR into a file.  If used with the @option{--batch} a parameter
+file is used to create the CSR.
 
 @item --list-keys
 @itemx -k 
@@ -147,11 +188,22 @@ is available.
 List certificates matching @var{pattern} using an external server.  This
 utilizes the @code{dirmngr} service.  
 
-@item --dump-keys
+@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
@@ -174,27 +226,47 @@ 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.  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
-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 higly insecure and this command is only provided if
-there is no other way to exchange the private key.
+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
@@ -205,6 +277,12 @@ smartcard is not yet supported.
 @end table
 
 
+@c *******************************************
+@c ***************            ****************
+@c ***************  OPTIONS   ****************
+@c ***************            ****************
+@c *******************************************
+@mansect options
 @node GPGSM Options
 @section Option Summary
 
@@ -219,8 +297,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
 
@@ -236,6 +316,9 @@ 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
@@ -266,7 +349,11 @@ a running dirmngr can't be connected.
 @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.
+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
@@ -279,6 +366,9 @@ 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
 
@@ -299,6 +389,21 @@ 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
@@ -306,14 +411,14 @@ 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 ke listing
+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 opton may
+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
@@ -321,8 +426,33 @@ 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
 
@@ -350,6 +480,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
@@ -357,6 +508,20 @@ 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
@@ -382,56 +547,93 @@ 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).
   
+@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 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.
+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 --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
+@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 releaes of this program. They are
+specified and may change with newer releases of this program. They are
 however carefully selected to best aid in debugging.
 
 @item --debug @var{flags}
@@ -441,24 +643,24 @@ 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
+@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}.
@@ -492,32 +694,185 @@ 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}.
 
-@c 
-@c  Examples
-@c
+@end table
+
+
+@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
 
@@ -576,9 +931,12 @@ 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.
 
@@ -603,6 +961,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
 
 
@@ -627,13 +986,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
@@ -643,7 +1005,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
@@ -701,13 +1063,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 @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
@@ -762,8 +1124,8 @@ 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 @command{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 
@@ -833,16 +1195,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
@@ -863,7 +1231,7 @@ 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}
@@ -876,3 +1244,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