Skip to main content
Skip table of contents

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.