Disk Backend Module

Read and write certificates, serial numbers and certificate sign requests from and to files on disk.

What does it do?

Based on the configuration of paths and files, this module allows certificate sign requests to be saved to disk for later processing, and certificates to be returned from disk to clients that ask for them.

In addition, an OpenSSL compatible serial file and index database can be used to generate serial numbers for certificates and stored for later access in an index database.

This module allows a typical disk based OpenSSL certificate authority to become accessible over the web.

Module Integration

The mod_ca_disk module is a backend module and will not do anything useful until mod_ca_disk has been combined with one or more frontend modules and optional backend modules listed below. The mod_ca_disk module provides the following hooks, and suitable frontend modules must be configured to implement each protocol as needed.

All backend modules run within a standard Apache httpd request, and standard httpd functionality applies in all cases.

Sign Request Hook

When this hook is triggered, this module saves the certificate sign request to disk ready for later processing. Protocols like SCEP provide a mechanism to register the request for a certificate, and then return the results when ready.

This module provides the following implementations of this hook.

Sign Request Save To Disk Saves the certificate revocation list to a directory on disk for later processing.

This hook is called by the following frontend modules.

mod_csr Generate and issue certificates in response to an X509 certificate request.
mod_pkcs12 Generate public/private key pairs and and issue certificates in response to a application/x-www-form-urlencoded form request.
mod_scep Generate and issue certificates using the SCEP protocol.
mod_spkac Generate and issue certificates using the SPKAC protocol.

Certificate Storage Hook

When this hook is triggered, this module saves the newly generated certificate to a directory.

This module provides the following implementations of this hook.

Certificate Storage Save To Disk Saves the newly generated certificate to a directory.

This hook is called by the following frontend modules.

mod_csr Generate and issue certificates in response to an X509 certificate request.
mod_pkcs12 Generate public/private key pairs and and issue certificates in response to a application/x-www-form-urlencoded form request.
mod_scep Generate and issue certificates using the SCEP protocol.
mod_spkac Generate and issue certificates using the SPKAC protocol.

Get Certificate Hook

When this hook is triggered, certificates that were generated earlier are returned from the specified directory.

This module provides the following implementations of this hook.

Get Certificate From Disk Returns the certificate from a directory on disk written during earlier processing. This hook implementation will trigger the Get Certificate Chain Hook to add a certificate chain to the given certificate.

This hook is called by the following frontend modules.

mod_scep Generate and issue certificates using the SCEP protocol.

Make Serial Hook

When this hook is triggered, this module returns the next serial number after the one stored in the current serial file. The serial number can optionally be stored in an OpenSSL compatible database index file.

This module provides the following implementations of this hook.

Make Next Serial From Disk Returns the next serial number from the contents of a file on disk.

This hook is called by the following frontend modules and backend modules.

mod_ca_engine This hook signs a given certificate sign request using an OpenSSL provided crypto engine such as a smartcard, using the serial number returned by this module.
mod_ca_simple This hook signs a given certificate sign request, using the serial number returned by this module.
mod_timestamp Parse and return responses to RFC3161 Time Stamp Protocol requests.

Examples

SCEP Example

Save incoming certificate sign requests to an incoming directory, then serve the resulting certificates back when ready. In this example, certificates are signed out of band.


# backend configuration:
<IfModule mod_ca_disk.c>
  CADiskCertificateSignRequestPath /etc/pki/CA/certs/
  CADiskCertificateByTransactionPath /etc/pki/CA/certs/
</IfModule>

# frontend configuration:
<IfModule mod_scep.c>
  <Location /scep>
    SetHandler scep
    ScepSubjectRequest commonName
  </Location>
</IfModule>

OpenSSL Serial / Index Example

In this example we generate serial numbers from the OpenSSL serial file, and we keep track of certificates issued by writing them to the OpenSSL index.


# backend configuration:
<IfModule mod_ca_disk.c>
  CADiskSerialFile /etc/pki/CA/serial
  CADiskIndexFile /etc/pki/CA/index.txt
  CADiskCertificateBySerialPath /etc/pki/CA/certs/
</IfModule>
<IfModule mod_ca_simple.c>
  CASimpleTime on
</IfModule>

# frontend configuration:
<IfModule mod_csr.c>
  <Location /csr>
    SetHandler csr
    CsrSubjectRequest CN
  </Location>
</IfModule>

Hook Implementation Reference

The following backend hook implementations are provided by this module.

