Engine Backend Module

Sign certificates using certificates and keys on a smartcard or HSM using the OpenSSL ENGINE mechanism.

What does it do?

This module provides set of signing functions that can be used to sign certificate sign requests backed with the OpenSSL ENGINE mechanism.

Based on the configuration, this module performs signing of an incoming certificate sign request using a certificate and key stored on an HSM or smartcard.

Module Integration

The mod_ca_engine module is a backend module and will not do anything useful until mod_ca_engine has been combined with one or more frontend modules and optional backend modules listed below. The mod_ca_engine 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 signs the certificate sign request using a certificate on the local disk, and a key on an HSM or smartcard using the OpenSSL ENGINE mechanism.

This module provides the following implementations of this hook.

Engine Sign Request Signs the certificate sign request using a key stored on an HSM or smartcard.

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 Chain Hook

When this hook is triggered, this module returns the intermediate certificate chain used to sign certificate sign requests, if any and present.

This module provides the following implementations of this hook.

mod_ca_engine This hook returns the certificate chain of a certificate provided by an OpenSSL provided crypto engine such as a smartcard.

This hook is called by the following 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.

Make Serial Hook

When this hook is triggered, the Sign Request Hook asks for a serial number to use when signing the certificate.

Implementations of this hook are provided by other modules.

Make Next Serial From Disk Returns the next serial number from the contents of a file on disk.
Simple Make Serial From Subject Returns the serial number from that embedded within the subject of the certificate sign request.
Simple Make Random Serial Returns a random serial number.

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.

Get Time Hook

When this hook is triggered, the Sign Request Hook asks for the time to use when signing the certificate.

Implementations of this hook are provided by other modules.

mod_ca_simple This hook returns the time to be used to sign a certificate sign request, derived from the system time.

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.

Get Certificate Authority Hook

When this hook is triggered, this module returns the root CA certificate used to sign certificate sign requests.

This module provides the following implementations of this hook.

Engine Get Certificate Authority Returns the certificate authority certificate used to sign the request.

This hook is called by the following frontend modules.

mod_ocsp Respond with the revocation status of a certificate.
mod_scep Generate and issue certificates using the SCEP protocol.

Get Next Certificate Authority Hook

When this hook is triggered, this module returns the next root CA certificate that will in future be used to sign certificate sign requests.

This module provides the following implementations of this hook.

Engine Get Next Certificate Authority Returns the next certificate authority certificate that will be used to sign future requests.

This hook is called by the following frontend modules.

mod_scep Generate and issue certificates using the SCEP protocol.

Examples

Basic Example

The simplest case: issue a certificate to anybody who wants one.


# global configuration
<IfModule mod_ca_engine.c>
  CAEngineDevice dynamic
  CAEnginePreCommand SO_PATH /usr/lib64/engines-1.1/pkcs11.so
  CAEnginePreCommand ID pkcs11
  CAEnginePreCommand LIST_ADD 1
  CAEnginePreCommand LOAD
  CAEnginePreCommand MODULE_PATH /usr/lib64/opensc-pkcs11.so
  CAEnginePreCommand PIN ${KEYPIN}
</IfModule>

# backend configuration:
<IfModule mod_ca_simple.c>
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on
</IfModule>
<IfModule mod_ca_engine.c>
  # sign with this certificate...
  CAEngineCertificate /etc/pki/tls/ca-cert.pem
  # ...and private key
  CAEngineKey "${KEYURI}"
  # add extensions for a typical CA
  CAEngineExtension basicConstraints CA:FALSE
  CAEngineExtension keyUsage critical,nonRepudiation,digitalSignature,keyEncipherment
  CAEngineExtension extendedKeyUsage OID:1.3.6.1.5.5.7.3.2
  CAEngineExtension subjectKeyIdentifier hash
  CAEngineExtension authorityKeyIdentifier keyid,issuer
</IfModule>

