Usage and Integration

Input Parameters

Debbie receives the requests as a POST request over an HTTP / HTTPS connection. Depending on the type of document and signature you have to process, the parameters you should receive are the following:

Field	Required	Description
signatureType	yes	Type of signature to be validated CAdES: (CMS Advanced Signature) CAdES format. CAdES-Multiple: Same as CAdES for multiple signers. CAdES-Implicit^: CAdES with data embedded. CAdES-Explicit^:* CAdES without signed data inside. XAdES-Enveloped^: XAdES. XAdES-Detached^: XAdES. PAdES: (PDF Advanced Signature) PAdES format. P7B or X509: (certificate) Validate only the certificate PKCS1: for PKCS#1 signatures. In this case certificate parameter is required.
signedText	yes	Signed text
signedTextPack	BASE64-<encode>	If present, it indicates that the signed text is in Base64 format. It also used to indicate the character set used by the signed text, because the signing tool used can set different char-set. Example: BASE64-ISO-8859-1
signature	yes	Signature, base64 format.
certificate	depending on signatureType	Certificate, base64 format.
algorithm	only for PKCS1	PKCS1 signature, base64 format.
pdfFile	only for PAdES	PDF file attachment to use with PAdES (form-data) validation requests.
pdfFilename	only for PAdES	PDF filename to use with PAdES (x-www-form-urlencoded) validation requests.
pdfPassword	only for PAdES	For password-protected PDF documents.

Note

^* Not yet implemented.

^**Same as CAdES.

Sample Output

Common response with an HTTP 200 response code. Any other response must be considered as an error.

{
	"version": "2.2.3",
	"opResult": {
    	"resultStatus": 2,
    	"resultList": [
      		{
        		"code": 30018
      		}
    	]
  	},
  	"policy": {
    	"resultStatus": 2,
    	"name": “digicert”,
    	“version”: “1.0.0”,
    	“date”: “2016-09-12T18:34:23Z”,
		"certificate”: {
      		"level": 1,
      		"resultStatus": 2,
      		"resultList": [
        		{
          			"code": 30071,
          			“detail”: “serial:20332452340;”
        		}
      		]
    	}
    	"signature": {
      		"type": "CAdES",
      		"resultStatus": 2,
      		"resultList": [
        		{
          			"code": 30018
        		}
      		]
    	}
  	},
  	"signers": [
    	{
      		"serialNumber": "87931315209220339004858855189940763179",
      		"serialNumberH": "4226f48e9c8c3d25e431ed0d9d5b7a2b",
      		"thumbPrint": "4e373939053809742beb373bfdb2ee2471a217f7",
      		"notBeforeS": "2004-03-02 00:00:00 UTC",
      		"notAfterS": "2036-07-16 23:59:59 UTC",
      		"daysToExpire": 7202,
      		"notBeforeTS": 1078185600,
      		"notAfterTS": 2099865599,
      		"isDefault": false,
      		"status": 0,
      		"trustLevel": 1,
      		"validationMode": 2,
      		"subject": {
        		"DN": "CN=VeriSign Class 2 TEST Public Primary Certification Authority-G3, OU=For Test Purposes Only, OU=Terms of use at https:\/\/www.verisign.com\/cps\/testca (c)04, OU=VeriSign Trust Network, O=\"VeriSign, Inc.\", C=US",
        		"parsedDN": {
          			"C": "US",
          			"O": "VeriSign, Inc.",
          			"CN": "VeriSign Class 2 TEST Public Primary Certification Authority-G3",
          			"OU": {
            			"OU0": "VeriSign Trust Network",
            			"OU1": "Terms of use at https:\/\/www.verisign.com\/cps\/testca (c)04",
            			"OU2": "For Test Purposes Only"
          			}
        		}
      		},
      		"issuer": {
        		"DN": "CN= VeriSign Class 2 Public Primary Certification Authority, OU=For Test Purposes Only, OU=Terms of use at https:\/\/www.verisign.com\/cps\/testca (c)04, OU=VeriSign Trust Network, O=\"VeriSign, Inc.\", C=US",
        		"parsedDN": {
          			"C": "US",
          			"O": "VeriSign, Inc.",
          			"CN": "VeriSign Class 2 Public Primary Certification Authority",
          			"OU": {
            			"OU0": "VeriSign Trust Network",
            			"OU1": "Terms of use at https:\/\/www.verisign.com\/cps\/testca (c)04",
            			"OU2": "For Test Purposes Only"
          			}
        		}
      		},
      		"subjectAltNames": { }
    	}
  	]
}

