Move parameter file description to the manual.
[gnupg.git] / doc / DETAILS
index 5870927..543ae4d 100644 (file)
@@ -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
-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
-
-
+The the manual for a description.
 
 
 Layout of the TrustDB