copyright assignments are not anymore required.
[gnupg.git] / doc / gpgsm.texi
index d936b3e..bdb0378 100644 (file)
@@ -21,7 +21,7 @@
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
+.RI [ options ]
 .I command
 .RI [ args ]
 @end ifset
@@ -29,9 +29,9 @@
 
 @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
+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 features certificate management and
+@command{gpgsm} includes a full featured certificate management and
 complies with all rules defined for the German Sphinx project.
 
 @manpause
@@ -77,21 +77,22 @@ only one command is allowed.
 @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.
+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.
+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
 
@@ -122,8 +123,8 @@ 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 signatrue may also be checked.
+detached signature may also be checked.
+
 @item --server
 @opindex server
 Run in server mode and wait for commands on the @code{stdin}.
@@ -133,7 +134,7 @@ Run in server mode and wait for commands on the @code{stdin}.
 Behave as a Dirmngr client issuing the request @var{command} with the
 optional list of @var{args}.  The output of the Dirmngr is printed
 stdout.  Please note that file names given as arguments should have an
-absulte file name (i.e. commencing with @code{/} because they are
+absolute file name (i.e. commencing with @code{/} because they are
 passed verbatim to the Dirmngr and the working directory of the
 Dirmngr might not be the same as the one of this client.  Currently it
 is not possible to pass data via stdin to the Dirmngr.  @var{command}
@@ -149,7 +150,7 @@ 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. 
+use @samp{--help} to get a list of supported operations.
 
 
 @end table
@@ -164,12 +165,23 @@ use @samp{--help} to get a list of supported operations.
 @table @gnupgtabopt
 @item --gen-key
 @opindex gen-key
-This command allows the interactive creation of a certifcate signing
-request.  It is commonly used along with the @option{--output} option to
-save the created CSR into a file.
+@ifclear gpgtwoone
+-This command allows the creation of a certificate signing request.  It
+-is commonly used along with the @option{--output} option to save the
+-created CSR into a file.  If used with the @option{--batch} a parameter
+-file is used to create the CSR.
+@end ifclear
+@ifset gpgtwoone
+This command allows the creation of a certificate signing request or a
+self-signed certificate.  It is commonly used along with the
+@option{--output} option to save the created CSR or certificate into a
+file.  If used with the @option{--batch} a parameter file is used to
+create the CSR or certificate and it is further possible to create
+non-self-signed certificates.
+@end ifset
 
 @item --list-keys
-@itemx -k 
+@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
@@ -184,7 +196,7 @@ 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.  
+utilizes the @code{dirmngr} service.
 
 @item --list-chain
 @opindex list-chain
@@ -217,14 +229,20 @@ mainly for debugging.
 @opindex keydb-clear-some-cert-flags
 This is a debugging aid to reset certain flags in the key database
 which are used to cache certain certificate stati.  It is especially
-useful if a bad CRL or a weird running OCSP reponder did accidently
+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}.
+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
@@ -233,10 +251,12 @@ 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.
+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
@@ -276,15 +296,15 @@ smartcard is not yet supported.
 @node GPGSM Options
 @section Option Summary
 
-@command{GPGSM} comes features a bunch ofoptions to control the exact behaviour
+@command{GPGSM} features a bunch of options to control the exact behaviour
 and to change the default configuration.
 
-@menu 
+@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 don't want to do.
+* Esoteric Options::        Doing things one usually do not want to do.
 @end menu
 
 
@@ -294,7 +314,7 @@ and to change the default configuration.
 @node Configuration Options
 @subsection How to change the configuration
 
-These options are used to change the configuraton and are usually found
+These options are used to change the configuration and are usually found
 in the option file.
 
 @table @gnupgtabopt
@@ -325,15 +345,15 @@ Change the default name of the policy file to @var{filename}.
 @opindex agent-program
 Specify an agent program to be used for secret key operations.  The
 default value is the @file{/usr/local/bin/gpg-agent}.  This is only used
-as a fallback when the envrionment variable @code{GPG_AGENT_INFO} is not
-set or a running agent can't be connected.
-  
+as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
+set or a running agent cannot be connected.
+
 @item --dirmngr-program @var{file}
 @opindex dirmnr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
 default value is @file{/usr/sbin/dirmngr}.  This is only used as a
 fallback when the environment variable @code{DIRMNGR_INFO} is not set or
-a running dirmngr can't be connected.
+a running dirmngr cannot be connected.
 
 @item --prefer-system-dirmngr
 @opindex prefer-system-dirmngr
@@ -342,9 +362,12 @@ to connect to this one.  Fallback to a pipe based server if this does
 not work.  Under Windows this option is ignored because the system dirmngr is
 always used.
 
+@item --disable-dirmngr
+Entirely disable the use of the Dirmngr.
+
 @item --no-secmem-warning
 @opindex no-secmem-warning
-Don't print a warning when the so called "secure memory" can't be used.
+Do not print a warning when the so called "secure memory" cannot be used.
 
 @item --log-file @var{file}
 @opindex log-file
@@ -384,7 +407,7 @@ 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
+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
@@ -395,29 +418,29 @@ line of the @file{trustlist.txt}
 @opindex force-crl-refresh
 Tell the dirmngr to reload the CRL for each request.  For better
 performance, the dirmngr will actually optimize this by suppressing
-the loading for short time intervalls (e.g. 30 minutes). This option
+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. 
+command.  This option should not be used in a configuration file.
 
 @item  --enable-ocsp
 @itemx --disable-ocsp
 @opindex enable-ocsp
 @opindex disable-ocsp
-Be default @acronym{OCSP} checks are disabled.  The enable option may
+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 won't succeed.  Note, that you have to allow OCSP
-requests in Dirmngr's configuration too (option 
-@option{--allow-ocsp} and configure dirmngr properly.  If you don't do
+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 t search for the
+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
@@ -428,12 +451,22 @@ 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.
-
-
+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
 
@@ -447,10 +480,9 @@ However the standard model (shell) is in that case always tried first.
 @item --armor
 @itemx -a
 @opindex armor
-@opindex -a
-Create PEM encoded output.  Default is binary output. 
+Create PEM encoded output.  Default is binary output.
 
-@item --base64 
+@item --base64
 @opindex base64
 Create Base-64 encoded output; i.e. PEM without the header lines.
 
@@ -474,7 +506,7 @@ Assume the input data is binary encoded.
 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
+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.
@@ -491,7 +523,6 @@ set; however @option{--default-key} always overrides this.
 @item --local-user @var{user_id}
 @item -u @var{user_id}
 @opindex local-user
-@opindex -u
 Set the user(s) to be used for signing.  The default is the first
 secret key found in the database.
 
@@ -520,11 +551,11 @@ secret key.
 @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. 
+requires a CRL lookup and other operations.
 
 When used along with --import, a validation of the certificate to
 import is done and only imported if it succeeds the test.  Note that
-this does not affect an already available cwertificate in the DB.
+this does not affect an already available certificate in the DB.
 This option is therefore useful to simply verify a certificate.
 
 
@@ -532,6 +563,10 @@ This option is therefore useful to simply verify a certificate.
 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 --with-colons mode.
+
 @end table
 
 @c *******************************************
@@ -544,10 +579,9 @@ certificate.
 @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.
-
+-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
@@ -555,7 +589,13 @@ 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
 
 
@@ -564,7 +604,7 @@ encryption.  For convenience the strings @code{3DES}, @code{AES} and
 @c ********  ESOTERIC OPTIONS  ***************
 @c *******************************************
 @node Esoteric Options
-@subsection Doing things one usually don't want to do.
+@subsection Doing things one usually do not want to do.
 
 
 @table @gnupgtabopt
@@ -573,7 +613,7 @@ encryption.  For convenience the strings @code{3DES}, @code{AES} and
 @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
+processing model and thus needs to rely on the announced digest
 algorithms to properly hash the data.  As a workaround this option may
 be used to tell gpg to also hash the data using the algorithm
 @var{name}; this slows processing down a little bit but allows to verify
@@ -586,29 +626,37 @@ with @samp{SHA256} for @var{name}.
 @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.  Alternativly @var{epoch} may be given as a full ISO time string
+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.
+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:
+a numeric value or by a keyword:
 
 @table @code
 @item none
-no debugging at all.
-@item basic  
-some basic debug messages
+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
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
 @item expert
-even more detailed messages
+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
+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
@@ -625,8 +673,8 @@ 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 1  (2)
+values of big number integers
 @item 2  (4)
 low level crypto operations
 @item 5  (32)
@@ -641,7 +689,7 @@ write hashed data to files named @code{dbgmd-000*}
 trace Assuan protocol
 @end table
 
-Note, that all flags set using this option may get overriden by
+Note, that all flags set using this option may get overridden by
 @code{--debug-level}.
 
 @item --debug-all
@@ -664,7 +712,7 @@ 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 regresssion
+lets @command{gpgsm} ignore all notAfter dates, this is used by the regression
 tests.
 
 @item --fixed-passphrase @var{string}
@@ -673,6 +721,10 @@ 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
@@ -709,7 +761,8 @@ 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}).
+  --options}).  You should backup this file.
+
 
 @item policies.txt
 @cindex policies.txt
