ENTERPRISE EDITION This is an EJBCA Enterprise Edition (EE) feature.

Introduction

The Validation Tool is a standalone client-side application for certificates and OCSP responses validation and conformance checks.

The tool is used for running tests on issued certificates or OCSP responses to validate that they match the configured criteria. A typical use case is to, after setting up a functioning system, configure a set of checks to be run either periodically or after upgrades and configuration changes, to ensure the system is still functioning as expected. To perform validation during issuance, use the built in EJBCA Validators.

The Validation Tool is independent of the EJBCA version and the same tool can thus be used after an EJBCA upgrade.

The following sections cover building and running the tool, output Results, and information on the Validation Tool Command Line Interface.

For information on configuration, see Validation Tool Configuration and for a summary of the features, see Validation Tool Features.

Build

To build the tool and create a dist/validationtool directory, run the following:

ant validationtool

You may move the directory dist/validationtool to any location.

To provide online documentation for available ValidationTool commands and options, run the following::

bin/validationtool.sh

To create a source distribution and create a dist/validationtool-src directory, run the following:

ant validationtool-src

You may zip the directory and extract it in any location.

To build the Validation Tool, run the following in the modules/validationtool directory:

ant jar

Configure

For configuration examples, refer to the conf/sample1 folder containing sample OCSP and certificate checks configuration files. For more information, see Validation Tool Configuration.

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

Run

To run OCSP checks, run the following:

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, replace the managementca.crt with the issuer of your OCSP responder certificates, and change the DN:s and serial numbers in the configuration file to match your installation.

To run certificate checks, run the following:

bin/validationtool.sh certificate -conf conf/sample1/certchecks1.properties -certfolder ./certfolder

The tool waits for certificate files to be placed in the folder called certfolder. When a certificate file is detected, it is parsed and the configured certificate checks are executed. You need to configure certchecks1.properties with the tests that should be performed and their properties.

Results

Results are written after all configured checks are run for a query or certificate file. By default, the log is written to both standard output and a log file called validationtool.log. Log4j can be configured in conf/log4j.xml.

If the validation was successful and all checks for the current query or certificate file were successful, the results are logged with the INFO priority. Otherwise the ERROR priority is used.

For every check performed, an entry is written in the report beginning with the result of the check, either _SUCCESS{_}, _UNKNOWN_ or _FAILURE{_}. Success means that the check was successfully executed, and the expected result obtained. Unknown means that the test could not be executed for instance because a certificate was not included in the OCSP response etc. Failure means that the test was executed but the expected result was not obtained.

For successful checks, the name of the test and a short description is noted. For other results a more detailed description about what failed with the analyzed certificate or OCSP response is noted.

Example certificate validation output

2012-07-31 15:21:22,208 ERROR : Validation results for: 
          Configuration:                    certchecks1.properties
          Certificate file:                 timestamp2.pem
          Certificate serial:               0x5c04ced718526417
          Certificate issuer:               CN=ManagementCA,O=PrimeKey Solutions AB,C=SE
          Certificate subject:              CN=Signer 1,C=SE
          Certificate fingerprint (SHA1):   05a219d835622653192c30eeeee8f01f918b30fb
 
[SUCCESS] CertCheck_Signature_algorithmEquals
          Compares the signature algorithm
          Expected:  1.2.840.113549.1.1.5
          Actual:    1.2.840.113549.1.1.5
          Details:   
 
[SUCCESS] CertCheck_SubjectDNComponents_required
          Checks that sampled certificate contains the required DN fields
          Expected:  At least [O, CN]
          Actual:    [O, OU, CN]
          Details:   
 
[FAILURE] CertCheck_SubjectDNComponents_identical
          Compares the values of the DN components configured to be identical
          Expected:  the following to be identical [C, O]
          Actual:    was different [O]
          Details:   [[O=[PrimeKey Solutions AB], [Organization 1]]]
...

Example OCSP validation output

2012-08-06 12:16:59,887 ERROR : Validation results for: 
          Server URL:            http://localhost:8080/ejbca/publicweb/status/ocsp
          Configuration:         ocspchecks_myca1.properties
          CA:                    CN=MyCA1,O=EJBCA Support,C=SE
          Query serial number:   0x168794fbd471c7fc
          Expected signer:       CN=Signer 2,O=EJBCA Support,C=SE
          Expected status:       good
          Request file:          ./failfolder/request936843811890885123.orq
          Response file:         ./failfolder/response6475558795694330535.ors
 
