Certificate

Certificate

Functionality

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

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

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;
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.