# frontend configuration:
<IfModule mod_csr.c>
  <Location /csr>
    SetHandler csr
    # use subject from the certificate sign request unmodified
    CsrSubjectRequest *
  </Location>
</IfModule>

Hook Implementation Reference

The following backend hook implementations are provided by this module.

Engine Sign Request

Signs the certificate sign request using a key stored on an HSM or smartcard.

Both the CAEngineCertificate directive and the CAEngineKey directive are needed to enable the hook implementation. In addition, both the Make Serial Hook and the Get Time Hook are called to fill in the serial number and signing time for the certificate.

Each certificate is signed by default for 365 days. This can be controlled by the CAEngineDays directive. The CAEngineExtension directive allows certificate extensions to be added to the certificate.

Engine Get Certificate Authority

Returns the certificate authority certificate used to sign the request.

The certificate authority certificate is parsed from the CAEngineCertificate directive and returned when requested. This is the last certificate specified in the file.

Engine Get Next Certificate Authority

Returns the next certificate authority certificate that will be used to sign future requests.

The next certificate authority certificate is parsed from the CAEngineNextCertificate directive and returned when requested.

Engine Get Chain

Returns the chain of certificates used to sign the request.

The certificate chain is parsed from the CAEngineCertificate directive and returned when requested. These are all certificates apart from the last certificate specified in the file.

Directive Reference

CAEngineCertificate Directive

Description Filename of certificate chain: signing certificate first, CA certificate last.
Syntax CAEngineCertificate file
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the filename of the signing certificate, including the certificate chain: signing certificate first, CA certificate last.

CAEngineKey Directive

Description Set to the URI of the signing key on the smartcard or HSM.
Syntax CAEngineKey uri
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the URI of the signing key on the smartcard or HSM.

Examples of URIs include:


# backend configuration:
<IfModule mod_ca_engine.c>
  CAEngineKey "pkcs11:model=PKCS%2315;manufacturer=EnterSafe;serial=1234567890123456;token=User%20PIN%20%28My%20Token%29;object=Certificate"
</IfModule>

CAEngineNextCertificate Directive

Description Filename of the next CA certificate to follow this one, if any.
Syntax CAEngineNextCertificate file
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the filename of the next CA certificate to follow this one, if any.

CAEngineDays Directive

Description Set to the number of days the certificate must be signed for.
Syntax CAEngineDays days
Default CAEngineDays 365
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the number of days the certificate must be signed for.

Defaults to 365 days.

CAEngineExtension Directive

Description Certificate extension to add to the certificate when signed.
Syntax CAEngineExtension string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Certificate extension to add to the certificate when signed.

Examples of certificate extensions include:


# backend configuration:
<IfModule mod_ca_engine.c>
  CAEngineExtension basicConstraints CA:FALSE
  CAEngineExtension keyUsage critical,nonRepudiation,digitalSignature,keyEncipherment
  CAEngineExtension extendedKeyUsage OID:1.3.6.1.5.5.7.3.2
  CAEngineExtension subjectKeyIdentifier hash
  CAEngineExtension authorityKeyIdentifier keyid,issuer
</IfModule>

CAEngineDevice Directive

Description Name of the OpenSSL crypto engine to use.
Syntax CAEngineDevice string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Name of the OpenSSL crypto engine to use.

Examples of crypto engines include:


# backend configuration:
<IfModule mod_ca_engine.c>
  CAEngineDevice dynamic
</IfModule>

CAEnginePreCommand Directive

Description Commands to process before the engine is initialised.
Syntax CAEnginePreCommand string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Commands to process before the engine is initialised.

CAEnginePostCommand Directive

Description Commands to process after the engine is initialised.
Syntax CAEnginePostCommand string
Default none
Context server config, virtual host, directory, .htaccess
Status Backend
Module mod_ca_engine
Compatibility Introduced in mod_ca 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Commands to process after the engine is initialised.