-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Please find attched the openssl.conf documentation that I wrote a
while ago. I have tidied it up a little since I last posted it a
few months back, but there have been no real changes.
There was a bit of debate when I previously posted it on what format
was best to present this in, but (to my knowledge) there was no
consensus.
I am therefore submitting it in ASCII format in the hope that it gets
included in 0.9.5 (or whatever the next release will be).
Regards,
Damien Miller
- --
| "Bombay is 250ms from New York in the new world order" - Alan Cox
| Damien Miller - http://www.mindrot.org/
| Email: [EMAIL PROTECTED] (home) -or- [EMAIL PROTECTED] (work)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.0 (GNU/Linux)
Comment: For info see http://www.gnupg.org
iD8DBQE4aEnqormJ9RG1dI8RAjThAKC7Q07ks+Skmgx4WoLN0QHSk3HG+QCfTig8
ubyGrRscXDyDx+MoIDQJSbI=
=9Pl5
-----END PGP SIGNATURE-----
OpenSSL configuration file
-------------------------
1. Introduction
The OpenSSL configuration file is used by several of the OpenSSL
applications, mainly x509, req and ca.
These applications read their path and configuration information from
the default openssl.conf or from a configuration file specified on
the command-line using the -config option or through the OPENSSL_CONF
environment variable.
Command-line arguments override defaults specified in the
configuration file.
This document assumes that the reader is familiar with the basics of
X.509 certificates and the certification process.
2. Layout
openssl.conf is broken into sections which are delimited by a section
name in square brackets, for example "[ my_ca ]". Some of these
section names are predefined, others may be defined by the user.
Where user defined sections exist, the tools must be informed about
them before they are used. This is done through configuration file
directives or command line arguments.
3. Syntax
Comments begin with a '#' character and may start anywhere on a line.
Blank lines and whitespace outside double quotes is ignored .
Apart from the section headers mentioned previously all directives are
in the form:
name = value
'name' consists of a text string, or (in certain sections) an ASN.1
OID.
The structure and contents of 'value' depends on the
context. Whitespace should be enclosed within double quotes '"'
(although this is not always enforced).
Values may contain references to environment variables, these are
specified as '$ENV::ENVVAR', replacing "ENVVAR" with the name of the
environment variable you wish to reference (for example "$ENV::HOME").
Values may also contain references to other configuration variables.
These are specified as '$name', '${name}' or '$(name}' where 'name' is
the name of a previously defined configuration variable. You will need
to use one of the bracketed forms ("$(name)" or "${name}") if your
reference is being used adjacent to alphanumeric characters.
Examples:
dir = /var/ssl/CA
certs = $dir/certs
my_name = happy
somevar = $(my_name)123
4. Global section
There are a few configuration variables that apply globally. In
addition to these you can define your own global variables that you
can use almost anywhere later.
4.1 RANDFILE
This variable specifies where the random seed will be loaded
from. This variable is used by most of the OpenSSL applications. It
should be set to a file that is not readable by other users. If the
file does not already exist, it will be created the next time one of
the application is run.
It is not recommended that this be set to /dev/[u]random on systems
that support it as large amounts of random data are read, which
may deplete the entropy pool. OpenSSL will automatically use these
facilities anyway.
Example:
RANDFILE = $ENV::HOME/.rnd
4.2 oid_file
This variable specifies the location of a file from which performs
ASN.1 OID -> name mappings. The objects specified in this file
are loaded and they are available by name for use by the openssl
applications or by user applications that call OBJ_create_objects() on
the config file.
Example:
oid_file = $ENV::HOME/.oid
4.3 extensions
This variable specifies a configuration section in which X.509v3
extensions are defined for use by the x509 application's -extfile
option. These extensions can also be placed alone in an empty file.
Example:
extensions = my_extensions
[ my_extensions ]
basicConstraints = critical, CA:true
4.4 oid_section
This variable specifies a configuration section in which ASN.1 OID to
name mappings are stored.
Example:
oid_section = my_oids
[ my_oids ]
someoid=1.2.3.4
5. OID section
The OID section maps ASN.1 OIDs (Object IDs) to names. The name of the
section is user defined and must be specified by the "oid_section"
variable in order to be recognised by applications that use them (ca,
req and any user applications).
Name/OID mappings are specified as "name = value" pairs where "name"
is the textual name for an OID and value is the OID path in dotted
decimal format. For example:
[ my_oids ]
my_org = 3.4.5.6.7
foo = $(my_org).8.9
bar = 3.4.5.6
6. CA section
6.1 default_ca
This variable specifies the name of a user-defined config section from
which to read the default CA settings for the OpenSSL ca application.
This can also be overridden from the command line (using the -name
option), so multiple CAs can be supported from the same configuration
file.
Example:
[ ca ]
default_ca = my_ca
7. User-defined CA configurations
The configuration file supports multiple CA configurations, each
in their own section. The default configuration is specified using
the "default_ca" variable above, but additional configuration can
be accessed using the "-name" command-line option to the OpenSSL ca
command.
7.1 dir
This variable specifies the top directory of the CA tree.
Example:
dir = /var/ssl/CA/my_ca
7.2 certs
This variable specifies where the issued certificates are kept.
This doesn't seem to do anything in practice.
Example:
certs = $dir/certs
7.3 crl_dir
This variable specifies where the issued CRL is kept.
This doesn't seem to do anything in practice?
Example:
crl_dir = $dir/crl
7.4 database
This file points to a textual database which stores infomration about
certificates which have been generated by the CA.
This consists of zero or more lines, each storing information about a
specific certificate.
Each line contains the following fields, seperated by tab characters:
- Certificate status
- 'V' = valid
- 'R' = revoked
- 'E' = expired
- Certificate expiry date in YYMMDDHHMMSSZ format.
- Date certificate was revoked (or blank if not revoked).
- Serial number of certificate.
- Filename of certificate if known.
- DN of certificate
This file is used by the ca application to keep track of certificates
and in the building of CRLs. It can also be used by user applications.
Example:
database = $dir/index.txt
7.5 new_certs_dir
This variable specifies where new certificates are stored when they
are created. Certificates are stored in in PEM format files named by
the certificate serial number (e.g. "$new_certs_dir/03.pem").
Example:
new_certs_dir = $dir/newcerts
7.6 certificate
This variable points to the CA's certificate file in PEM format.
Example:
certificate = $dir/cacert.pem
7.7 serial
This variable points to a text file containing the serial number of
the next certificate to be issued in hexidecimal format.
Example:
serial = $dir/serial
7.8 crl
This variable points to a file containing the current CRL in PEM
format.
Example:
crl = $dir/crl.pem
7.9 private_key
This variable points to the file containing the CA's private key in
PEM format.
Example:
private_key = $dir/private/cakey.pem
7.10 RANDFILE
This variable points to a random seed file which is local to the CA.
Example:
RANDFILE = $dir/private/.rand
7.11 x509_extensions
This variable specifies a user-defined configuration file section
containing X.509v3 extensions to be added to the certificate being
signed.
Example:
x509_extensions = my_exts
7.12 default_days
This variable specifies the default lifetime of the certificate from
the date of certification in days.
Example:
default_days = 365
7.13 default_crl_days
This variable specifies the default lifetime of a CRL from the date of
creation in days.
Example:
default_crl_days = 28
7.14 default_md
This variable specified the default message digest (hash) algorithm to
use in certificate signatures. Possible include "md2", "md5", "sha1",
"md5-sha1" and "ripemd160".
Example:
default_md = md5
7.15 preserve
This variable specifies whether the default ordering of the DN should
be preserved.
Example:
preserve = no
7.16 policy
This variable points to a user-defined config section which specifies
the policy to by applied to the DNs of the certificate requests being
signed. Using this parameter (and an appropriate policy), it is
possible to ensure that specific DN components are supplied and/or
ensure that DN components match those of the CA.
Example:
policy = policy_supplied
8 CA policy sections
The CA policy sections allow the administrator to specify the matching
rules applied to DN components in certificate requests to be signed.
A CA policy section consists of one or more DN component names and a
policy for each (in "name = value" format).
There are three possible policies: "optional", "supplied" and "match".
"optional" means that the specified DN component need not be supplied
in a certificate request and places no restrictions on its content if
present.
"match" means that the specified DN component must be supplied if
it exists in the CA's subject DN. If the DN component exists in the
CA's subject DN, then it must also match the one in the certificate
request. This can be used to lock a CA into certifying specific DN
paths only, e.g. an organisation may elect to only sign certificates
with the same organizationName.
"supplied" means that the specified DN component must be present in
the certificate request, but places no restrictions upon its content.
If the certificate request does not match the policy (e.g a "supplied"
field is not present, or a "match" field is not equal to the CA's),
then an error is generated when the CA attempts to sign the request.
DN components not explicitly specified in the policy are treated as
"optional".
Example:
[ mindrot_policy ]
countryName = match
stateOrProvinceName = match
localityName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
9 X509v3 extensions user-defined section
This section defines which X509v3 extensions will be added to a
certificate when it is certified.
The X509v3 extensions section consists of one or more extension names
(either pre-defined, loaded from an OID file or manually mapped to an
OID number) and the value assigned to it (in "name = value" format).
There are three main types of extensions: string extensions,
multi-valued extensions and raw extensions.
String extension value are specified in quotes, e.g
'nsComment = "foo"'.
Multi-valued extensions are contain one or more sub-values. Each
sub-value has a name and a value, seperated by a colon (e.g "foo:bar").
Multiple sub-values are seperated by commas, e.g
"basicConstraints=CA:TRUE, pathlen:10".
Alternatly they can be specifed in a seperate user-defined section by
prefixing the section name with and '@' symbol, e.g
"basicConstraints=@bc". This does not appear to interact well with
the special syntax for subjectAltName and issuerAlt name mentioned
below.
In some cases it is possible and valid for the same sub-value name to
appear multiple time (e.g in the case of email addresses in
subjectAltName). If you do this in a user defined section, then append
a period and a unique number to each sub-value name. e.g:
email.1 = [EMAIL PROTECTED]
email.2 = [EMAIL PROTECTED]
The extension value syntax allows marking extensions as critical. This
is done by prepending "critical, " to the extension value. e.g.
"basicConstraints = critical,CA:true"
It is also possible to encode raw OIDs and values. There is little
reason to encode a raw OID, as you can map them to names in the OID
section or in an OID file anyway. Raw values are encoded as the string
"RAW:" followed by one or more hex octets separated by colons, e.g:
"basicConstraints= critical, RAW:30:03:01:01:FF".
subjectAltName and issuerAltName are treated specially. subjectAltName
supports copying of the emailAddress from the requests's DN using the
"email:copy" directive. issuerAltName support copying of the issuer's
DN using the "issuer:copy" directive.
subjectAltName and issuerAltName also support the all of the RFC2459
attributes: "othername", "X400Name", "EdiPartyName", "email", "DNS",
"URI", "DirName", "IP" and "RID".
The subjectKeyIdentifier attribute supports the value "hash" to
include the a SHA1 hash of the public key as the key identifier.
The authorityKeyIdentifier attribute supports the values
"keyid:always" and "issuer:always" to copy the keyid and DN of the
CA's certificate.
Example:
[ my_v3_extns ]
basicConstraints = critical,CA:true, pathlen:20
keyUsage = cRLSign, keyCertSign
subjectAltName=email:copy
issuerAltName=issuer:copy, URI:http://www.ibs.com.au/
10. CRL extensions user-defined section
This section contains extensions to add to a CRL when one is
generated. Only issuerAltName and authorityKeyIdentifier make any
sense in a CRL. These follow the same syntax as they do in the
X.509v3 extensions section.
Example:
[ my_crl_extensions ]
issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always,issuer:always
11. req section
The req section defines the default configuration for certificate
requests generated by the req application. Many of its parameters can
be overridden at the command-line.
11.1 default_bits
This variable defines the default number of bits to be used for the
key when one is generated implicitly by the req application. It can be
overridden at the command-line using the -newkey parameter.
Example:
default_bits = 1024
11.2 default_keyfile
This file defines the default file in which to store a private key
when one is generated implicitly by the req application.
Example:
default_keyfile = privkey.pem
11.3 distinguished_name
This variable points to a user-defined config section which specifies
which DN components should be asked for in the generation of a
certificate request, the prompts used to ask for them and other
related details.
Example:
distinguished_name = my_favourite_req_style
11.4 attributes
This variable points to a user-defined config section which contains
certificate request attributes to be prompted for and included.
Example:
attributes = my_attributes
11.5 x509_extensions
This variable points to a user-defined config section which contains
X.509v3 extensions to be included when generating a self-signed
certificate.
Example:
x509_extensions = self_sign_exts
12 Certificate request DN user-defined section
This section defines which DN components should be asked for in the
creation of a certificate request, their default values and other
details such as their minimum and maximum lengths.
The request DN section consists of one or more DN component names
(either pre-defined, loaded from an OID file or manually mapped to
an OID number) and the text used to prompt for it (in "name = value"
format). Inclusion of a DN component will cause the req application
to prompt for it when generating a certificate request. User defined
variables cannot be used in DN component prompts.
You can specify multiple prompts for a DN component by prefixing
the name with a number followed by a period. e.g "0.commonName" and
"1.commonName".
To hard-code a DN component, specify the component name with "_value"
appended. e.g. "commonName_value = Damien Miller".
To specify the minimum or maximum lengths of a DN component, append
either "_min" or "_max" respectively. e.g "countryName_min = 2".
To specify a default value for a DN component, specify the component
name with the string "_default" appended. e.g "localityName_default =
Melbourne"
Example:
[ my_favorite_req_style ]
countryName = Country Name (2 letter code)
countryName_default = AU
countryName_min = 2
countryName_max = 2
stateOrProvinceName = "State or Province Name (full name)"
stateOrProvinceName_default = Victoria
localityName = Locality Name (eg, city)
localityName_default = Melbourne
organizationName_value = Mindrot.org
0.organizationalUnitName = Top level organizational unit
0.organizationalUnitName_default = Mindless paper pushing
0.organizationalUnitName = Subsection
1.organizationalUnitName_default = Bit twiddling division
commonName = Common Name (eg, YOUR name)
commonName_max = 64
13. Certificate request attributes user-defined section
This section defines attributes to be added to a certificate request .
The syntax is similar to the certificate request DN component section.
Example:
[ my_attribs ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
unstructuredName = An optional company name
14. An annotated openssl.conf
This is the openssl.conf that I set up for an internal CA. It contains
three CA definitions with slightly different policies and extensions.
# OpenSSL configuration of IBS internal Certification Authority
# Set location of random seed file
RANDFILE = /var/ssl/CA/.rnd
# Default CA spec to use
[ ca ]
default_ca = hostCA
# Specification of root CA
[ rootCA ]
dir = /var/ssl/CA/rootCA
certs = $dir/certs
crl_dir = $dir/crl
database = $dir/index.txt
new_certs_dir = $dir/newcerts
certificate = $dir/cacert.pem
serial = $dir/serial
crl = $dir/crl.pem
private_key = $dir/private/cakey.pem
RANDFILE = $dir/private/.rand
default_days = 1460
default_crl_days = 30
default_md = md5
preserve = no
# Specify CA policy. (see below)
# This CA signs certificates from within our organisation only.
policy = policy_match
# Specify extensions. (see below)
x509_extensions = root_ca
# Specification of CA for Enki auth certificates
[ enkiCA ]
dir = /var/ssl/CA/enkiCA
certs = $dir/certs
crl_dir = $dir/crl
database = $dir/index.txt
new_certs_dir = $dir/newcerts
certificate = $dir/cacert.pem
serial = $dir/serial
crl = $dir/crl.pem
private_key = $dir/private/cakey.pem
RANDFILE = $dir/private/.rand
default_days = 365
default_crl_days = 30
default_md = md5
preserve = no
# Specify CA policy. (see below)
# This CA signs certificates from outside our organisation, but we
# require some values to be filled out.
policy = policy_supplied
# What extensions to include (see below).
x509_extensions = enki_ca
# Specification of CA for host (server) certificates
[ hostCA ]
dir = /var/ssl/CA/hostCA
certs = $dir/certs
crl_dir = $dir/crl
database = $dir/index.txt
new_certs_dir = $dir/newcerts
certificate = $dir/cacert.pem
serial = $dir/serial
crl = $dir/crl.pem
private_key = $dir/private/cakey.pem
RANDFILE = $dir/private/.rand
default_days = 365
default_crl_days = 30
default_md = md5
preserve = no
# This CA signs certificates from within out organisation only.
policy = policy_match
# Extensions to include
x509_extensions = host_ca
# CA policies
[ policy_match ]
# Top level fields must match, commonName must be supplied
countryName = match
stateOrProvinceName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
[ policy_anything ]
# Anything goes, as long as commonName is supplied
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
[ policy_supplied ]
# Important fields must be supplied
countryName = supplied
stateOrProvinceName = supplied
localityName = optional
organizationName = supplied
organizationalUnitName = optional
commonName = supplied
emailAddress = optional
# X509v3 extensions for rootCA
[ root_ca ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always, issuer:always
#basicConstraints = critical,CA:true
basicConstraints = CA:true
keyUsage = cRLSign, keyCertSign
nsCertType = sslCA, emailCA
subjectAltName = email:copy
issuerAltName = issuer:copy
# X509v3 extensions for enkiCA
[enki_ca]
nsCertType = client
nsComment = "https://enki.ibs.com.au/"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
subjectAltName = email:copy
issuerAltName = issuer:copy
# X509v3 extensions for hostCA
[host_ca]
nsCertType = server
nsComment = "http://www.ibs.com.au/"
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid,issuer:always
subjectAltName = email:copy
issuerAltName = issuer:copy
# X509v3 extensions for self-signed certificates
[ self_sign ]
subjectKeyIdentifier = hash
authorityKeyIdentifier = keyid:always, issuer:always
#basicConstraints = critical,CA:true
basicConstraints = CA:true
keyUsage = cRLSign, keyCertSign
nsCertType = sslCA, emailCA
subjectAltName = email:copy
issuerAltName = issuer:copy
# Certificate request section
[ req ]
default_bits = 1024
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = self_sign
# What DN components to ask for
[ req_distinguished_name ]
countryName = "Country Name (2 letter ISO code)"
countryName_default = AU
countryName_min = 2
countryName_max = 2
stateOrProvinceName = "State or Province Name"
stateOrProvinceName_default = Victoria
localityName = "Locality Name (eg, city)"
localityName_default = Melbourne
organizationName = "Organization Name"
organizationName_default = "Internet Business Solutions Pty Ltd"
organizationalUnitName = "Organizational Unit"
commonName = "Common Name (user or host name)"
commonName_max = 64
emailAddress = "Email Address"
emailAddress_max = 40
[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20
