Move parameter file description to the manual.

doc/ChangeLog

@@ -1,3 +1,8 @@
+2011-03-01  Werner Koch  <wk@g10code.com>
+
+	* gpgsm.texi (CSR and certificate creation): New.
+	* gpg.texi (Unattended GPG key generation): New.
+
 2010-10-29  David Shaw  <dshaw@jabberwocky.com>
 
 	* gpg.texi (GPG Configuration Options): Clarify that show-photos
@@ -191,7 +196,7 @@
 
 	* qualified.txt: Add new BnetzA certs 12R and 13R.
 	* com-certs.pem: Ditto.
-	* examples/trustlist.txt: Ditto. 
+	* examples/trustlist.txt: Ditto.
 
 2008-06-19  Werner Koch  <wk@g10code.com>
 
@@ -477,7 +482,7 @@
 
 2007-02-18  Werner Koch  <wk@g10code.com>
 
-	* gpg.texi (GPG Esoteric Options): No card reader options for gpg2. 
+	* gpg.texi (GPG Esoteric Options): No card reader options for gpg2.
 
 2007-02-14  Werner Koch  <wk@g10code.com>
 
@@ -552,7 +557,7 @@
 
 	* instguide.texi (Installation): New.
 	* assuan.texi (Assuan): Removed.  Use the libassuan manual instead.
-	* gnupg.texi: Reflect these changes. 
+	* gnupg.texi: Reflect these changes.
 
 	* gpg.texi: Make some parts depend on the "gpgone" set
 	command. This allows us to use the same source for gpg1 and gpg2.
@@ -707,7 +712,7 @@
 	* gnupg.texi: Include gpg.texi
 
 	* tools.texi: Add a few @command markups.
-	* gpgsm.texi: Ditto 
+	* gpgsm.texi: Ditto
 	* gpg-agent.texi: Ditto.
 	* scdaemon.texi: Ditto.
 
@@ -725,7 +730,7 @@
 	expected pinentry filename.
 
         Changed license of the manual stuff to GPL.
-	
+
 	* gnupg.texi (Top): New menu item Helper Tools.
 
 	* tools.texi (Helper Tools): New.
@@ -831,7 +836,7 @@
 2002-05-14  Werner Koch  <wk@gnupg.org>
 
 	* Makefile.am, gpgsm.texi: New.
-	
+
  Copyright 2002, 2004, 2005, 2006, 2007, 2008, 2010 Free Software Foundation, Inc.
 
  This file is free software; as a special exception the author gives

doc/DETAILS

@@ -785,199 +785,12 @@ would result in:
 
 Key generation
 ==============
-    See the Libcrypt manual.
+See the Libcrypt manual.
 
 
 Unattended key generation
 =========================
