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.

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

]]>
                

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.

                  
     Pkcs12SubjectRequest CN 1
     Pkcs12SubjectRequest OU 1
     Pkcs12SubjectSet O "Demo Services Ltd"
     Pkcs12SubjectSet L "Capital City"
     Pkcs12SubjectSet C "EU"

]]>
                

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

                  
	Name: 
	

	Department: 
	

	Temporary password: 
	

	


]]>
                

Or alternatively - a curl example is shown below.

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.

                  
    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"
  
]]>
                

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.

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".