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
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:
|
getPublicKeyInfo() | Object containing following properties
|
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
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;
}