Building

In the validationtool folder run:

ant jar        

Configuring

The folder conf/sample1 contains sample OCSP checks and certificate checks configuration files that can be used as examples.

Configuration files are in Java Properties files format. The application expects ISO-8859-1 (latin1) encoding. Other characters can be escaped manually or by using a tool such as native2ascii.

Running

To run the OCSP checks issue:

bin/validationtool.sh ocsp -url http://localhost:8080/ejbca/publicweb/status/ocsp -caconf conf/sample1/ocspchecks_adminca.properties

This will query the OCSP responder for three different results (good, revoked and unknown) as configured in ocspchecks_adminca.properties. For the tests to succeed you will have to replace the managementca.crt with the issuer of your OCSP responder certificates as well as changing the DN:s and serial numbers in the configuration file to match your installation. For more details see later sections of the manual.

Certificate checks

The certificate check tool is run with one certificate checks configuration file. The file points out one template certificate to compare the certificates against as well as lists all checks to perform and their properties.

Sample cert check configuration:

template.file=template1.pem

checks=\
    CertCheck_Certificate_identical,\
    CertCheck_Signature_algorithmEquals,\
    CertCheck_SubjectDNComponents_required,\
    CertCheck_SubjectDNComponents_allowed,\
    CertCheck_IssuerDNComponents_specified,\
    CertCheck_ValidityNotAfter_minRemaining,\
    CertCheck_Extensions_identical

checks.CertCheck_Certificate_identical.dynamicfields=\
    serialNumber,\
    signature,\
    issuer,\
    validity,\
    subject,\
    subjectPublicKeyInfo,\
    extensions

checks.CertCheck_SubjectDNComponents_required.components=CN,O
checks.CertCheck_SubjectDNComponents_allowed.components=CN,O,L,ST,C

checks.CertCheck_IssuerDNComponents_specified.dnparts=O\=PrimeKey Solutions AB,C\=SE
checks.CertCheck_ValidityNotAfter_minRemaining.hours=24
checks.CertCheck_Extensions_identical.oids=\
    2.5.29.37,\
    2.5.29.14

Each check is listed in the "checks" property separated by a comma sign. Properties for the checks (if required) are added in properties of the form checks.CHECKNAME.PROPERTYNAME=VALUE where CHECKNAME is the name of the check as it is written in the checks list and PROPERTYNAME is the name of a property the check is expecting. Checks might require 0 or more properties. The tool will exit with an error message if not all required properties are specified.

OCSP checks

The OCSP check tool can be feed with one or more CA configuration files. Each CA configuration file represents one CA issuing OCSP responder certificates. It defines a set of queries to send to the OCSP responders as well as lists all checks to perform and their properties.

Sample OCPS checks CA configuration:

ca.issuercertificatefile=myca1.crt
ca.usenonce=true

ca.queries=revoked1,unknown1,good1
ca.queries.revoked1.serialnumber=0x70A81ED6E6339EDC
ca.queries.revoked1.expectedstatus=revoked
ca.queries.revoked1.signersubjectdn=CN\=OCSPSigner1 MyCA1,OU=The Unit,O=The organization,L=Stockholm,C=SE

ca.queries.unknown1.serialnumber=0x47114711
ca.queries.unknown1.expectedstatus=unknown
ca.queries.unknown1.signersubjectdn=CN\=OCSPSigner1 MyCA1,OU=The Unit,O=The organization,L=Stockholm,C=SE

ca.queries.good1.serialnumber=0x168794FBD471C7FC
ca.queries.good1.expectedstatus=good
ca.queries.good1.signersubjectdn=CN\=OCSPSigner1 MyCA1,OU=The Unit,O=The organization,L=Stockholm,C=SE

ca.checks=\
    OcspCheck_ExpectedSigner,\
    OcspCheck_ExpectedStatus,\
    OcspCheck_Response_time,\
    OcspCheck_Response_verify,\
    OcspCheck_Nonce,\
    OcspCheck_Extensions_required,\
    OcspCheck_Extensions_allowed,\
    OcspCheck_CertificateChain,\
    OcspCheck_SignerCertificate

ca.checks.OcspCheck_Response_time.maxtime=500
ca.checks.OcspCheck_SignerCertificate.includeconfigurationfile=certchecks1.properties
ca.checks.OcspCheck_Extensions_allowed.allowedoids=1.3.6.1.5.5.7.48.1.2
ca.checks.OcspCheck_Extensions_required.requiredoids=

This example defines three queries to send, one with each OCSP response status - good, revoked or unknown for different certificate serial numbers. The idea is to configure the queries to be for certificate which are known to have a particular status in the CA database. The OCSP responder (signer) subject DN for the expected responder answering the request is also configured. Only responses from the expected responder is further examined. This could be particular useful if running queries against a load balancer or a virtual IP (VIP) with multiple responders behind and one wants to be sure that each responder is tested.

The ca.usenonce property determines if a nonce should be included or not when sending the queries. Default is to send a nonce (ca.usenonce=true).

