Previous: Automated signature checking, Up: Unattended Usage

#### 4.5.2 CSR and certificate creation

Please notice: The immediate creation of certificates is only supported by GnuPG version 2.1 or later. With a 2.0 version you may only create a CSR.

The command `--gen-key` may be used along with the 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:

- 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 only supported value for algo is ‘`rsa`’.
Key-Length: nbits
  The requested length of a generated key in bits. Defaults to 2048.
Key-Grip: hexstring
  This is optional and used to generate a CSR or certificatet 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 arbitary 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 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.
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 ‘`sha1`’.