Segments of response

A common response is composed of several segments, included in the same JSON file.

Some segments only when validating some kind of documents or signatures.

General result

This general response has information about the total status of the validation process. This value is related to the execution of the process, not about the document or certificate validated,

{
	"version": "2.0.0",
	"opResult": {
   		"resultStatus": 2,
    	"resultList": [
      		{
        		"code": 30018,
				“detail”: “description_detail” 
      		}
    	]
	}
}

Fields

Field	Format	Description
version	X.Y.Z	Debbie process version used to validate.
opResult	0, 1, 2	Overall validation result status.

Possible values are as follows:

Status	Value	Description
SUCCESS	0	No error
WARNING	1	The procedure finished, but a warning condition happened. Some warning conditions can be: CRL can't be downloaded, but current downloaded CRL is still valid.
ERROR	2	Validation is incorrect.

If resultStatus is ERROR or WARNING, a list of (code, detail) is included in resultList.

These codes have a detailed error code and detail, which can be used for a better diagnostic. Detailed description can contain information about the certificate with the problem, or a description of the CRL that couldn't be downloaded.

Policy

This information summarizes the result of the validation process. Based on the validation request, the response can include the validation of:

certificates
signatures

The final resultStatus is the worst value (highest) of all the validations.

Policy Result

{
	"policy": {
    	"resultStatus": 2,
    	“name”: “digicert”,
    	“version”: “0.9.1”,
    	“date”: "2019-08-15T20:59:29Z",
    	“certificate”: ... , <defined below>
    	“signature”: ... <defined below>
	}
}

Field	Description
name	Name of the policy.
version	Policy version, as defined in the configuration file.

Signature

This structure is defined within the policy the response, and is used to describe the signature validation result.

It is present when the signature related information has been found on the document.

In addition to the resultStatus and resultList values found within it, the processed signature structure type (ie CAdES, XAdES, etc) is also defined.

Signature Result