@@ -718,7 +771,8 @@ 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.
+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:
@@ -726,7 +780,7 @@ like this:
 @c man:.RS
 @example
 # Allowed policies
-2.289.9.9  
+2.289.9.9
 @end example
 @c man:.RE
 
@@ -768,7 +822,7 @@ 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 
+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}
@@ -780,16 +834,24 @@ 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/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 the a small
+start up with a working configuration.  For existing users a small
 helper script is provided to create these files (@pxref{addgnupghome}).
 
-For internal purposes gpgsm creates and maintaines a few other files;
-They all live in in the current home directory (@pxref{option
+For internal purposes gpgsm creates and maintains a few other files;
+they all live in in the current home directory (@pxref{option
 --homedir}).  Only @command{gpgsm} may modify these files.
 
 
@@ -798,12 +860,13 @@ They all live in in the current home directory (@pxref{option
 @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.
-      
+used to show the internal structure of this file.  You should backup
+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
+random number generator across invocations.  The same file is used by
 other programs of this software too.
 
 @item S.gpg-agent
@@ -812,7 +875,7 @@ 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
+describing a regular TCP listening port) is the standard way of
 connecting the @command{gpg-agent}.
 
 @end table
@@ -832,14 +895,12 @@ $ gpgsm -er goo@@bar.net <plaintext >ciphertext
 @end example
 
 
-@c man end
-
-
 @c *******************************************
 @c ***************              **************
 @c ***************  UNATTENDED  **************
 @c ***************              **************
 @c *******************************************
+@manpause
 @node Unattended Usage
 @section Unattended Usage
 
@@ -851,6 +912,7 @@ but may also be used in the standard operation mode by using the
 
 @menu
 * Automated signature checking::  Automated signature checking.
+* CSR and certificate creation::  CSR and certificate creation.
 @end menu
 
 @node Automated signature checking,,,Unattended Usage
@@ -858,7 +920,7 @@ but may also be used in the standard operation mode by using the
 
 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 ooperation si a bit complicated.  In mosted cases it is required
+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:
 
@@ -871,7 +933,7 @@ 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 
+  @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
@@ -883,7 +945,7 @@ these status codes:
 
 @item The signature is invalid
 This means that the signature verification failed (this is an indication
-of af a transfer error, a programm error or tampering with the message).
+of af 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}
@@ -891,19 +953,168 @@ of af a transfer error, a programm error or tampering with the message).
   @end table
 
 @item Error verifying a signature
-For some reason the signature could not be verified, i.e. it can't be
+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,,,Unattended Usage
+@section CSR and certificate creation
+
+@ifclear gpgtwoone
+@strong{Please notice}: The immediate creation of certificates is only
+supported by GnuPG version 2.1 or later.  With a 2.0 version you may
+only create a CSR.
+@end ifclear
+
+The command @option{--gen-key} may be used along with the option
+@option{--batch} to either create a certificate signing request (CSR)
+or an X.509 certificate. The 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 2048.
+
+@item Key-Grip: @var{hexstring}
+This is optional and used to generate a CSR or certificatet 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 arbitary 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 rfc2253 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{sha1}.
+
+@end table
 
 @c *******************************************
 @c ***************           *****************
 @c ***************  ASSSUAN  *****************
 @c ***************           *****************
 @c *******************************************
-@manpause
 @node GPGSM Protocol
 @section The Protocol the Server Mode Uses.
 
@@ -935,7 +1146,7 @@ Assuan manual for details.
 @node GPGSM ENCRYPT
 @subsection Encrypting a Message
 
-Before encrytion can be done the recipient must be set using the
+Before encryption can be done the recipient must be set using the
 command:
 
 @example
@@ -946,7 +1157,7 @@ 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 can't be used, the encryption will then not be done for
+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
@@ -983,18 +1194,19 @@ should consider this session failed.
 The option armor encodes the output in @acronym{PEM} format, the
 @code{--base64} option applies just a base 64 encoding.  No option
 creates binary output (@acronym{BER}).
-  
+
 The actual encryption is done using the command
 
 @example
-  ENCRYPT 
+  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 won't be any
+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
@@ -1043,14 +1255,14 @@ Write the output to file descriptor @var{m}.  If a detached signature is
 requested, only the signature is written.
 
 @example
-  SIGN [--detached] 
+  SIGN [--detached]
 @end example
 
 Sign the data set with the INPUT command and write it to the sink set by
 OUTPUT.  With @code{--detached}, a detached signature is created
 (surprise).
 
-The key used for signining is the default one or the one specified in
+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
 
@@ -1062,7 +1274,7 @@ to 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 can't be used, the signature will then not be created using
+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.
@@ -1095,7 +1307,7 @@ token is used to store the key.  Configuration options to
 @command{GPGSM} can be used to restrict the use of this command.
 
 @example
-  GENKEY 
+  GENKEY
 @end example
 
 @command{GPGSM} checks whether this command is allowed and then does an
@@ -1107,7 +1319,7 @@ key parameters in the native format:
     C: D foo:fgfgfg
     C: D bar
     C: END
-@end example    
+@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
@@ -1143,7 +1355,7 @@ The list commands  commands are affected by the option
 
 where mode may be:
 @table @code
-@item 0 
+@item 0
 Use default (which is usually the same as 1).
 @item 1
 List only the internal keys.
@@ -1154,7 +1366,7 @@ List internal and external keys.
 @end table
 
 Note that options are valid for the entire session.
-    
+
 
 @node GPGSM EXPORT
 @subsection Export certificates
@@ -1186,14 +1398,19 @@ in the same way as with the OUTPUT command.
 To import certificates into the internal key database, the command
 
 @example
-  IMPORT
+  IMPORT [--re-import]
 @end example
 
 is used.  The data is expected on the file descriptor set with the
-@code{INPUT} command.  Certain checks are performend on the
-certificate.  Note that the code will also handle PKCS\#12 files and
+@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
@@ -1226,11 +1443,16 @@ The value of @var{what} specifies the kind of information returned:
 Return the version of the program.
 @item pid
 Return the process id of the process.
+@item agent-check
+Return success if the agent is running.
+@item cmd_has_option @var{cmd} @var{opt}
+Return success if the command @var{cmd} implements the option @var{opt}.
+The leading two dashes usually used with @var{opt} shall not be given.
 @end table
 
 @mansect see also
 @ifset isman
-@command{gpg2}(1), 
+@command{gpg2}(1),
 @command{gpg-agent}(1)
 @end ifset
 @include see-also-note.texi