This document describes the parameters in the OpenSSL config file necessary for using pyCA.

## Table of Contents

- Module pycacnf.py
- OpenSSL configuration file (openssl.cnf)
- Section [ pyca ]
- CA Sections
- req Sections
- policy Sections
- x509_extensions Sections
- Example

## Abstract

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.

## OpenSSL configuration file

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!

### Pre-compilation

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!

### Section [ ca ]

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.

### Section [ pyca ]

Some parameters only used by pyCA are configured in an own proprietary section named [ pyca ].

#### Files and directories

OpenSSLExec
  Full pathname of the openssl executable (default /usr/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).

#### Mail-Options

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.

#### CA-Options

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!<BR Example:
  `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`

#### WWW-Options

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

### CA Section

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.

### req Section

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.

### policy Section

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.

### x509_extensions Section

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.