Move parameter file description to the manual.
[gnupg.git] / doc / gpgsm.texi
index 5835c72..2beaf2d 100644 (file)
@@ -21,7 +21,7 @@
 .IR dir ]
 .RB [ \-\-options
 .IR file ]
-.RI [ options ]  
+.RI [ options ]
 .I command
 .RI [ args ]
 @end ifset
@@ -31,7 +31,7 @@
 @command{gpgsm} is a tool similar to @command{gpg} to provide digital
 encryption and signing services on X.509 certificates and the CMS
 protocol.  It is mainly used as a backend for S/MIME mail processing.
-@command{gpgsm} includes a full features certificate management and
+@command{gpgsm} includes a full featured certificate management and
 complies with all rules defined for the German Sphinx project.
 
 @manpause
@@ -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
@@ -286,10 +288,10 @@ smartcard is not yet supported.
 @node GPGSM Options
 @section Option Summary
 
-@command{GPGSM} comes features a bunch of options to control the exact behaviour
+@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}.
 
@@ -446,7 +448,16 @@ use of the chain model.  The chain model is also used if an option in
 the @file{trustlist.txt} or an attribute of the certificate requests it.
 However the standard model (shell) is in that case always tried first.
 
-
+@item --ignore-cert-extension @var{oid}
+@opindex ignore-cert-extension
+Add @var{oid} to the list of ignored certificate extensions.  The
+@var{oid} is expected to be in dotted decimal form, like
+@code{2.5.29.3}.  This option may be used more than once.  Critical
+flagged certificate extensions matching one of the OIDs in the list
+are treated as if they are actually handled and thus the certificate
+won't be rejected due to an unknown critical extension.  Use this
+option with care because extensions are usually flagged as critical
+for a reason.
 
 @end table
 
@@ -461,9 +472,9 @@ However the standard model (shell) is in that case always tried first.
 @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.
 
@@ -533,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
@@ -545,6 +556,10 @@ This option is therefore useful to simply verify a certificate.
 For standard key listings, also print the MD5 fingerprint of the
 certificate.
 
+@item --with-keygrip
+Include the keygrip in standard key listings.  Note that the keygrip is
+always listed in --with-colons mode.
+
 @end table
 
 @c *******************************************
@@ -557,10 +572,9 @@ certificate.
 @item --include-certs @var{n}
 @opindex include-certs
 Using @var{n} of -2 includes all certificate except for the root cert,
--1 includes all certs, 0 does not include any certs, 1 includes only
-the signers cert (this is the default) and all other positive
-values include up to @var{n} certificates starting with the signer cert.
-The default is -2.
+-1 includes all certs, 0 does not include any certs, 1 includes only the
+signers cert and all other positive values include up to @var{n}
+certificates starting with the signer cert.  The default is -2.
 
 @item --cipher-algo @var{oid}
 @opindex cipher-algo
@@ -568,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
@@ -617,19 +631,25 @@ is given as fingerprint or keygrip.
 @item --debug-level @var{level}
 @opindex debug-level
 Select the debug level for investigating problems. @var{level} may be
-one of:
+a numeric value or by a keyword:
 
 @table @code
 @item none
-no debugging at all.
-@item basic  
-some basic debug messages
+No debugging at all.  A value of less than 1 may be used instead of
+the keyword.
+@item basic
+Some basic debug messages.  A value between 1 and 2 may be used
+instead of the keyword.
 @item advanced
-more verbose debug messages
+More verbose debug messages.  A value between 3 and 5 may be used
+instead of the keyword.
 @item expert
-even more detailed messages
+Even more detailed messages.  A value between 6 and 8 may be used
+instead of the keyword.
 @item guru
-all of the debug messages you can get
+All of the debug messages you can get. A value greater than 8 may be
+used instead of the keyword.  The creation of hash tracing files is
+only enabled if the keyword is used.
 @end table
 
 How these messages are mapped to the actual debugging flags is not
@@ -646,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)
@@ -753,7 +773,7 @@ like this:
 @c man:.RS
 @example
 # Allowed policies
-2.289.9.9  
+2.289.9.9
 @end example
 @c man:.RE
 
@@ -795,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}
@@ -868,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
 
@@ -887,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
@@ -907,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
@@ -933,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.
 
@@ -1019,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
@@ -1079,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
@@ -1131,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
@@ -1143,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
@@ -1179,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.
@@ -1190,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
@@ -1276,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