Certificate request verifications in Protocol Gateway

This article is valid for Certificate Manager 8.5 and later.

This article describes how to use certificate context and modules to verify the content of certificate requests in Protocol Gateway.

Protocol Gateway uses a subset of the certificate format files and modifiers in Certificate Factory (CF). For more information, see the section Certificate Formats in the Certificate Manager Technical Description.

Certificate context

Before sending certificate requests from Protocol Gateway to Certificate Factory (CF), the context is not only one certificate context, but a general context that contains certificate contexts. The context contains a list of certificate requests and also a common context, which in turn are the same as certificate contexts on CF. The values from the common context are copied to all certificate requests if they should be missing any information present in the common context.

The following certificate request contexts can be used for verifications in Protocol Gateway:

certrequests

certrequests is a list of requests.

For example, to get commonname.value of a certificate request, specify the nested certificate context with the following syntax, where <index> specifies the certificate request number:

Example: certrequest syntax

CODE

certrequests:<index>:commonname.value

commoncontext

For example, to get the commonname.value of the common context, use the following syntax:

Example: commoncontext syntax

CODE

commoncontext:commonname.value

Available modules

Each handler in a <protocol>.properties file may define attributes in the same way as in a format. Below are examples of how to set up modifiers, by using the formatFields function of a handler in a .properties file.

Currently, the following general modules are available in the Protocol Gateway formats and they are run in the following order:

CertificateReader

CertificateReader is a module unique to Protocol Gateway. Its function is to extract the client certificate used to authenticate to Protocol Gateway. It supports certificates from client TLS through Tomcat, or the signing certificate in a CMP request.

It extracts information from the certificate into the context, and this information can then be used with FieldComposer, FieldOperator and RequestVerifier to manipulate and verify the information.

Syntax

CODE

CertificateReader.Source = <source>
CertificateReader.Attribute.<index> = <attribute>

Value: CMP | TLS

If CMP is entered, the signing certificate of the CMP request is used.

If TLS is entered, the client certificate used to authenticate to Protocol Gateway is used.

<index>

A unique identifier for an attribute to extract, starting with 0.

If issuer. is prepended to the attribute, it means that it will try to get the attribute from the signing certificate's issuer's Subject.

The name to extract from the certificate, specified with FieldOperator syntax.

If san. is prepended to the attribute, it means that it will try to get the attribute from the SubjectAlternativeName of the certificate.

The attributes will be placed in .value of the same index after extraction from the certificate, e.g. CertificateReader.attribute.<index>.value.

Example

This example shows how to use CertificateReader in a <protocol>.properties file:

Example: CertificateReader in <protocol>.properties file

CODE

; Read the common name from the TLS client certificate with CertificateReader
handler.x.formatFields.0 = CertificateReader.Source = TLS
handler.x.formatFields.1 = CertificateReader.Attribute.0 = commonname

FieldOperator

The FieldOperator modifier is a general utility module for simple manipulation of fields in the
Certificate context.

This example shows how to use FieldOperator in a <protocol>.properties file:

Example: FieldOperator in <protocol>.properties file

CODE

; Copy the extracted common name to the common name
; of the certificate request with FieldOperator
handler.x.formatFields.2 = FieldOperator.a.copy = CertificateReader.Attribute.0.value, certrequests:0:commonname.value, overwrite

; Remove any periods in the common name with FieldOperator
; using Regular Expressions
handler.x.formatFields.3 = FieldOperator.b.replace = certrequests:0:commonname.value, certrequests:0:commonname.value, \., overwrite

FieldComposer

The FieldComposer modifier is used to produce new or to replace existing Distinguished Name attributes from attributes present in the certificate request.

This example shows how to use FieldComposer in a <protocol>.properties file:

Example: FieldComposer in <protocol>.properties file

CODE

; Add @mycompany.my to the common name with FieldComposer
handler.x.formatFields.4 = FieldComposer.certrequests:0:commonname.replace = true
handler.x.formatFields.5 = FieldComposer.certrequests:0:commonname.rule = certrequests:0:commonname.value + "@mycompany.my"

handler.x.formatFields.6 = RequestVerifier.Rule.0 = MustMatch
handler.x.formatFields.7 = RequestVerifier.Rule.0.Attribute = commonname.value
handler.x.formatFields.8 = RequestVerifier.Rule.0.Regex = .+@mycompany\.my

RequestVerifier

The RequestVerifier modifier is a general utility that can deny requests according to a set of rules.

This example shows how to use RequestVerifier in a <protocol>.properties file:

Example: RequestVerifier in <protocol>.properties file

CODE

; Verify that the common name looks as desired with RequestVerifier.
; Note that RequestVerifier verifies all certificate requests this way,
; if multiple were sent in to Protocol Gateway.
handler.<x>.formatFields.0 = RequestVerifier.Rule.0 = MustMatch
handler.<x>.formatFields.1 = RequestVerifier.Rule.0.attribute = commonname.value
handler.<x>.formatFields.2 = RequestVerifier.Rule.0.regex = .+@mycompany\.my

OcspCheckModifier

The purpose of the OcspCheckModifier is to perform an OCSP check for the issued certificate and to verify that the certificate status is not "non-issued" before moving on to the next modifier.

The modifier can be used when one wants to minimize the risk for clients to receive certificates with status "nonissued" ("Revoked" with reason "on hold") if they perform an OCSP check when receiving the certificate from CM. This modifier can be used in both PGW and CF.