Notice in this example that the check called OcspCheck_SignerCertificate is using a certificate checks configuration file (as described in previous section) and will also run all checks configured in that one against the responder certificate.

Available checks

Expected:  Identical values for the fields: [version, serialNumber, issuer, validity, issuerUniqueID, subjectUniqueID]
Actual:    Different values for the fields: [serialNumber, issuer, validity]
Details:   
serialNumber expected: 0x7d982c66a57c3430
serialNumber   actual: 0x4d69e649072cc0d8
issuer expected: C=SE, O=EJBCA Sample, CN=ManagementCA
issuer    actual: C=SE, O=EJBCA Support, CN=MyCA1
validity expected: [Sat Jun 03 17:33:39 CEST 2006, Fri May 29 17:43:39 CEST 2026]
validity    actual: [Wed Jul 04 20:04:07 CEST 2012, Sat Jul 02 20:04:07 CEST 2022]

Expected:  At least [L, O, CN]
Actual:    [O, CN]
Details: 

Expected:  At least [L, O, CN]
Actual:    [O, CN]
Details: 

Expected:  Any number of [O, CN]
Actual:    [L, O, CN]
Details:  

Expected:  Any number of [O, CN]
Actual:    [L, O, CN]
Details:   

Expected:  the following to be as specified [C, O]
Actual:    was different [C, O]
Details:   [C=[SE],[NO], O=[PrimeKey],[CESeCore]]    

Expected:  the following to be as specified [C, O]
Actual:    was different [O]
Details:   [O=[PrimeKey],[CESeCore]]    

Expected:  the following to be identical [ST, C, L]
Actual:    was different [ST]
Details:   [ST=[Sweden],[Norway]]    

Expected:  the following to be identical [ST, C, L]
Actual:    was different [C]
Details:   [C=[SE],[NO]]

Expected:  the following components to be in the this order [CN, O, C]
Actual:    [C, O, CN]
Details:   [O was not supposed to be before C]

Expected:  the following components to be in the this order [CN, O, C]
Actual:    [C, CN, O]
Details:   [CN was not supposed to be before C]

Expected:  'notAfter' at least 4380 hours in future (earliest valid is 2013-02-14 00:13:11 UTC)
Actual:    4379 hours in future (2013-02-13 23:13:11 UTC)
Details:   Current time: 2012-08-15 12:13:11 UTC

Expected:  'notAfter' not more than 4380 hours in future (last valid is 2013-02-14 00:07:14 UTC)
Actual:    4381 hours in the future (2013-02-14 01:07:14 UTC)
Details:   Current time: 2012-08-15 12:07:14 UTC

Expected:  not more than 4380 minutes from now
Actual:    -5000 minutes
Details:   
Current time: 2012-08-10 07:09:03 UTC
notBefore:    2012-08-13 18:29:03 UTC

Expected:  bitLength=1024
Actual:    bitLength=2048
Details:   

Expected:  EC
Actual:    RSA
Details:   

Expected:  1.2.840.113549.1.1.5
Actual:    1.2.840.113549.1.1.11
Details:   

Expected:  [2.5.29.19]
Actual:    [2.5.29.15, 2.5.29.19]
Details:

Expected:  [2.5.29.19]
Actual:    [2.5.29.15]
Details:   

Expected:  Identical values for [2.5.29.37, 2.5.29.19]
Actual:    Different values for [2.5.29.37]
Details:   

Expected:  Response from signer with subject DN: "CN=OCSPSigner1 MyCA1,OU=The Unit,O=The organization,L=Stockholm,C=SE"
Actual:    Got 3 responses from other responders: [CN=MyCA1,O=EJBCA Support,C=SE, CN=MyCA1,O=EJBCA Support,C=SE, 
           CN=MyCA1,O=EJBCA Support,C=SE]
           Got 2 query errors: [Connection refused, Connection refused]
Details:   

Expected:  All configured certificate checks to succeed
Actual:    At least one certificate check failed
Details:   See the individual checks for details.

Expected:  Valid certificate chain
Actual:    Verification error
Details:   Signature does not match.
Certificate to be verified: CN=Sub sub CA 1
Issuer certificate: CN=Responder Sub CA 1
Complete chain:
   0: 0x76782bc186c29f0e CN=Sub sub CA 1 issued by CN=Sub CA 1
   1: 0x392407a31a050b2 CN=Responder Sub CA 1 issued by CN=Root CA 1
   2: 0x1cbb40cd1664b95e CN=Root CA 1 issued by CN=Root CA 1

Expected:  revoked
Actual:    unknown
Details:       

Expected:  Same nonce in response as in request
Actual:    No nonce in response
Details:   

Expected:  consistent signature
Actual:    inconsistent signature
Details:   the signature did not be verified correctly

Expected:  responseTime <= 5000
Actual:    responseTime = 6137
Details: 

Expected:  [1.3.6.1.5.5.7.48.1.6, 1.3.6.1.5.5.7.48.1.2]
Actual:    [1.3.6.1.5.5.7.48.1.2]
Details:  

