security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2025-07-03 22:56:33 +02:00
Code Activity

Move parameter file description to the manual.

Browse source
This commit is contained in:
Werner Koch 2011-03-01 17:08:49 +01:00
parent 28c157b55c
commit 00f8b68505
5 changed files with 473 additions and 365 deletions
Download patch file Download diff file Expand all files Collapse all files

191
doc/DETAILS
View 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