[SUCCESS] OcspCheck_ExpectedSigner
          Outputs whether a response was received from the expected signer or not
          Expected:  Response from signer with subject DN: "CN=OCSP Signer 1,O=Organization A,C=SE"
          Actual:    Response from signer with subject DN: "CN=OCSP Signer 1,O=Organization A,C=SE"
          Details:   
 
[FAILURE] OcspCheck_ExpectedStatus
          Checks that the returned certificate status is the expected
          Expected:  good
          Actual:    unknown
          Details:   
 
[SUCCESS] OcspCheck_Response_time
          Checks that the response was returned within the configured max time
          Expected:  responseTime <= 500
          Actual:    responseTime = 61
          Details:   
 
...

Validation Tool Command Line Interface (CLI)

The Validation Tool Command Line Interface (CLI) has a ocsp and a certificate command with the following respective syntax.

ocsp

in/validationtool.sh ocsp
 
usage: ocsp [-url URL]... [-maxtries NUMBER] [-caconf CONFIGFILE]...
            [-failfolder FOLDER]
Run the OCSP healthcheck tool with the specifed CA configuration file(s)
 -caconf        CA configuration file. This option can be specified for
                every issuer to query.
 -failfolder    Folder to move requests and responses for which there were
                failures. If not specified, failures are not stored.
 -listchecks    Lists all the available checks and exists. No other
                options are required when using this.
 -maxtries      Maximum number of tries to perform before giving up
                getting a response from a particular responder.
 -url           URL of server to query. This option can be specified for
                every server to query.
 
Sample usages:
a) ocsp -listchecks
b) ocsp -url http://localhost:8080/ejbca/publicweb/status/ocsp -caconf
managementca.properties
c) ocsp -url http://server1/status/ocsp -url http://server2/status/ocsp
-maxtries 5 -caconf ocspchecks_managementca.properties -caconf
ocspchecks_authca1.properties
d) ocsp -url http://localhost:8080/ejbca/publicweb/status/ocsp -caconf
ocspchecks_managementca.properties -failfolder ./failfolder

Multiple OCSP responder URL:s and CA configuration files can be specified as arguments to the command. Each URL will be queried with all queries as configured in each CA configuration file. This means that each URL should answer responses with the signer subject DN:s as specified in the configuration. This might only be useful in some situation like when one wants to test different URL:s to the same responders. To query different responders on different URLs the command can instead be invoked multiple times with the different URLs and matching configuration files.

If a folder for failures is specified the requests and responses which had failures will be outputted there.

The maxtries option decides the maximum number of times each query is sent before giving up trying to get a response from the specified responder. Default value is 5.

certificate

bin/validationtool.sh certificate
 
usage: certificate -conf CONFFILE -certfolder FOLDERPATH [-minfileage
                   2000] [-waittime 1000] [-failfolder FOLDER]
The certificate validation application monitoring and checking all
certificates in the specified folder.
 -certfolder    Folder to watch for certificates.
 -conf          File name of the configuration file to use.
 -failfolder    Folder to move certificates to for which there were
                failures. If not specified the files are deleted.
 -listchecks    Lists all the available checks and exists. No other
                options are required when using this.
 -minfileage    Minimum number of milliseconds since the last modified
                time before a file is up for inspection. Specify this to make it less
                likely a file is being checked before it has been completely written to
                disk.
 -waittime      Time in milliseconds to wait before checking again if
                there were no files in the directory.
 
Sample usages:
a) certificate -listchecks
b) certificate -conf certchecks.properties -certfolder ./certfolder
c) certificate -conf certchecks.properties -certfolder ./certfolder
-minfileage 2000 -waittime 1000
d) certificate -conf certchecks.properties -certfolder ./certfolder
-failfolder ./failfolder

If a folder for failures is specified the certificates which had failures will be moved there.

Note that it is important to not run multiple instances of the tool at the same time on the same folder as the tool will remove the tested certificates.