-This feature allows unattended generation of keys controlled by a
+The the manual for a description.
-parameter file.  To use this feature, you use --gen-key together with
---batch and feed the parameters either from stdin or from a file given
-on the commandline.  The description below is only for GPG; GPGSM has
-a similar feature, see the file sm/certreqgen.c for a description.
-
-The format of this file is as follows:
-  o Text only, line length is limited to about 1000 chars.
-  o You must use UTF-8 encoding to specify non-ascii characters.
-  o Empty lines are ignored.
-  o Leading and trailing spaces are ignored.
-  o A hash sign as the first non white space character indicates a comment line.
-  o Control statements are indicated by a leading percent sign, the
-    arguments are separated by white space from the keyword.
-  o Parameters are specified by a keyword, followed by a colon.  Arguments
-    are separated by white space.
-  o The first parameter must be "Key-Type", control statements
-    may be placed anywhere.
-  o Key generation takes place when either the end of the parameter file
-    is reached, the next "Key-Type" parameter is encountered or at the
-    control statement "%commit"
-  o Control statements:
-    %echo <text>
-	Print <text>.
-    %dry-run
-	Suppress actual key generation (useful for syntax checking).
-    %commit
-	Perform the key generation.  An implicit commit is done
-	at the next "Key-Type" parameter.
-    %pubring <filename>
-    %secring <filename>
-	Do not write the key to the default or commandline given
-	keyring but to <filename>.  This must be given before the first
-	commit to take place, duplicate specification of the same filename
-	is ignored, the last filename before a commit is used.
-	The filename is used until a new filename is used (at commit points)
-	and all keys are written to that file.	If a new filename is given,
-	this file is created (and overwrites an existing one).
-        GnuPG < 2.1:  Both control statements must be given.
-        GnuPG >= 2.1: "%secring" is now a no-op.
-    %ask-passphrase
-        Enable a mode where the command "passphrase" is ignored and
-        instead the usual passphrase dialog is used.  This does not
-        make sense for batch key generation; however the unattended
-        key generation feature is also used by GUIs and this feature
-        relinquishes the GUI from implementing its own passphrase
-        entry code.  This is a global option.
-    %no-ask-passphrase
-        Disable the ask-passphrase mode.
-    %no-protection
-        With GnuPG 2.1 it is not anymore possible to specify a
-        passphrase for unattended key generation.  The passphrase
-        command is simply ignored and %ask-passpharse is thus
-        implicitly enabled.  Using this option allows to the creation
-        of keys without any passphrases.  This option is mainly
-        intended for regression tests.
-    %transient-key
-        If given the keys are created using a faster and a somewhat
-        less secure random number generator.  This option may be used
-        for keys which are only used for a short time and do not
-        require full cryptographic strength.  It takes only effect if
-        used together with the option no-protection.
-
-   o The order of the parameters does not matter except for "Key-Type"
-     which must be the first parameter.  The parameters are only for the
-     generated keyblock and parameters from previous key generations are not
-     used. Some syntactically checks may be performed.
-     The currently defined parameters are:
-     Key-Type: <algo-number>|<algo-string>
-	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.  It may be "default" to use the default
-	one; in this case don't give a Key-Usage and use "default" for
-	the Subkey-Type.
-     Key-Length: <length-in-bits>
-	Length of the key in bits.  The default is returned by running
-        the command "gpg --gpgconf-list".
-     Key-Usage: <usage-list>
-        Space or comma delimited list of key usage, allowed values are
-        "encrypt", "sign", and "auth".  This is used to generate the
-        key flags.  Please make sure that the algorithm is capable of
-        this usage.  Note that OpenPGP requires that all primary keys
-        are capable of certification, so no matter what usage is given
-        here, the "cert" flag will be on.  If no Key-Usage is
-        specified and the key-type is not "default", all allowed
-        usages for that particular algorithm are used; if it is not
-        given but "default" is used the usage will be "sign".
-     Subkey-Type: <algo-number>|<algo-string>
-	This generates a secondary key.  Currently only one subkey
-	can be handled.  "default" is also supported.
-     Subkey-Length: <length-in-bits>
-	Length of the subkey in bits.  The default is returned by running
-        the command "gpg --gpgconf-list".
-     Subkey-Usage: <usage-list>
-        Similar to Key-Usage.
-     Passphrase: <string>
-	If you want to specify a passphrase for the secret key,
-	enter it here.	Default is not to use any passphrase.
-     Name-Real: <string>
-     Name-Comment: <string>
-     Name-Email: <string>
-	The 3 parts of a key. Remember to use UTF-8 here.
-	If you don't give any of them, no user ID is created.
-     Expire-Date: <iso-date>|(<number>[d|w|m|y])
-	Set the expiration date for the key (and the subkey).  It may
-	either be entered in ISO date format (2000-08-15) or as number
-	of days, weeks, month or years.  The special notation
-	"seconds=N" is also allowed to directly give an Epoch
-	value. Without a letter days are assumed.  Note that there is
-	no check done on the overflow of the type used by OpenPGP for
-	timestamps.  Thus you better make sure that the given value
-	make sense.  Although OpenPGP works with time intervals, GnuPG
-	uses an absolute value internally and thus the last year we
-	can represent is 2105.
-     Creation-Date: <iso-date>
-        Set the creation date of the key as stored in the key
-        information and which is also part of the fingerprint
-        calculation.  Either a date like "1986-04-26" or a full
-        timestamp like "19860426T042640" may be used.  The time is
-        considered to be UTC.  If it is not given the current time
-        is used.
-     Preferences: <string>
-        Set the cipher, hash, and compression preference values for
-	this key.  This expects the same type of string as "setpref"
-	in the --edit menu.
-     Revoker: <algo>:<fpr> [sensitive]
-        Add a designated revoker to the generated key.  Algo is the
-	public key algorithm of the designated revoker (i.e. RSA=1,
-	DSA=17, etc.)  Fpr is the fingerprint of the designated
-	revoker.  The optional "sensitive" flag marks the designated
-	revoker as sensitive information.  Only v4 keys may be
-	designated revokers.
-     Handle: <string>
-        This is an optional parameter only used with the status lines
-        KEY_CREATED and KEY_NOT_CREATED.  STRING may be up to 100
-        characters and should not contain spaces.  It is useful for
-        batch key generation to associate a key parameter block with a
-        status line.
-     Keyserver: <string>
-        This is an optional parameter that specifies the preferred
-        keyserver URL for the key.
-
-
-Here is an example on how to create a key:
-$ cat >foo <<EOF
-     %echo Generating a basic OpenPGP key
-     Key-Type: DSA
-     Key-Length: 1024
-     Subkey-Type: ELG-E
-     Subkey-Length: 1024
-     Name-Real: Joe Tester
-     Name-Comment: with stupid passphrase
-     Name-Email: joe@foo.bar
-     Expire-Date: 0
-     Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
-     # Do a commit here, so that we can later print "done" :-)
-     %commit
-     %echo done
-EOF
-$ gpg --batch --gen-key foo
- [...]
-$ gpg --no-default-keyring --secret-keyring ./foo.sec \
-				  --keyring ./foo.pub --list-secret-keys
-/home/wk/work/gnupg-stable/scratch/foo.sec
-------------------------------------------
-sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar>
-ssb  1024g/8F70E2C0 2000-03-09
-
-If you want to create a key with the default algorithms you would
-use these parameters:
-
-     %echo Generating a default key
-     Key-Type: default
-     Subkey-Type: default
-     Name-Real: Joe Tester
-     Name-Comment: with stupid passphrase
-     Name-Email: joe@foo.bar
-     Expire-Date: 0
-     Passphrase: abc
-     %pubring foo.pub
-     %secring foo.sec
-     # Do a commit here, so that we can later print "done" :-)
-     %commit
-     %echo done
-
-
 
 
 Layout of the TrustDB

