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.

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.

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

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.

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.

The simplest case: issue a certificate to anybody who wants one. And we trust whatever values they want to have in the 'Subject' of the certificate.

                  
# backend configuration:

# Sign the certificates we ussue with this certificate.
# If needed - generate one for testing with:
#     openssl req -new -x509 -nodes \
#       -subj /CN=TheCA/O=Me/L=Here/C=EU \
#       -out    /etc/pki/tls/ca-cert.pem \
#       -keyout /etc/pki/tls/ca-key.pem
#
CASimpleCertificate /etc/pki/tls/ca-cert.pem
CASimpleKey         /etc/pki/tls/ca-key.pem

# use system clock as the time source
CASimpleTime on

# assign a random serial number
CASimpleSerialRandom on
  
# Specify the algorithm to use when
# generating a key; use:
# 
#    openssl list -public-key-algorithms 
# 
# to get a complete list of supported algorithms.
#
CASimpleAlgorithm RSA

Loglevel debug

<Location /pkcs12>
     SetHandler pkcs12
     # use subject from the certificate sign request unmodified, 
     # accept anything. Up to 99 'RDN' values in total.
     Pkcs12SubjectRequest * 99
</Location>

                

Now, from a governance perspective, one generally does not allow the user to specify everything.

So a more realistic Location block is shown below. Where one allows the user to specify the Common Name (CN) and the Organisational Unit (OU); but with the Organisation(O), Locality(L) and Country(C) to forced to an appropriate value.

                  
<Location /pkcs12>
     Pkcs12SubjectRequest CN 1
     Pkcs12SubjectRequest OU 1
     Pkcs12SubjectSet O "Demo Services Ltd"
     Pkcs12SubjectSet L "Capital City"
     Pkcs12SubjectSet C "EU"
</Location>

                

One would normally enage with this endpoint (/pkcs12) with a some javascript from the browser or as a simple form, such as for example:

                  
<form method=post action="/pkcs12">
	Name: <input name="subject-CN" value="Alice"/>
	<br/>
	Department: <input name="subject-OU" value="Vermin Handling Department"/>
	<br/>
	Temporary password: <input name="challenge" value="s3cr!t"/>
	<p/>
	<input type=submit value="generate"/><br/>
</form>

                

Or alternatively - a curl example is shown below.

                  
# Fetch a client certificate as a P12 for the user Alice (CN) 
# with an `Organisational Unit' specified as well. The other
# fields (Country(C), Locality(L), etc) are locked down servr
# side. Curl saves this to a file (client.p12):
# 
curl -o client.p12  -vvvv --silent  \
        --data-urlencode subject-CN=Alice  \
        --data-urlencode subject-OU="Vermin Handling"  \
        --data-urlencode challenge=s3cr1t \
        http://localhost:80/pkcs12

# Decode the PKCS12 file into a PEM cert/key; using the
# challenge to decrypt the outer package.
#
openssl pkcs12 -password pass:s3cr!t -nodes -nokeys -out client.pem

# And show what is in the PEM file:
#
openssl x509 -text -noout iin client.pem


                

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. We also set a more realistic set of CA extension values and limit the validity to 31 days. And rather than letting the user pick the CN with a subject-CN POST value - we force it to be identical to the value the user authenticated as.

                  
# backend configuration:
# 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

# Specify the algorithm to use when
# generating a key; use:
# 
#    openssl list -public-key-algorithms 
# 
# to get a complete list of supported algorithms.
#
CASimpleAlgorithm RSA 

# Typical extensions expected.
CASimpleExtension basicConstraints CA:FALSE
CASimpleExtension keyUsage critical,nonRepudiation,digitalSignature,keyEncipherment
CASimpleExtension subjectKeyIdentifier hash
CASimpleExtension authorityKeyIdentifier keyid,issuer

# See rfc5280 -- id-kp-clientAuth
CASimpleExtension extendedKeyUsage OID:1.3.6.1.5.5.7.3.2

CASimpleDays 31

# frontend configuration:
  <Location /pkcs12>
    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"
  </Location>

                

After calling the request authorization hook, the make key hook, the sign request hook, and the certificate storage hook, return the DER or PEM encoded certificate.

SetHandler pkcs12

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

Set the name of the form parameter containing the challenge.

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

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

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.

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.

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.

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.

Set to the number of iterations. Defaults to 2048.

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

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

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

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