This document describes the parameters in the OpenSSL config file necessary for
using pyCA.
Table of Contents
The goal of pyCA is to keep as much configuration data in
OpenSSL's configuration file (most times called openssl.cnf)
as possible because it is much easier to keep one file up-to-date
and consistent. pyCA also tries to reduce administrative
tasks and end-user's frustration by generating specific input forms for
a certain CA definition (certificate type) to avoid users generating
invalid certificate requests which does not fulfill the policy of a
certificate authority.
Although a lot of parameters already known in OpenSSL are used it
was necessary to add some new sections and attributes for reaching
this goal. These extensions have nothing to do with the OpenSSL-package
itself and hopefully will not conflict with new parameters introduced
in OpenSSL.
Module pycacnf.py
Although pyCA tries to get all configuration parameters from the
OpenSSL config file there are two parameters which have to be configured
in the Python module pycacnf.py which has to be located together
with the CGI-BIN programs and scripts or in the system's Python path:
-
The path of the OpenSSL's config file (e.g. /usr/local/ssl/lib/openssl.cnf)
is configured in the variable cnf_filename.
-
If you are not allowed to place Python modules in the system's Python path
you can list more directories containing modules in the list
variable pylib.
Or simply set the environment variable PYCALIB to define
the name of the directory containing the modules.
pyCA tries to make use of as many parameters given in the
OpenSSL configuration file as possible. Therefore you should
set up all sections in a reasonable manner refering to OpenSSL's
documentation. pyCA defines some additional parameters which are
defined below. All parameter names are handled case-sensitive!
You can create a pre-compiled binary copy of your configuration file
by running pickle-cnf.py to gain
better performance.
The pathname of the pre-compiled copy is always presumed to be cnf_filename
with the suffix .pickle.
The Python modules cPickle (if existent) or pickle are
used for reading this pre-compiled copy. If this fails the source of
the configuration file is read. You have to take care that the pre-compiled
copy is up-to-date and reflects your actual configuration by running
pickle-cnf.py after every change of
the source!
The term CA name used in this document specifies the
name of a CA definition in the section [ ca ].
Each name of a CA has to be unique and points to a CA section which contains
several parameters for this certain CA.
Some parameters only used by pyCA are configured in an
own proprietary section named [ pyca ].
-
OpenSSLExec
-
Full pathname of the openssl executable (default /usr/local/ssl/bin/openssl).
-
CaFixExec
-
ignored since 0.5.3 - use the more
flexible ca_x509_extfile parameter
-
TmpDir
-
Directory for temporary files (default /tmp).
-
caCertConfirmReqLog
-
(since 0.6.6)
Path to file for log output of
ca-certreq-mail.py. The directory must be writeable for the
user defined with parameter userMailDaemon.
-
caPendCertReqDir
-
ignored since 0.5.0 - use the more
flexible pend_reqs_dir parameter
-
caNewCertReqDir
-
ignored since 0.5.0 - use the more
flexible new_reqs_dir parameter
-
userCAAdmin
-
(since 0.5.4)
Existing username of the user maintaining the CA data.
Used for setting the ownership of various files and directories in
ca-make.py.
Example:
userCAAdmin = caadmin
-
userMailDaemon
-
(since 0.5.4)
Existing username of the user running the mail delivery demon.
Used for setting the ownership of certificate request spool directories
pend_reqs_dir and new_reqs_dir
in ca-make.py.
Example:
userMailDaemon = daemon
-
userWWWRun
-
(since 0.5.4)
Existing username of the user running the web server.
Used for setting the ownership of certificate request spool directories
pend_reqs_dir and new_reqs_dir
in ca-make.py.
Example:
userWWWRun = wwwrun
-
ErrorLog
-
(since 0.5.3)
Normally errors are written to sys.stderr which is most times written
to the error log of the web server. You can redirect Python's sys.stderr
to an dedicated error log file by providing a pathname here which is handy
in situation where you do not have access to the web error logs.
Note that the file has to be writeable by the user the web server runs as
(see also userWWWRun).
-
MailRelay
-
The default SMTP mail relay.
Example:
MailRelay = mail.domain.my
-
caAdminMailAdr
-
(since 0.6.2)
Mail address of the CA's administrator. Is used as default
address for some tasks in ca-cycle-pub.py.
-
caCertReqMailAdr
-
Mail address of the mail dialogue script for certificate requests.
If empty, no mail dialogue is initiated.
-
caCertFormat
-
Ignored since 0.6.0!
Specified the format of all stored certificate data.
(nice idea but the code gets too messy...)
-
PreferDERCerts
-
ignored since 0.5.0
-
caPendCertReqValid
-
Amount of time [h] how long a pending certificate request is stored
in pend_reqs_dir without being
confirmed by e-mail. Set to zero to disable automatic deletion
of stale certificate requests by ca-cycle-pub.py.
-
caInternalCertTypes
-
List CA names (see section [ ca ] for which certificate
requests can only be created from an internal network
(see caInternalIPAdr and
caInternalDomains).
The integrity of your PKI should not rely on such mechanisms!
Example:
caInternalCertTypes = Member, Admin
-
caInternalIPAdr
-
List of IP network addresses/-masks which are considered internal
(see caInternalCertTypes).
The integrity of your PKI should not rely on such mechanisms!
Example:
caInternalIPAdr = 127.0.0.0/255.0.0.0,10.0.0.0/255.0.0.0
-
caInternalDomains
-
List of email address domains which are considered internal
(see caInternalCertTypes).
The integrity of your PKI should not rely on such mechanisms!
caInternalDomains = domain1.my,domain2.my,trusteddomain.other
-
caIntermediateCACerts
-
(since 0.6.2)
List CA names (see section [ ca ]
for which handling of intermediate CA certs should be provided.
E.g. get-cert.py will send
the intermediate CA certs as chain together with the downloaded
certificate.
Example:
caIntermediateCACerts = Persona,Friends,Member
-
nsBaseUrl
-
Base-URL for the all URL addresses.
This is meant as fallback option if the CA-specific
attribute nsBaseUrl (see section x509_extensions)
is not set.
-
nsCAIndexUrl
-
Relative URL address of ca-index.py.
-
nsEnrollUrl
-
Relative URL address of ns-enroll.py.
-
nsGetCertUrl
-
Relative URL address of get-cert.py
-
nsViewCertUrl
-
Relative URL address of view-cert.py
-
HelpUrl
-
Relative URL directory of help texts (e.g. ns-enroll-help.html).
-
ScriptMethod
-
Preferred HTTP method for submitting form parameters.
Example:
ScriptMethod = POST
-
htmlBodyParam
-
(since 0.4.5)
Specifies the parameter string placed in the <BODY>-tag in
the output of the CGI-BIN-programs
-
htmlBodyText, htmlBodyLink, htmlBodyVlink, htmlBodyBgColor, htmlBodyBackground
-
ignored since 0.4.5 - use the more
flexible htmlBodyParam parameter
Parameters for the CA definition (separate CA sections referred
by the CA's name in section [ ca ]).
Parameters already known in OpenSSL
Many standard parameters of the OpenSSL config are used.
Refer to the OpenSSL docs for reading about these.
-
dir
-
Where everything is kept
-
certs
-
Where the issued certs are kept
-
crl_dir
-
Where the issued crl are kept
-
database
-
Certificate database index file.
-
new_certs_dir
-
Default place for new certs.
-
certificate
-
The CA certificate
-
serial
-
The filename containing current serial number.
-
crl
-
The current CRL
-
private_key
-
The private key of the CA
-
default_crl_days
-
how long before next CRL
-
policy
-
Name of policy section
-
x509_extensions
-
Name of section with X.509v3 extension attributes
Special parameters for pyCA
-
signedby
-
CA name of the CA which issued (or will issue) the CA certificate.
This pyCA attribute in the CA definition section allows building
CA hierarchies with ca-make.py. Up to now only a two-level
hierarchy is supported.
-
pend_reqs_dir
-
(since 0.5.0)
Directory for storing certificate requests (default $dir/pendreqs).
This directory has to be writeable only for the user/group the web server
is run as and readable/writeable for the local mail delivery demon.
It has to be readable/writeable for CA administrator's user if you
want to enable automatic deletion of stale certificate requests
(see script ca-cycle-pub.py and
option caPendCertReqValid).
-
new_reqs_dir
-
(since 0.5.0)
Directory for storing certificate requests after mail dialogue (default $dir/newreqs).
This directory has to be writable only for the mail delivery demon
and readable/writeable for the CA administrator's user.
-
req
-
(since 0.5.0)
Name of req section to be used when creating
certificate requests for this CA definition. If this parameter is not
set the section [ req ] is used.
-
min_key_size
-
(since 0.5.3)
Minimum required key size depending on CAs policy (default 0). If this is
set to a value greater than 0 there is a note displayed in
ns-enroll.py right above the
<KEYGEN>-tag to inform the user about the required key size of a
certain certificate type and the submitted key size is checked.
-
ca_reqfile
-
(since 0.5.3)
Pathname of the request config file to be used in
ca-make.py
for creating the certificate request for the CA certificate.
-
ca_x509_extfile
-
(since 0.5.3)
Pathname of the file containing the extended X.509v3 attributes to be used
in ca-make.py
for signing the CA certificate.
Parts of the input form generated by
ns-enroll.py for a specific
certificate type is defined by a req section already
known in OpenSSL.
Parameters already known in OpenSSL
-
[parameter]
-
(since 0.4.2)
Displayed description for this specific parameter.
-
[parameter]_max
-
(since 0.4.2)
Maximum length for this specific parameter.
-
[parameter]_default
-
(since 0.4.2)
Default for the specific parameter. If you define a comma-separated list
a select list is generated in the input form.
Special parameters for pyCA
-
[parameter]_regex
-
(since 0.4.2)
Regular expression for valid strings.
ns-enroll.py uses the
definitions in the policy section for generating specific
input forms depending on the certificate type to prevent users from generating
invalid certificate requests.
For each attribute name you can define one of the following policy options:
-
matched
-
The [parameter]_default is read from the
req section and displayed as fixed
input parameter in the input form (<INPUT TYPE=HIDDEN VALUE="[parameter]_default">).
-
supplied
-
An input field or select list with [parameter]_default is shown and
the input field is handled as required.
-
optional
-
An input field or select list with [parameter]_default. The user
is allowed to leave this input field empty.
Several X.509v3 extensions defined in the x509_extensions section
are used to display URLs or determine the type of certificate usage.
-
nsComment
-
This is used to display a nice comment in
ca-index.py and
ns-enroll.py about the
certificate usage.
-
nsBaseUrl
-
This is the base URL for all other URL addresses.
-
nsCaRevocationUrl
-
This is used in ca-index.py
to display a link for downloading the latest certificate
revocation list (CRL) of a certificate authority.
-
nsRevocationUrl
-
Up to now this parameter is not used in pyCA.
-
nsCaPolicyUrl
-
This is used in
ca-index.py and
ns-enroll.py
to display a link to the certification practice statement of
a certificate authority.
-
keyUsage
-
This is used to determine the certificate usage according
to PKIX (not implemented yet).
-
nsCertType
-
This is used to determine the certificate usage according to
Netscape specification.