{
    "signature": {
    "type": "CAdES",
    "resultStatus": 2,
    "resultList": [
		{
        	"code": 30018
		}
    ]
}

Certificate / Signer

This structure is defined within the policy response, and is used to describe the certificate validation result against the validation level required.

The level field represents the required validation level for certificates

The content of this field is a structure of one or more WebCertificate. The identifier “signers” or “certificates” depends on whether a signature or only a certificate has been sent to validate.

This structure is present when one or more elements of type certificate have been detected in the sent document.

If no signer is found then this structure is not included in the response and the *opResult includes the corresponding error.

This array of "certificates" has a structure for each of them called webCertificate detail below:

WebCertificate

{
	"serialNumber": "87931315209220339004858855189940763179",
	"serialNumberH": "4226f48e9c8c3d25e431ed0d9d5b7a2b",
	"thumbPrint": "4e373939053809742beb373bfdb2ee2471a217f7",
	"notBeforeS": "2019-03-02 00:00:00 UTC",
	"notAfterS": "2020-03-02 23:59:59 UTC",
	"daysToExpire": 39,
	"notBeforeTS": 1078185600,
	"notAfterTS": 2099865599,
	"isDefault": false,
	"status": 0,
	"trustLevel": 1,
	"validationMode": 2,
	"subject": {
		"DN": "CN=Jorge Perez Garcia, OU=Terms of use at www.certisur.com, OU=CertiSur Trust Network, O=CertiSur S.A.., C=AR",
        "parsedDN": {
			"C": "AR",
          	"O": "CertiSur S.A.",
          	"CN": "Jorge Perez Garcia",
          	"OU": {
            	"OU0": "CertiSur Trust Network"
            	"OU1": "Terms of use at www.certisur.com",
          	}
		}
	},
    "issuer": {
        "DN": "Root Certification Authority, OU=CertiSur Trust Network, O="CertiSur S.A.\", C=AR",
        "parsedDN": {
			"C": "US",
          	"O": "VeriSign, Inc.",
          	"CN": "Root Certification Authority",
          	"OU": {
            	"OU0": "CertiSur Trust Network",
            	"OU1": "Terms of use at www.certisur.com",
          	}
        }
	},
    "subjectAltNames": {}
}

Field	Description
serialNumber	Certificate serial number represented in decimal format.
serialNumberH	Certificate serial number represented in hexadecimal format (Base16).
thumbPrint	Certificate thumbprint
notBeforeS / notBeforeTS	Certificate validity start date. The date is shown in “YYYY-MM-DD hh: mm: ss UTC” format, and also in decimal format.
notAfterS / notAfterTS	Same as notBefore, but for the certificate expiration date.
daysToExpire	Remaining validity days of the certificate. A negative number indicates that the certificate is already expired. Since it is an approximation, the status must be used to determine if a certificate is effectively expired.
isDefault	Not used.
status	Decimal value to indicate the certificate status: Unknown (-1) Valid (0) Expired (1) Suspended (2) Revoked (3)
trustLevel	Decimal value that indicates the trust level you have about this certificate in accordance with the policy used for validation: Unknown (-1): There is none information about the certificate Trusted (0): The certificate was issued by a CA included into a policy's trust anchor Self Signed (1): The certificate is self-signed Untrusted (2): The certificate is not included into any Policy's trust anchor
validationMode	Decimal value indicating the mechanism used to validate the certificate. Possible values are: NONE validation (0) Certificate Revocation List - CRL (1) Online Certificate Status Protocol - OCSP (2)
subject	The certificate Subject.
subject.DN	The certificate Distinguished Name (DN).
subject.ParsedDN	Each of the DN fields is broken down into a structure of each of its parts. Repeated fields, such as OU, are in turn decomposed.
issuer / issuer.DN / issuer.parsedDN	As with the subject, the same fields exist for the certificate issuer.
extensions	The certificate extension field divided into different parts.
extensions.subjectAltName.OtherName	Extension field content only if the certificate had any value in this field.

Result value and programing

The response to a query includes information that can be used by the client application.

It is important to understand its meaning, and evaluate the retuned value in a way that minimize the change in the software and delegate the validation to the server. Two values must be taken into account for this to be true:

opResult.resultStatus: This value must be < ERROR (2)
policy.resultStatus: If present, this value must be < ERROR (2)

In the case of wanting strict behavior, you can consider that the only acceptable value is SUCCESS (0), and therefore not accept those answers that have a value of WARNING (1).

The first field indicates whether the request could be processed and there have been no problems regarding its structure (opResult).

The second field (policy) indicates that the requested policy could be fulfilled.

The values of SUCCESS (0), in both cases, are considered a complete success. A value of WARNING (1) indicates that an event has occurred that should be taken into account but does not violate the level of validation required.

Healtcheck and Health

This service receives health check requests as a GET request over a HTTPS connection. To do this you must access the following service URL:

[https://homo-validate.certisur.com:4443/healthcheck]

The response returned a 200 HTTP / HTTPS value code. The other protocol codes must be considered as an error in Debbie's operation and the log must be used to determine its cause.

Below is the definition of the JSON response included in the body.

HealthCheck response

{"version":"2.4.7","status":"UP"}

Additional to the healthcheck validation service, it is possible to validate the status of each policy using the following URL:

[https://homo-validate.certisur.com:4443/health/<tenant>]

HealthCheck response

{
  "info": {
    "date":"2022-02-10T20:32:41.727Z",
    "policyVersion":"3.0.0",
    "notes": {
      "resultList": [
      {
        "code":30075,
        "detail":"[2] OCSPResponder -> http://pki-ocsp.digicert.com (Unauthorized request. OCSP response error: 6)"
      }
    ]
  },
  "policyName":"acme",
  "validationLevel":3
  },
  "statistics": {
    "signatureValidationCounter": {
      "lastValidation":"2021-10-21T09:17:31.114Z",
      "success":2,
      "failure":0
    }
  },
  "status":"WARN"
}

Possible values for ***status*** are as follows:

Status	Value	Description
Success	OK	The policy validation methods (CRL / OCSP) work correctly to validate signatures and certificates.
Warning	WARN	Some of the validation methods (CRL / OCSP) do not work correctly, but it is still possible to perform signature and certificate validation operations. The error that must be addressed is indicated in the detail.
Error	ERROR	An error has occurred that prevents the validation of signatures and certificates. The error that must be addressed is indicated in the detail.

If the status is ERROR or WARNING, a list of pairs of (code, detail*) will be included in the result. This sequence informs the type of error that occurred, and if possible, a detail that might be useful for its diagnosis.

If there are errors in the trustAnchor check within the policy, the list of pairs of (code, detail) within resultList informs the type of error that occurred, and if possible, a detail that can be useful for diagnosis.

In the detail field, the index [n] of the trustAnchor with error is indicated, with the validation type-checked (OCSPResponder or CRL) and a detail of the problem.

CertiSur Products Suites