Expected:  Any of [1.3.6.1.5.5.7.48.1.2]
Actual:    [1.3.6.1.5.5.7.48.1.2, 1.3.6.1.5.5.7.48.1.6]
Details:   

General

• The tool is independent of EJBCA version.
• Configuration properties are validated before the testing starts.

OCSP Specific

• The OCSP command works as a real OCSP client sending requests to the configured OCSP responder(s).
• The OCSP client can query multiple servers by specifying multiple "url" arguments at the command line. In addition if multiple responders are behind an load balancer or VIP the queries in the CA configuration files can be configured to look for responses from specific responders by specifying the signer certificate subject DN. Then only responses from that responder will be considered.
• The maximum number of tries to perform to get a response for a query from a particular responder is configurable at the command line by specifying the maxtries argument.
• Querying for multiple CAs on each server by supplying multiple CA configuration files. New files can easily be created and supplied at the command line when invoking the tool.
• Querying one OK, one revoked and one unknown certificate, as configured, from each CA by specifying multiple queries in the CA configuration file with different expected status for different certificates. The check OcspCheck_ExpectedStatus verifies that the status is the expected and OcspCheck_ExpectedSigner outputs if a response was received from the expected responder.
• Verifying that the returned certificate chain in the OCSP response is good by adding the check called OcspCheck_CertificateChain.
  A basic certificate chain check is performed with the configured issuer certificate as trust anchor. More complex chains or chains where the responder certificate is not signed by the configured issuer might fail.
• Verifying that the returned OCSP response verifies by adding the check called OcspCheck_Response_verify.
• Verifying that the OCSP response is returned timely (configurable max time) by adding the check called OcspCheck_Response_time.
• Verifying the nonce if configured to use one by adding the check called OcspCheck_Nonce.
• Verifying that the right extensions are used by adding the checks called OcspCheck_Extensions_required and OcspCheck_Extensions_allowed.
• The signer certificate can be validated with the same set of checks and configuration as with the certificate checks tool by adding the check called OcspCheck_SignerCertificate and configure it with the name of a certificate checks configuration file.

Certificate Specific

• The tool is configured with a configuration file pointing out a template certificate that can be used by the different checks to compare the certificates against. The configuration file also contains details about which checks to perform.
• Certificates could be exported from EJBCA to the configured certificate folder for instance using a publisher.
• Verifying that the sampled certificates are identical to the template certificate (except for dynamic values) by adding the check called CertCheck_Certificate_identical.
• Verifying that the sampled certificates contains issuer and subject DN components that are configured to be required by adding the checks called CertCheck_SubjectDNComponents_required and CertCheck_IssuerDNComponents_required.
• Verifying that the sampled certificates does not contain other DN components than required or optional by by adding the checks called CertCheck_SubjectDNComponents_allowed and CertCheck_IssuerDNComponents_allowed and configure it with the list of allowed DN components, that is both the required and optional ones.
• Verifying that the certificate contains the specified values for DN components that must be the same, i.e. O=PrimeKey,C=SE, by adding the checks called CertCheck_SubjectDNComponents_specified and CertCheck_IssuerDNComponents_specified and specify the DN parts or add the checks CertCheck_SubjectDNComponents_identical and CertCheck_IssuerDNComponents_identical to required the values of the specified DN components to be identical to those in the template certificate.
• Verifying that the validity end date is at least a configurable number of hours in the future by adding the check called CertCheck_ValidityNotAfter_minRemaining.
• Verifying that the validity end date is not more than a configurable number of hours in the future by adding the check called CertCheck_ValidityNotAfter_maxRemaining.
• Verifying that the validity start date is not more than a configurable number of minutes from now by adding the check called CertCheck_ValidityNotBefore_maxDiffFromNow.
• Verifying that the public key specification (ie. key length for RSA) is the same as in the template by adding the check called CertCheck_PublicKey_sizeEquals.
• Verifying that the public key algorithm is the same as in the template by adding the check called CertCheck_PublicKey_algorithmEquals.
• Verifying that the signature algorithm is the same as in the template by adding the check called CertCheck_Signature_algorithmEquals.
• Verifying that the same extensions are used in the certificate as in the template and that they have the same criticality but not necessarily the same value by adding the checks called CertCheck_Extensions_criticalOIDs and CertCheck_Extensions_nonCriticalOIDs
• Verifying the extensions that are configured to be identical by adding the check CertCheck_Extensions_identical which compares the DER encoded values of the extensions in the certificate with those in the template.
• Verifying that the subject and issuer DN are in the correct order by adding the checks called SubjectDNOrder_specified and IssuerDNOrder_specified and specify the order of the DN components.
• The tool runs as long as there are certificate files in the configured directory. When a file is analyzed, then the output is written to log files and the analyzed file is deleted. When there are no more certificate files in the configured directory, the application sleeps for a while (as configured) before checking if there are some more certificates to validate.
• To make it less likely a certificate file is being analyzed before it has been completely written to disk new files will not be read until their last modified time is more than configured time in the past (for instance 2 seconds).