Sign Request Save To Disk

Saves the certificate revocation list to a directory on disk for later processing.

The CADiskCertificateSignRequestPath directive enables this hook implementation.

Each certificate sign request is written to a file named after the transaction ID, with the extension csr.

Certificate Storage Save To Disk

Saves the newly generated certificate to a directory.

If the CADiskCertificateBySerialPath directive is used, the certificate is stored in the given directory with the name corresponding to the certificate serial number, and the default extension pem. This matches the behaviour of the new_certs_dir option in an OpenSSL openssl.cnf file.

Alternatively, if the CADiskCertificateByTransactionPath directive is used, the certificate is stored in the given directory with the name corresponding to the transaction ID and the default extension cert.

Get Certificate From Disk

Returns the certificate from a directory on disk written during earlier processing.

If the CADiskCertificateBySerialPath directive is enabled, and the serial number of the certificate has been kept aside during earlier processing, the certificate will be read from a file matching the serial number expressed as a hex value, and the default extension pem.

Alternatively, if the CADiskCertificateByTransactionPath directive is used, the certificate is read from the given directory with the name corresponding to the transaction ID and the default extension cert.

This hook will trigger the Get Certificate Chain Hook to add the certificate chain to the certificate.

Make Next Serial From Disk

Returns the next serial number from the contents of a file on disk.

If the CADiskSerialFile directive is enabled, the number in the file is read in, incremented, saved and returned as the serial number for this certificate.

The serial number file corresponds to and is designed to work with the serial parameter in the openssl.cnf file in OpenSSL.

If the CADiskIndexFile directive is enabled, the resulting serial number and subject is written to the given index file. The database index file corresponds to and is designed to work with the database parameter in the openssl.cnf file in OpenSSL.

If the CADiskIndexUnique directive is enabled, the request will fail if the combination of serial number and subject has been seen before. This option corresponds to the unique_subject option in the OpenSSL openssl.cnf file.

Directive Reference

CADiskCertificateSignRequestPath Directive

Description Set to the path where certificate sign requests should be stored.
Syntax CADiskCertificateSignRequestPath path
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_disk
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the path where certificate sign requests should be stored.

Incoming certificate sign requests will be written to the path specified by this directive, for later processing. Each certificate sign request is written to a file named after the transaction ID, with the extension csr.

CADiskCertificateByTransactionPath Directive

Description Set to the path for certificates keyed by transaction, followed by optional suffix (defaults to 'cert').
Syntax CADiskCertificateByTransactionPath path [suffix]
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_disk
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the path for certificates keyed by transaction, followed by optional suffix.

Signed certificates will be written to and stored at the path specified by this directive, for record, or later retrieval. Each certificate sign request is written to a file named after the transaction ID, with the default extension cert. This extension can be overridden.

CADiskCertificateBySerialPath Directive

Description Set to the path for certificates keyed by serial number, followed by optional suffix (defaults to 'pem').
Syntax CADiskCertificateBySerialPath path [suffix]
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_disk
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the path for certificates keyed by serial number, followed by optional suffix.

Signed certificates will be written to and stored at the path specified by this directive, for record, or later retrieval. Each certificate sign request is written to a file named after the certificate serial number, with the default extension pem. This extension can be overridden.

CADiskSerialFile Directive

Description Set to the name of the serial file.
Syntax CADiskSerialFile file
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_disk
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of a file containing the last used serial number.

If this directive is used, this module will increment and return the serial number in the given file to the ca_makeserial hook.

The serial number file corresponds to and is designed to work with the serial parameter in the openssl.cnf file in OpenSSL.

CADiskIndexFile Directive

Description Set to the name of the database index file.
Syntax CADiskIndexFile file
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_disk
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of a file containing the index database.

This directive requires the CADiskSerialFile directive to be set for this directive to take effect.

If this directive is used, this module will add the serial number and subject to the database file in the ca_makeserial hook.

The database index file corresponds to and is designed to work with the database parameter in the openssl.cnf file in OpenSSL.

CADiskIndexUnique Directive

Description If enabled, the certificate subject must be unique.
Syntax CADiskIndexUnique flag
Default CADiskIndexUnique false
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_disk
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

If enabled, the certificate subject must be unique.

This directive requires the CADiskSerialFile and CADiskIndexFile directives to be set for this directive to take effect.

If this directive is used, the serial number and subject being added to the database file in the ca_makeserial hook will fail if the serial number has been used before.