Signed Public Key and Challenge Module

Generate and issue certificates using the SPKAC protocol.

What does it do?

This module implements a Signed Public Key and Challenge endpoint that is capable of signing and issuing certificates on behalf of a suitable client.

Based on configuration, parameters can be passed from optional form parameters, or explicit expressions, and a new certificate sign request with acceptable parameters is combined with the public key and the challenge from the SPKAC parameter and passed to suitably configured backend modules for request authorisation, certificate signing and issuing, and certificate storage.

This module can be configured to respond to SPKAC client requests as implemented by conformant implementations of HTML5.2 and earlier.

Module Integration

The mod_spkac module is a frontend module and will not do anything useful until mod_spkac has been combined with one or more backend modules listed below. The mod_spkac module uses the following hooks to authorise, sign/issue and store a certificate, and suitable backend modules must be configured to implement each hook as needed.

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

Request Authorization Hook

This optional hook allows you to verify the parameters included with the certificate sign request, such as the challenge password. If left unconfigured, all certificate requests will be accepted.

mod_ca_ldap Allows the certificate sign request to be verified against an LDAP directory.

Sign Request Hook

This hooks signs the certificate sign request and returns the issued certificate. The hook is mandatory, and the request will be rejected if left unconfigured.

mod_ca_disk Allows certificate sign requests to be saved to disk for later out of band processing. The response will redirect the caller to where the certificate can be collected.
mod_ca_engine Allows certificate sign requests to be signed by an HSM such as a smartcard.
mod_ca_simple Allows certificate sign requests to be signed by a certificate and key specified on disk.

Certificate Storage Hook

This optional hook allows the newly generated certificate to be stored locally or in a database or directory. If left unconfigured, no local copy of the certificate will be stored.

mod_ca_ldap Saves the newly issued PKCS7 certificate and chain to an LDAP directory.

Examples

Basic Example

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

                  
  # sign with this certificate...
  CASimpleCertificate /etc/pki/tls/ca-cert.pem
  # ...and private key
  CASimpleKey /etc/pki/tls/ca-key.pem
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on


# frontend configuration:

  
    SetHandler spkac
    # use subject from the certificate sign request unmodified
    SpkacSubjectRequest *
  

]]>

Logged In Example

A more typical scenario: issue a certificate to a logged in user.

In this example it is assumed that Apache configuration exists that authenticates a user against a database, directory, a token, or a previous certificate. 

                  
  # sign with this certificate...
  CASimpleCertificate /etc/pki/tls/ca-cert.pem
  # ...and private key
  CASimpleKey /etc/pki/tls/ca-key.pem
  # use system clock as the time source
  CASimpleTime on
  # assign a random serial number
  CASimpleSerialRandom on


# frontend configuration:

  
    SetHandler spkac
    # standard Apache authorisation
    Require valid-user
    # set the common name to the logged in username
    SpkacSubjectSet CN %{REMOTE_USER}
    # set a fixed OU field in the subject
    SpkacSubjectSet OU "Terms and Conditions Apply"
  

]]>

Handler Reference

The following parameters to the SetHandler directive are supported.

spkac Handler

After calling the request authorization hook, the sign request hook, and the certificate storage hook, return the DER encoded certificate.

Directive Reference

SpkacLocation Directive

Description Set the URL location of the WADL returned by the OPTIONS method.
Syntax SpkacLocation url
Default SpkacLocation [current-URL]
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set the URL location of the WADL returned by the OPTIONS method.

SpkacSize Directive

Description Set to the maximum size of the SPKAC request from the client.
Syntax SpkacSize bytes
Default SpkacSize 131072
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the maximum size of the SPKAC request from the client. This value cannot be smaller than 4096 bytes.

SpkacName Directive

Description Set to the form name of the SPKAC request from the client.
Syntax SpkacName string
Default SpkacName key
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of the form parameter containing the SPKAC request from the client.

SpkacSubjectAltNameRequest Directive

Description Specify fields in the form that will be copied over to the subject alternative name of the certificate.
Syntax SpkacSubjectAltNameRequest field [number]
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify fields in the form that will be copied over to the subject alternative name of the certificate, with optional limit to the number of fields that may appear.

Fields in the form are expected to be prefixed with the string subjectAltName- which will stripped before comparing to names set by this directive.

Field names are limited to otherName, rfc822Name, dNSName, x400Address, directoryName, ediPartyName, uniformResourceIdentifier, iPAddress, or registeredID and are described in the Subjects and Subject Alternative Names section.

SpkacSubjectAltNameSet Directive

Description Specify an expression that will be included in the certificate subject alternative name.
Syntax SpkacSubjectAltNameSet field value
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify an expression that will be included in the certificate subject alternative name.

Field names are limited to otherName, rfc822Name, dNSName, x400Address, directoryName, ediPartyName, uniformResourceIdentifier, iPAddress, or registeredID and are described in the Subjects and Subject Alternative Names section.

SpkacSubjectRequest Directive

Description Specify fields in the form that will be copied over to the certificate subject.
Syntax SpkacSubjectRequest field [number]
Default SpkacSubjectRequest field 1
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify fields in the form that will be copied over to the certificate subject, with optional limit to the number of fields that may appear.

Subject handling is covered in detail in the Subjects and Subject Alternative Names section.

SpkacSubjectSet Directive

Description Specify an expression that will be included in the certificate subject.
Syntax SpkacSubjectSet field value
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_spkac
Compatibility Introduced in mod_spkac 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify an expression that will be included in the certificate subject. Subject attribute name is configured first, then the expression.

Subject handling is covered in detail in the Subjects and Subject Alternative Names section.