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.
- %echo text
- Print text as diagnostic.
- Suppress actual key generation (useful for syntax checking).
- Perform the key generation. Note that an implicit commit is done at
the next Key-Type parameter.
- 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 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
- 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’.