File: gnupg.info,  Node: CSR and certificate creation,  Prev: Automated signature checking,  Up: Unattended Usage

5.5.2 CSR and certificate creation
----------------------------------

The command '--generate-key' may be used along with the option '--batch'
to either create a certificate signing request (CSR) or an X.509
certificate.  This is controlled by a parameter file; the format of this
file is as follows:

   * Text only, line length is limited to about 1000 characters.
   * UTF-8 encoding must be used to specify non-ASCII characters.
   * Empty lines are ignored.
   * Leading and trailing while space is ignored.
   * A hash sign as the first non white space character indicates a
     comment line.
   * Control statements are indicated by a leading percent sign, the
     arguments are separated by white space from the keyword.
   * Parameters are specified by a keyword, followed by a colon.
     Arguments are separated by white space.
   * The first parameter must be 'Key-Type', control statements may be
     placed anywhere.
   * The order of the parameters does not matter except for '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.
   * 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' is encountered.

Control statements:

%echo TEXT
     Print TEXT as diagnostic.

%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.

General Parameters:

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.  The supported values for ALGO are 'rsa', 'ecdsa', and
     'eddsa'.

Key-Length: NBITS
     The requested length of a generated key in bits.  Defaults to 3072.
     The value is ignored for ECC algorithms.

Key-Grip: HEXSTRING
     This is optional and used to generate a CSR or certificate 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', 'sign' and 'cert'.  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 Distinguished Name (DN) of the subject in RFC-2253
     format.

Name-Email: 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.

Name-DNS: 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.

Name-URI: STRING
     This is an URI for the altSubjectName.  This parameter is optional
     but may occur several times to add several URIs to a certificate.

Additional parameters used to create a certificate (in contrast to a
certificate signing request):

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 arbitrary length.  The special value 'random' can be used to
     create a 64 bit random serial number.

Issuer-DN: ISSUER-NAME
     This is the DN name of the issuer in RFC-2253 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.

Creation-Date: ISO-DATE
Not-Before: ISO-DATE
     Set the notBefore date of the certificate.  Either a date like
     '1986-04-26' or '1986-04-26 12:00' or a standard ISO 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
Not-After: ISO-DATE
     Set the notAfter date of the certificate.  Either a date like
     '2063-04-05' or '2063-04-05 17:00' or a standard ISO timestamp like
     '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.

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.  For
     compatibility with future versions, it is suggested to prefix the
     keygrip with a '&'.

Hash-Algo: HASH-ALGO
     Use HASH-ALGO for this CSR or certificate.  The supported hash
     algorithms are: 'sha1', 'sha256', 'sha384' and 'sha512'; they may
     also be specified with uppercase letters.  The default is 'sha256'.

Authority-Key-Id: HEXSTRING
     Insert the decoded value of HEXSTRING as authorityKeyIdentifier.
     If this is not given and an ECC algorithm is used the public part
     of the certified public key is used as authorityKeyIdentifier.  To
     inhibit any authorityKeyIdentifier use the special value 'none' for
     HEXSTRING.

Subject-Key-Id: HEXSTRING
     Insert the decoded value of HEXSTRING as subjectKeyIdentifier.  If
     this is not given and an ECC algorithm is used the public part of
     the signing key is used as authorityKeyIdentifier.  To inhibit any
     subjectKeyIdentifier use the special value 'none' for HEXSTRING.