PKCS12 Module

Generate public/private key pairs and and issue certificates in response to a application/x-www-form-urlencoded form request.

What does it do?

This module accepts a application/x-www-form-urlencoded form submission request containing optional parameters.

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

The resulting certificate chain and private key is returned as a DER encoded PKCS12 certificate and key.

Module Integration

The mod_pkcs12 module is a frontend module and will not do anything useful until mod_pkcs12 has been combined with one or more backend modules listed below. The mod_pkcs12 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.

Make Key Hook

This hook generates a public/private key pair. The hook is mandatory, and the request will be rejected if left unconfigured.

mod_ca_simple Generates a public/private key.

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 pkcs12
    # use subject from the certificate sign request unmodified
    Pkcs12SubjectRequest *
  

]]>

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 pkcs12
    # standard Apache authorisation
    Require valid-user
    # set the common name to the logged in username
    Pkcs12SubjectSet CN %{REMOTE_USER}
    # set a fixed OU field in the subject
    Pkcs12SubjectSet OU "Terms and Conditions Apply"
  

]]>

Directive Reference

Pkcs12Size Directive

Description Set to the maximum size of the form submitted by the client.
Syntax Pkcs12Size bytes
Default Pkcs12Size 131072
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

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

Pkcs12ParamChallenge Directive

Description Set the name of the form parameter containing the challenge.
Syntax Pkcs12ParamChallenge param
Default Pkcs12ParamChallenge challenge
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set the name of the form parameter containing the challenge.

Pkcs12ParamNickname Directive

Description Set to the name of the request variable from the client containing the certificate nickname..
Syntax Pkcs12ParamNickname param
Default Pkcs12ParamNickname challenge
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the name of the request variable from the client containing the certificate nickname. Overrides the Pkcs12Nickname directive.

Pkcs12Location Directive

Description Set the URL location of the WADL returned by the OPTIONS method.
Syntax Pkcs12Location url
Default Pkcs12Location [current-URL]
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 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.

Pkcs12SubjectAltNameRequest Directive

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

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

If a wildcard is used, all fields in the certificate request subject alternative name will be copied across unmodified.

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.

Pkcs12SubjectAltNameSet Directive

Description Specify an expression that will be included in the certificate subject alternative name.
Syntax Pkcs12SubjectAltNameSet field value
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 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.

Pkcs12SubjectRequest Directive

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

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

If a wildcard is used, all fields in the certificate request subject alternative name will be copied across unmodified.

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

Pkcs12SubjectSet Directive

Description Specify an expression that will be included in the certificate subject.
Syntax PkcsSubjectSet field value
Default None
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 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.

Pkcs12Iterate Directive

Description Set to the number of iterations.
Syntax Pkcs12Iterate iterations
Default Pkcs12Iterate 2048
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the number of iterations. Defaults to 2048.

Pkcs12Digest Directive

Description Set to the mac digest used on the PKCS12.
Syntax Pkcs12Digest digest
Default Pkcs12Digest SHA256
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to the mac digest used on the PKCS12. Defaults to SHA256.

Pkcs12CertificatePBE Directive

Description Specify the certificate PBE algorithm.
Syntax Pkcs12CertificatePBE algorithm
Default Pkcs12CertificatePBE PBE-SHA1-3DES
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify the certificate PBE algorithm. Defaults to PBE-SHA1-3DES.

Pkcs12KeyPBE Directive

Description Specify the key PBE algorithm.
Syntax Pkcs12KeyPBE algorithm
Default Pkcs12KeyPBE PBE-SHA1-3DES
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Specify the key PBE algorithm. Defaults to PBE-SHA1-3DES.

Pkcs12Nickname Directive

Description Set to an expression that resolves to the nickname of the certificate.
Syntax Pkcs12Nickname name
Default Pkcs12Nickname certificate
Context server config, virtual host, directory, .htaccess
Status Frontend
Module mod_pkcs12
Compatibility Introduced in mod_pkcs12 0.2.0 and works with Apache HTTP Server 2.4.0 and later

Set to an expression that resolves to the nickname of the certificate. Defaults to "certificate".