security-and-privacy/gnupg
security-and-privacy/gnupg
1
0
Fork 0
mirror of git://git.gnupg.org/gnupg.git synced 2024-12-22 10:19:57 +01: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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
doc/ChangeLog
View File

@ -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

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

283
doc/gpg.texi
View File

@ -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 Options:: List of all options.
* GPG Configuration:: Configuration files.
* GPG Examples:: Some usage examples.
* GPG Commands:: List of all commands.
* GPG Options:: List of all options.
* GPG Configuration:: Configuration files.
* GPG Examples:: Some usage examples.
Developer information:
@c * Unattended Usage:: Using @command{gpg} from other programs.
@c * GPG Protocol:: The protocol the server mode uses.
* Unattended Usage of GPG:: Using @command{gpg} from other programs.
@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

214
doc/gpgsm.texi
View File

@ -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
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.
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.
@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)
values of big number integers
@item 1 (2)
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

133
sm/certreqgen.c
View File

@ -19,127 +19,20 @@
*/
/*
The format of the native parameter file is 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 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.
The format of the parameter file is described in the manual under
"Unattended Usage".
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>
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. For now the only supported
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
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=Ddorf,C=DE
Name-Email: joe@foo.bar
# Do a commit here, so that we can later print a "done"
%commit
%echo done
EOF
*/