doc/gpg.texi

@@ -32,7 +32,7 @@ gpg
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
+.RI [ options ]
 .I command
 .RI [ args ]
 @end ifset
@@ -57,7 +57,7 @@ gpg2
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
+.RI [ options ]
 .I command
 .RI [ args ]
 @end ifset
@@ -98,16 +98,16 @@ page and at @inforef{Top,GnuPG 1,gpg}.
 @mancont
 
 @menu
-* GPG Commands::        List of all commands.
+* GPG Commands::            List of all commands.
-* GPG Options::         List of all options.
+* GPG Options::             List of all options.
-* GPG Configuration::   Configuration files.
+* GPG Configuration::       Configuration files.
-* GPG Examples::        Some usage examples.
+* GPG Examples::            Some usage examples.
 
 Developer information:
-@c * Unattended Usage::      Using @command{gpg} from other programs.
+* Unattended Usage of GPG:: Using @command{gpg} from other programs.
-@c * GPG Protocol::        The protocol the server mode uses.
 @end menu
 
+@c * GPG Protocol::        The protocol the server mode uses.
 
 
 @c *******************************************
@@ -303,7 +303,7 @@ secret key is not usable (for example, if it was created via
 @opindex list-sigs
 Same as @option{--list-keys}, but the signatures are listed too.
 @ifclear gpgone
-This command has the same effect as 
+This command has the same effect as
 using @option{--list-keys} with @option{--with-sig-list}.
 @end ifclear
 
@@ -326,7 +326,7 @@ Same as @option{--list-sigs}, but the signatures are verified.  Note
 that for performance reasons the revocation status of a signing key is
 not shown.
 @ifclear gpgone
-This command has the same effect as 
+This command has the same effect as
 using @option{--list-keys} with @option{--with-sig-check}.
 @end ifclear
 
@@ -2204,7 +2204,7 @@ a numeric value or by a keyword:
 @item none
 No debugging at all.  A value of less than 1 may be used instead of
 the keyword.
-@item basic  
+@item basic
 Some basic debug messages.  A value between 1 and 2 may be used
 instead of the keyword.
 @item advanced
@@ -2613,7 +2613,7 @@ Allow processing of multiple OpenPGP messages contained in a single file
 or stream.  Some programs that call GPG are not prepared to deal with
 multiple messages being processed together, so this option defaults to
 no.  Note that versions of GPG prior to 1.4.7 always allowed multiple
-messages.  
+messages.
 
 Warning: Do not use this option unless you need it as a temporary
 workaround!
@@ -2833,7 +2833,7 @@ translation is loaded from
 @code{@var{gpgdir}/gnupg.nls/@var{langid}.mo}.  Here @var{gpgdir} is the
 directory out of which the gpg binary has been loaded.  If it can't be
 loaded the Registry is tried and as last resort the native Windows
-locale system is used.  
+locale system is used.
 
 @end table
 
@@ -2964,11 +2964,264 @@ Before you report a bug you should first search the mailing list
 archives for similar problems and second check whether such a bug has
 already been reported to our bug tracker at http://bugs.gnupg.org .
 
+@c *******************************************
+@c ***************              **************
+@c ***************  UNATTENDED  **************
+@c ***************              **************
+@c *******************************************
+@manpause
+@node Unattended Usage of GPG
+@section Unattended Usage
+
+@command{gpg} 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.  The options @option{--status-fd} and @option{--batch}
+are almost always required for this.
+
+@menu
+* Unattended GPG key generation::  Unattended key generation
+@end menu
+
+
+@node Unattended GPG key generation,,,Unattended Usage of GPG
+@section Unattended key generation
+
+The command @option{--gen-key} may be used along with the option
+@option{--batch} for unattended key generation.  The parameters are
+either read from stdin or given as a file on the command line.
+The format of the parameter 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 keyblock (primary and subkeys); 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.
+
+@item %pubring @var{filename}
+@itemx %secring @var{filename}
+Do not write the key to the default or commandline given keyring but
+to @var{filename}.  This must be given before the first commit to take
+place, duplicate specification of the same filename is ignored, the
+last filename before a commit is used.  The filename is used until a
+new filename is used (at commit points) and all keys are written to
+that file. If a new filename is given, this file is created (and
+overwrites an existing one).  For gnuPG versions prior to 2.1, both
+control statements must be given. For GnuPG 2.1 and later
+@samp{%secring} is a no-op.
+
+@item %ask-passphrase
+@itemx %no-ask-passphrase
+Enable (or disable) a mode where the command @option{passphrase} is
+ignored and instead the usual passphrase dialog is used.  This does
+not make sense for batch key generation; however the unattended key
+generation feature is also used by GUIs and this feature relinquishes
+the GUI from implementing its own passphrase entry code.  These are
+global control statements and affect all future key genrations.
+
+@item %no-protection
+Since GnuPG version 2.1 it is not anymore possible to specify a
+passphrase for unattended key generation.  The passphrase command is
+simply ignored and @samp{%ask-passpharse} is thus implicitly enabled.
+Using this option allows the creation of keys without any passphrase
+protection.  This option is mainly intended for regression tests.
+
+@item %transient-key
+If given the keys are created using a faster and a somewhat less
+secure random number generator.  This option may be used for keys
+which are only used for a short time and do not require full
+cryptographic strength.  It takes only effect if used together with
+the control statement @samp{%no-protection}.
+
+@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.  @var{algo} may either be an OpenPGP algorithm number or a
+string with the algorithm name.  The special value @samp{default} may
+be used for @var{algo} to create the default key type; in this case a
+@samp{Key-Usage} shall not be given and @samp{default} also be used
+for @samp{Subkey-Type}.
+
+@item Key-Length: @var{nbits}
+The requested length of the generated key in bits.  The default is
+returned by running the command @samp{gpg2 --gpgconf-list}.
+
+@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 usages.  Allowed values are
+@samp{encrypt}, @samp{sign}, and @samp{auth}.  This is used to
+generate the key flags.  Please make sure that the algorithm is
+capable of this usage.  Note that OpenPGP requires that all primary
+keys are capable of certification, so no matter what usage is given
+here, the @samp{cert} flag will be on.  If no @samp{Key-Usage} is
+specified and the @samp{Key-Type} is not @samp{default}, all allowed
+usages for that particular algorithm are used; if it is not given but
+@samp{default} is used the usage will be @samp{sign}.
+
+@item Subkey-Type: @var{algo}
+This generates a secondary key (subkey).  Currently only one subkey
+can be handled.  See also @samp{Key-Type} above.
+
+@item Subkey-Length: @var{nbits}
+Length of the secondary key (subkey) in bits.  The default is returned
+by running the command @samp{gpg2 --gpgconf-list}".
+
+@item Subkey-Usage: @var{usage-list}
+Key usage lists for a subkey; similar to @samp{Key-Usage}.
+
+@item Passphrase: @var{string}
+If you want to specify a passphrase for the secret key,
+enter it here.	Default is not to use any passphrase.
+
+@item Name-Real: @var{name}
+@itemx Name-Comment: @var{comment}
+@itemx Name-Email: @var{email}
+The three parts of a user name.  Remember to use UTF-8 encoding here.
+If you don't give any of them, no user ID is created.
+
+@item Expire-Date: @var{iso-date}|(@var{number}[d|w|m|y])
+Set the expiration date for the key (and the subkey).  It may either
+be entered in ISO date format (2000-08-15) or as number of days,
+weeks, month or years.  The special notation "seconds=N" is also
+allowed to directly give an Epoch value. Without a letter days are
+assumed.  Note that there is no check done on the overflow of the type
+used by OpenPGP for timestamps.  Thus you better make sure that the
+given value make sense.  Although OpenPGP works with time intervals,
+GnuPG uses an absolute value internally and thus the last year we can
+represent is 2105.
+
+@item  Ceation-Date: @var{iso-date}
+Set the creation date of the key as stored in the key information and
+which is also part of the fingerprint calculation.  Either a date like
+"1986-04-26" or a full timestamp like "19860426T042640" may be used.
+The time is considered to be UTC.  If it is not given the current time
+is used.
+
+@item Preferences: @var{string}
+Set the cipher, hash, and compression preference values for this key.
+This expects the same type of string as the sub-command @samp{setpref}
+in the @option{--edit-key} menu.
+
+@item  Revoker: @var{algo}:@var{fpr} [sensitive]
+Add a designated revoker to the generated key.  Algo is the public key
+algorithm of the designated revoker (i.e. RSA=1, DSA=17, etc.)
+@var{fpr} is the fingerprint of the designated revoker.  The optional
+@samp{sensitive} flag marks the designated revoker as sensitive
+information.  Only v4 keys may be designated revokers.
+
+@item Keyserver: @var{string}
+This is an optional parameter that specifies the preferred keyserver
+URL for the key.
+
+@item Handle: @var{string}
+This is an optional parameter only used with the status lines
+KEY_CREATED and KEY_NOT_CREATED.  @var{string} may be up to 100
+characters and should not contain spaces.  It is useful for batch key
+generation to associate a key parameter block with a status line.
+
+@end table
+
+@noindent
+Here is an example on how to create a key:
+@smallexample
+$ cat >foo <<EOF
+     %echo Generating a basic OpenPGP key
+     Key-Type: DSA
+     Key-Length: 1024
+     Subkey-Type: ELG-E
+     Subkey-Length: 1024
+     Name-Real: Joe Tester
+     Name-Comment: with stupid passphrase
+     Name-Email: joe@@foo.bar
+     Expire-Date: 0
+     Passphrase: abc
+     %pubring foo.pub
+     %secring foo.sec
+     # Do a commit here, so that we can later print "done" :-)
+     %commit
+     %echo done
+EOF
+$ gpg2 --batch --gen-key foo
+ [...]
+$ gpg2 --no-default-keyring --secret-keyring ./foo.sec \
+       --keyring ./foo.pub --list-secret-keys
+/home/wk/work/gnupg-stable/scratch/foo.sec
+------------------------------------------
+sec  1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@@foo.bar>
+ssb  1024g/8F70E2C0 2000-03-09
+@end smallexample
+
+
+@noindent
+If you want to create a key with the default algorithms you would use
+these parameters:
+@smallexample
+     %echo Generating a default key
+     Key-Type: default
+     Subkey-Type: default
+     Name-Real: Joe Tester
+     Name-Comment: with stupid passphrase
+     Name-Email: joe@@foo.bar
+     Expire-Date: 0
+     Passphrase: abc
+     %pubring foo.pub
+     %secring foo.sec
+     # Do a commit here, so that we can later print "done" :-)
+     %commit
+     %echo done
+@end smallexample
+
+
+
+
 @mansect see also
 @ifset isman
-@command{gpgv}(1), 
+@command{gpgv}(1),
 @ifclear gpgone
-@command{gpgsm}(1), 
+@command{gpgsm}(1),
 @command{gpg-agent}(1)
 @end ifclear
 @end ifset

doc/gpgsm.texi

@@ -21,7 +21,7 @@
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
+.RI [ options ]
 .I command
 .RI [ args ]
 @end ifset
@@ -124,7 +124,7 @@ in the keybox or those set with the @option{--local-user} option.
 @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}.
