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.

CODE

certificateRequest(base64Certificate)

with parameters:

CODE

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

serialnumber	Certificate serial number
signature	Signature
subject	Subject DN of the certificate
getAki()	Authority Key Identifier of the certificate
getIssuer()	Issuer DN of the certificate
getKeyUsage()	Object with boolean properties: digitalSignature nonRepudiation keyEncipherment dataEncipherment keyAgreement certificateSigning crlSigning enciphermentOnly deciphermentOnly
getPublicKeyInfo()	Object containing following properties algorithm encodedKey format type rsa (boolean) dsa (boolean)
getSki()	Signer Key Identifier of the certificate
getValidFrom()	Date from which the certificate is valid from
getValidTill()	Date till which the certificate is valid to
getVersion()	Version of this certificate
getCertificate()	Gets the certificate in a base64 format
getSigner()	Object containing the same functions as the certificate, but all of them apply on the signer's certificate

Response Codes

Status	Sub status	Description
0	0	OK
>0	1	Certificate not valid
	2	Certificate expired
	3	Certificate not yet valid
	4	No AKI or issuer
	5	Invalid AKI or issuer
	6	Signer certificate not found
	7	Keystore error
	8	Signature invalid
	9	Invalid Base64

Example

Request

CODE

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

CODE

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