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:

    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/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).

    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!
    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.