This document describes the parameters in the OpenSSL config file necessary for using pyCA.
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.
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.
- 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.
Page last modified: Thursday, 23-Aug-2001 20:28:42 CEST, sponsored by
stroeder.com - Information Technology, IT-Security, Identity Management, System Integration