@@ -150,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
@@ -165,13 +165,15 @@ use @samp{--help} to get a list of supported operations.
 @table @gnupgtabopt
 @item --gen-key
 @opindex gen-key
-This command allows the creation of a certificate signing request.  It
+This command allows the creation of a certificate signing request or a
-is commonly used along with the @option{--output} option to save the
+self-signed certificate.  It is commonly used along with the
-created CSR into a file.  If used with the @option{--batch} a parameter
+@option{--output} option to save the created CSR or certificate into a
-file is used to create the CSR.
+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 
+@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
@@ -186,7 +188,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
@@ -289,7 +291,7 @@ smartcard is not yet supported.
 @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.
@@ -337,7 +339,7 @@ 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 environment variable @code{GPG_AGENT_INFO} is not
 set or a running agent can't be connected.
-  
+
 @item --dirmngr-program @var{file}
 @opindex dirmnr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
@@ -412,7 +414,7 @@ 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
@@ -422,7 +424,7 @@ Be default @acronym{OCSP} checks are disabled.  The enable option may
 be used to enable OCSP checks via Dirmngr.  If @acronym{CRL} checks
 are also enabled, CRLs will be used as a fallback if for some reason an
 OCSP request won't succeed.  Note, that you have to allow OCSP
-requests in Dirmngr's configuration too (option 
+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}.
 
