Move parameter file description to the manual.
[gnupg.git] / doc / gpgsm.texi
index 530169a..2beaf2d 100644 (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