Certificate adapter

The CertificateAdapter allows TrustBuilder to validate X509-certificates based on their validity periods and a trusted store of signer certificates. In order to be valid: * the certificate's period must be valid * the signer must be found in the trust store and the certificate's signature must comply with the signer's public key.

Prerequisites

TrustStore

In order to validate the certificate a truststore is required (if one isn't provided fallback is done on the keystore) For more information about creating and/or using key- and truststores in trustbuilder refer to the KeyStore and TrustStore chapter.

Configuration

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)

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

certificateRequest The CertificateRequest allows clients check the X509 certificate's validity period and to validate its signature using a signer's public key.

certificateRequest(base64Certificate) 

with parameters:

base64Certificate: Non-null, non-empty string; encoded in base64-format (may contain "-CERTIFICATE-" and "-END CERTIFICATE-" delimiters) 

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; 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

Response Codes

Example

Request

function createCertificateRequest(workItem){
    //workItem.certificate contains the base64 certificate request obtained through a header of direct as parameter
    workItem.certrequest = tb.certificateRequest(workItem.certificate);
}

Response

function handleResponse(workItem){
    if(certresponse.status == 0){
        tb.log("Certificate is valid.");
        return 'true';
    }
    return false;
}