@@ -470,9 +472,9 @@ for a reason.
 @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.
 
@@ -542,7 +544,7 @@ 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
@@ -580,7 +582,7 @@ 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
@@ -635,7 +637,7 @@ a numeric value or by a keyword:
 @item none
 No debugging at all.  A value of less than 1 may be used instead of
 the keyword.
-@item basic  
+@item basic
 Some basic debug messages.  A value between 1 and 2 may be used
 instead of the keyword.
 @item advanced
@@ -664,8 +666,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)  
+@item 1  (2)
-values of big number integers 
+values of big number integers
 @item 2  (4)
 low level crypto operations
 @item 5  (32)
@@ -771,7 +773,7 @@ like this:
 @c man:.RS
 @example
 # Allowed policies
-2.289.9.9  
+2.289.9.9
 @end example
 @c man:.RE
 
@@ -813,7 +815,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}
@@ -886,14 +888,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
 
@@ -905,6 +905,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
@@ -925,7 +926,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
@@ -951,13 +952,156 @@ this is a missing certificate.
 
 @end table
 
+@node CSR and certificate creation,,,Unattended Usage
+@section CSR and certificate creation
+
+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} and @samp{sign}.  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.
 
@@ -1037,11 +1181,11 @@ 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
@@ -1097,7 +1241,7 @@ 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
@@ -1149,7 +1293,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
@@ -1161,7 +1305,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
@@ -1197,7 +1341,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.
@@ -1208,7 +1352,7 @@ List internal and external keys.
 @end table
 
 Note that options are valid for the entire session.
