OCSP adapter

The OCSP-Adapter allows TrustBuilder to validate X509-certificates against a third-party OCSP-provider. A valid OCSP-response is returned by the adapter if:

The certificate's issuer is found in the trust store
The OCSP-provider must approve the certificate serial number / certificate issuer combination.

In addition, the adapter provides options to validate the time of the approval.

Prerequisites

TrustStore

A truststore containing the certificates issuers must be created - reference to topic describing how to create a keystore> + put keystore in TB_HOME or refer from workflow settings

HTTP-adapter

The OcspAdapter uses an instance of the HttpAdapter to access the OCSP-provider. Please refer to HTTP-adapter chapter for creating an instance of the HTTP-adapter.

Configuration

Parameter	Description	Required
AdapterUniqueID	Unique name assigned to this adapter; the name is used to reference the adapter in the workflow. The ID has following requirements: START with a letter or _ (underscore) FOLLOWED by a combination of following characters: Letter, Number, '.' (dot), '-' (dash), '_' (underscore)	x
HTTPAdapter	Unique ID of the HTTP-adapter which is used for communication with the third-party OCSP-responder; the HTTP-adapter must be created as a prerequisite to this OCSP-adapter.	x
ClockSkew	When the OCSP-provider returns a response, it also includes some timing information. The ClockSkew parameter defines the number of seconds the response time may differ from the local time in order to be accepted as a valid OCSP-response. This parameter will always be checked and must be an integer number greater than or equal to zero.	x
MaximumAge	While the response may have been valid at some point in time, this may no longer be the case.The MaximumAge parameter specifies the tolerance in seconds on the validity time of the response.A response whose last known validity time precedes the current time minus this parameter will be considered invalid.If the parameter is set to -1, this validation step is skipped.	x
OnlyUseHTTPAdapterServer	This paramters defines whether or not to use the host parameter of the HttpAdapter instead of the OCSP url defined in the certificate

Workflow Settings

A request for the adapter is prepared by specifying the following properties/scripts in the adapter activity:

Input Property: the variable containing the instructions the adapter have to execute
Output Property: the variable the adapter will store the response in after execution
Before Adapter Script: script that will be executed before calling the adapter
After Adapter Script: script that will be executed after the adapter fulfilled its task

Request - API

ocspRequest

Creates an OCSP validation request for validation against a third-party OCSP-responder.

CODE

workItem.ocspInput = tb.ocspRequest(base64ClientCert [, base64IntermediateCert],[ocspEndpoint]);

with parameters:

base64ClientCert: Non-null, non-empty string; encoded in base64-format (may contain -CERTIFICATE- and -END CERTIFICATE- delimiters)
base64IntermediateCert: string; encoded in base64-format. The public certificate for Intermediate CA of the certificate you want to validate (optional)
ocspEndpoint: string; Endpoint to send the call to (optional)

Example: A valid base64-encoded certificateID can be obtained from an ocspEndpointRequest.getCertificate(index)

Response - API

Common Properties

The response API can be applied to the variable specified in the output property (see Workflow Settings): to verify whether the action performed by the adapter was successful, to query for the data returned by the adapter.

All responses have four properties in common:

status Status flag indicating whether the response is ok (0) or not (1).
substatus Response specific number indicating what the problem was, eg. http status code
message Response specific message in case there was a problem (can be null)
rc Return Code, a human readable code based on the substatus

The status flag indicates whether a request was valid yes or no: status equals 0: OCSP-response indicates that the certificate is valid status equals 1: OCSP-response indicates that the certificate is invalid

Consequently, the message or return code (rc) can be used to give the end-user a reasonable explanation or send the information to the underlying logging system.

Adapter Specific Properties

The only supplementary information that can be gathered through the response-API is:

thisUpdate

This is the time where the status is known to be correct. A responder may not hold its information continuously updated. It may at time intervals retrieve updated status information from relevant CRLs.

nextUpdate

This is the time where the responder will retrieve updated status information If this component is not present, it indicates that the responder always holds up-to-date status information.

revocationTime

This returns the epoch when the certificate was revoked according to the ocsp server. Or 0 when not provided or ok.

revocationReason

This returns the reason why the certificate was revoked according to the ocsp server. Or 0 when not provided or ok.

Response Codes

If all is ok, the status is zero, for non-zero statusses, the substatus defines what is wrong.

1 OCSP malformed
2 OCSP Internal error
3 OCSP Try later
4 No AKI
5 Certificate Error
6 Invalid AKI
7 OCSP Signature required
8 OCSP error
9 Signer certificate not found
10 OCSP Unauth requuired
11 Keystore error
12 OCSP Revoked
13 OCSP Unknown
100 Invalid HTTP Adapter
101 Invalid HTTP Response
102 Response not yet valid
103 Response too old
104 Response expired
105 Response invalid update times
200 HTTP no error

Example

The Certificates can be extracted with the certificate adapter. See the certificate adapter for more information about extracting the base64 certificates

Request

CODE

function createOcspRequest(workItem){
    var value = workItem.subInput.value;
    var certificate = value.certificateString; // base64
    var certificateObject = value.certificate; // base64
    workItem.policy = value.policy;
    workItem.subjectDN = certificateObject.subject;
    var citizen_cert = value.getSigner().getCertificate(); // base64
    workItem.ocspInput = tb.ocspRequest(certificate, citizen_cert);
}

Response

CODE

//in this function we process the response from OCSP
//an error is thrown accordingly
function processOcspResponse(workItem){
    var ocspResponse = workItem.ocspOutput;
    tb.log(JSON.stringify(ocspResponse));

    var status = ocspResponse.status;
    var subStatus = ocspResponse.substatus;

    if (status === 0) {
        workItem.responseObject.errorCode = 0;
        tb.log("OcspAfter: Certificate appeared to be valid!");
        return;
    } else {
        workItem.responseObject.errorCode = 5;
        switch (subStatus) {
           case 1:
            tb.log("OcspAfter: OCSP malformed");
           break;
           case 2:
            tb.log("OcspAfter: OCSP Internal error");
           break;
           case 3:
            tb.log("OcspAfter: OCSP Try later");
           break;
           case 4:
            tb.log("OcspAfter: No AKI");
           break;
           case 5:
            tb.log("OcspAfter: Certificate Error");
           break;
           case 6:
            tb.log("OcspAfter: Invalid AKI");
           break;
           case 7:
            tb.log("OcspAfter: OCSP Signature required");
           break;
           case 8:
            tb.log("OcspAfter: OCSP error");
           break;
           case 9:
            tb.log("OcspAfter: Signer certificate not found");
           break;
           case 10:
            tb.log("OcspAfter: OCSP Unauth requuired");
           break;
           case 11:
            tb.log("OcspAfter: Keystore error");
           break;
           case 12:
            tb.log("OcspAfter: OCSP Revoked");
           break;
           case 13:
            tb.log("OcspAfter: OCSP Unknown");
           break;
           case 100:
            tb.log("OcspAfter: Invalid HTTP Adapter");
           break;
           case 101:
            tb.log("OcspAfter: Invalid HTTP Response");
           break;
           case 102:
            tb.log("OcspAfter: Response not yet valid");
           break;
           case 103:
            tb.log("OcspAfter: Response too old");
           break;
           case 104:
            tb.log("OcspAfter: Response expired");
           break;
           case 105:
            tb.log("OcspAfter: Response invalid update times");
           break;
           case 200:
            tb.log("OcspAfter: HTTP no error");
           break;
        }
    }
}