-    
+
 
 @node GPGSM EXPORT
 @subsection Export certificates
@@ -1294,7 +1438,7 @@ The leading two dashes usually used with @var{opt} shall not be given.
 
 @mansect see also
 @ifset isman
-@command{gpg2}(1), 
+@command{gpg2}(1),
 @command{gpg-agent}(1)
 @end ifset
 @include see-also-note.texi

sm/certreqgen.c

@@ -19,127 +19,20 @@
  */
 
 /*
-The format of the native parameter file is follows:
+   The format of the parameter file is described in the manual under
-  o Text only, line length is limited to about 1000 chars.
+   "Unattended Usage".
-  o You must use UTF-8 encoding to specify non-ascii characters.
-  o Empty lines are ignored.
-  o Leading and trailing spaces are ignored.
-  o A hash sign as the first non white space character is a comment line.
-  o Control statements are indicated by a leading percent sign, the
-    arguments are separated by white space from the keyword.
-  o Parameters are specified by a keyword, followed by a colon.  Arguments
-    are separated by white space.
-  o The first parameter must be "Key-Type", control statements
-    may be placed anywhere.
-  o Key generation takes place when either the end of the parameter file
-    is reached, the next "Key-Type" parameter is encountered or at the
-    controlstatement "%commit"
-  o Control statements:
-    %echo <text>
-	Print <text>.
-    %dry-run
-	Suppress actual key generation (useful for syntax checking).
-    %commit
-	Perform the key generation.  Note that an implicit commit is done
-	at the next "Key-Type" parameter.
-    %certfile <filename>
-        [Not yet implemented!]
-	Do not write the certificate to the keyDB but to <filename>.
-        This must be given before the first
-	commit to take place, duplicate specification of the same filename
-	is ignored, the last filename before a commit is used.
-	The filename is used until a new filename is used (at commit points)
-	and all keys are written to that file.	If a new filename is given,
-	this file is created (and overwrites an existing one).
-	Both control statements must be given.
 
-   o The order of the parameters does not matter except for "Key-Type"
+   Here is an example:
-     which must be the first parameter.  The parameters are only for the
+     $ cat >foo <<EOF
-     generated keyblock and parameters from previous key generations are not
+     %echo Generating a standard key
-     used. Some syntactically checks may be performed.
+     Key-Type: RSA
-
+     Key-Length: 2048
-     The currently defined parameters are:
+     Name-DN: CN=test cert 1,OU=Aegypten Project,O=g10 Code GmbH,L=Ddorf,C=DE
-
+     Name-Email: joe@foo.bar
-     Key-Type: <algo>
+     # Do a commit here, so that we can later print a "done"
-	Starts a new parameter block by giving the type of the
+     %commit
-	primary key. The algorithm must be capable of signing.
+     %echo done
-	This is a required parameter.  For now the only supported
+     EOF
-        algorithm is "rsa".
-
-     Key-Length: <length-in-bits>
-	Length of the key in bits.  Default is 2048.
-
-     Key-Grip: <hexstring>
-        This is optional and used to generate a request for an already
-        existing key.  Key-Length will be ignored when given,
-
-     Key-Usage: <usage-list>
-        Space or comma delimited list of key usage, allowed values are
-        "encrypt" and "sign".  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.
-
-     Name-DN: <subject_name>
-        This is the DN name of the subject in rfc2253 format.
-
-     Name-Email: <string>
-	The is an email address for the altSubjectName
-
-     Name-DNS: <string>
-	The is an DNS name for the altSubjectName
-
-     Name-URI: <string>
-	The is an URI for the altSubjectName
-
-     The following parameters are only used if a certificate (and not
-     a certificate signing request) is requested:
-
-     Serial: <sn>
-        If this parameter is given an X.509 certificate will be
-        generated.  SN is expected to be a hex string representing an
-        unsigned integer of arbitary length.  The special value
-        "random" can be used to crete a 64 bit random serial number.
-
-     Issuer-DN: <issuer_name>
-        This is the DN name of the issuer in rfc2253 format.  If it is
-        not set the subject DN will be used instead.  This creates a
-        self-signed certificate.  Only in this case a special GnuPG
-        extension will then be included in the certificate to mark it
-        as a standalone certificate.
-
-     Creation-Date: <iso-date>
-        Set the notBefore date of the certificate.  Either a date like
-        "1986-04-26" or a full timestamp like "19860426T042640" may be
-        used.  The time is considered to be UTC.  If it is not given
-        the current date is used.
-
-     Expire-Date: <iso-date>
-        Set the notBefore date of the certificate.  Either a date like
-        "1986-04-26" or a full timestamp like "19860426T042640" may be
-        used.  The time is considered to be UTC.  If it is not given a
-        default value is used.
-
-     Signing-Key: <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.
-
-     Hash-Algo: <hash-algo>
-        Use HASH-ALGO for this certificate.  The supported hash
-        algorithms are: "sha-1", "sha-256", "sha-384" and "sha-512".
-        "sha-1" is the default.
-
-Here is an example:
-$ cat >foo <<EOF
-%echo Generating a standard key
-Key-Type: RSA
-Key-Length: 2048
-Name-DN: CN=test cert 1,OU=Aegypten Project,O=g10 Code GmbH,L=Düsseldorf,C=DE
-Name-Email: joe@foo.bar
-# Do a commit here, so that we can later print "done" :-)
-%commit
-%echo done
-EOF
 */