10.4. INTERFACES
In this section the SiVa external interfaces are described. For information of internal components and their interfaces, please refer to Structure and activities.
SiVa service provides REST JSON and SOAP interfaces that enable the service users to:
- Request validation of signatures in a digitally signed document (i.e. signature container like BDOC,ASiC-E/PDF/...);
- Request validation of signature with providing data file hashes.
- Receive a response with the validation result of all the signatures in the document.
- Request datafiles inside of DDOC container
- Receive datafiles from DDOC container
SiVa service SOAP interface supports X-Road v6. However, it is optional whether to integrate SiVa service using X-Road or using "plain" SOAP interface. This document only describes the SiVa service part of the interface, for the X-Road specifics visit Riigi Infosüsteemi Amet webpage.
In the following subsections, the SiVa validation request and response interfaces are described in detail.
Validation request interface
** REST JSON Endpoint **
POST https://<server url>/validate
** SOAP Endpoint **
POST https://<server url>/soap/validationWebService/validateDocument
** SOAP WSDL **
POST https://<server url>/soap/validationWebService/validateDocument?wsdl
Validation request parameters
Validation request parameters for JSON and SOAP interfaces are described in the table below. Data types of SOAP parameters are defined in the SiVa WSDL document.
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| document | Document | + | String | Base64 encoded string of digitally signed document to be validated |
| filename | Filename | + | String | File name of the digitally signed document (i.e. sample.bdoc), max length 255 characters. |
| documentType | DocumentType | - | String | If not present document type is determined automatically based on the file extension used in the filename. This parameter is necessary to differentiate XROAD ASIC-E containers from standard ASIC-E containers. Possible values: XROAD - for documents created in the X-Road information system, see also specification document of the signature format. |
| signaturePolicy | SignaturePolicy | - | String | Can be used to change the default signature validation policy that is used by the service. See also SiVa Validation Policy for more detailed information on given policy constraints. Possible values: POLv3 - signatures with all legal levels are accepted (i.e. QES, AdESqc and AdES, according to Regulation (EU) No 910/2014.) POLv4 - the default policy. Accepted signatures depend on their type (i.e. signature, seal or unknown) and legal level (i.e. QES, AdESqc and Ades) |
| reportType | ReportType | - | String | Can be used to change the default returned report type. Possible values: Simple - default report type. Returns overall validation result (validationConclusion block) Detailed - returns detailed information about the signatures and their validation results (validationConclusion, validationProcess and validationReportSignature. Two later ones are optionally present). |
Sample JSON request with mandatory parameters
{
"filename":"sample.bdoc",
"document":"PD94bWwgdmVyc2lvbj0iMS4...."
}
Sample JSON request with all parameters
{
"filename":"sample.asice",
"document":"PD94bWwgdmVyc2lvbj0iMS4....",
"documentType":"XROAD",
"signaturePolicy":"POLv3",
"reportType":"Detailed"
}
Sample SOAP request
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:ValidateDocument xmlns:ns2="http://soap.webapp.siva.openeid.ee/">
<ns2:ValidationRequest>
<Document>PD94bWwgdmVyc2lvbj0iMS4....</Document>
<Filename>sample.asice</Filename>
<DocumentType>XROAD</DocumentType>
<SignaturePolicy>POLv3</SignaturePolicy>
<ReportType>Detailed</ReportType>
</ns2:ValidationRequest>
</ns2:ValidateDocument>
</soap:Body>
</soap:Envelope>
Validation request interface for hashcode
Hashcode XAdES validation is supported for REST JSON and SOAP interfaces.
** REST JSON Endpoint **
POST https://<server url>/validateHashcode
** SOAP Endpoint **
POST https://<server url>/soap/hashcodeValidationWebService
** SOAP WSDL **
POST https://<server url>/soap/hashcodeValidationWebService?wsdl
Validation request parameters
Validation request parameters for JSON interface are described in the table below.
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| signatureFile | SignatureFile | + | String | Base64 encoded string of XAdES document to be validated |
| filename | Filename | + | String | File name of the XAdES document (i.e. signature0.xml). Only XML files supported. |
| signaturePolicy | SignaturePolicy | - | String | Can be used to change the default signature validation policy that is used by the service. See also SiVa Validation Policy for more detailed information on given policy constraints. Possible values: POLv3 - signatures with all legal levels are accepted (i.e. QES, AdESqc and AdES, according to Regulation (EU) No 910/2014.) POLv4 - the default policy. Accepted signatures depend on their type (i.e. signature, seal or unknown) and legal level (i.e. QES, AdESqc and Ades) |
| reportType | ReportType | - | String | Can be used to change the default returned report type. Possible values: Simple - default report type. Returns overall validation result (validationConclusion block) Detailed - returns detailed information about the signatures and their validation results (validationConclusion, validationProcess and validationReportSignature. Two later ones are optionally present). |
| datafiles | DataFiles | + | Array | Array containing the information for datafiles that signature is covering |
| datafiles[0] | DataFile | + | Object | Object containing data file information |
| datafiles.filename | Filename | + | String | File name of the hashed data file, max length 255 characters. |
| datafiles.hashAlgo | HashAlgo | + | String | Hash algorithm used for hashing the data file (must match with algorithm in signature file). Accepted values are dependant of validation policy |
| datafiles.hash | Hash | + | String | Data file hash in Base64 encoded format. |
Sample JSON request with mandatory parameters
{
"signatureFile": "PD94bWwgdmVyc2lvbj0iMS4...."
"filename": "signature0.xml",
"datafiles": [{
"filename": "test.pdf",
"hashAlgo": "SHA256",
"hash": "IucjUcbRo9Rke0bZLiHcwiIiplP9pSrSPr7LKln1EiI="
}]
}
Sample JSON request with all parameters and multiple datafiles
{
"signatureFile":"sample.asice",
"filename":"PD94bWwgdmVyc2lvbj0iMS4....",
"signaturePolicy":"POLv3",
"reportType":"Detailed",
"datafiles": [{
"filename": "test.pdf",
"hashAlgo": "SHA256",
"hash": "IucjUcbRo9Rke0bZLiHcwiIiplP9pSrSPr7LKln1EiI="
},
{
"filename": "test2.pdf",
"hashAlgo": "SHA256",
"hash": "IucjUcbRo9Rke0bZLiHc23SSasw9pSrSPr7LKln1EiI="
}]
}
Sample SOAP request with mandatory parameters
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.webapp.siva.openeid.ee/">
<soapenv:Body>
<soap:HashcodeValidationDocument>
<soap:HashcodeValidationRequest>
<SignatureFile>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGlu...</SignatureFile>
<Filename>signature.xml</Filename>
<DataFiles>
<DataFile>
<Filename>test.pdf</Filename>
<HashAlgo>SHA256</HashAlgo>
<Hash>IucjUcbRo9Rke0bZLiHcwiIiplP9pSrSPr7LKln1EiI=</Hash>
</DataFile>
</DataFiles>
</soap:HashcodeValidationRequest>
</soap:HashcodeValidationDocument>
</soapenv:Body>
</soapenv:Envelope>
Sample SOAP request with all parameters and multiple datafiles
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.webapp.siva.openeid.ee/">
<soapenv:Body>
<soap:HashcodeValidationDocument>
<soap:HashcodeValidationRequest>
<SignatureFile>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGlu...</SignatureFile>
<Filename>signature.xml</Filename>
<ReportType>Simple</ReportType>
<SignaturePolicy>POLv4</SignaturePolicy>
<DataFiles>
<DataFile>
<Filename>test.pdf</Filename>
<HashAlgo>SHA256</HashAlgo>
<Hash>IucjUcbRo9Rke0bZLiHcwiIiplP9pSrSPr7LKln1EiI=</Hash>
</DataFile>
<DataFile>
<Filename>test2.pdf</Filename>
<HashAlgo>SHA256</HashAlgo>
<Hash>IucjUcbRo9Rke0bZLiHcwiIiplP9pSrSPr7LKln1EiI=</Hash>
</DataFile>
<DataFile>
<Filename>test3.pdf</Filename>
<HashAlgo>SHA256</HashAlgo>
<Hash>IucjUcbRo9Rke0bZLiHcwiIiplP9pSrSPr7LKln1EiI=</Hash>
</DataFile>
</DataFiles>
</soap:HashcodeValidationRequest>
</soap:HashcodeValidationDocument>
</soapenv:Body>
</soapenv:Envelope>
Validation response interface
The signature validation report (i.e. the validation response) for JSON and SOAP interfaces depends on what type of validation report was requested. Data types of SOAP parameters are defined in the SiVa WSDL document.
Validation response parameters Simple Report (successful scenario)
General structure of validation response.
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| validationReport | ValidationReport | + | Object | Object containing SIVA validation report |
| validationReport. validationConclusion | ValidationReport. ValidationConclusion | + | Object | Object containing information of the validation conclusion |
Structure of validationConclusion block
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| policy | Policy | + | Object | Object containing information of the SiVa signature validation policy that was used for validation. |
| policy.policyName | Policy.PolicyName | + | String | Name of the validation policy |
| policy. policyDescription | Policy. PolicyDescription | + | String | Short description of the validation policy. |
| policy.policyUrl | Policy.PolicyUrl | + | String | URL where the signature validation policy document can be downloaded. The validation policy document shall include information about validation of all the document formats, including the different validation policies that are used in case of different file formats and base libraries. |
| signaturesCount | SignaturesCount | + | Number | Number of signatures found inside digitally signed file. |
| validSignaturesCount | ValidSignaturesCount | + | Number | Signatures count that have validated to TOTAL-PASSED. See also Signature.Indication field. |
| validationLevel | ValidationLevel | - | Date | Validation process against what the document is validated, only applicable on DSS based validations. Possible values: ARCHIVAL_DATA |
| validationTime | ValidationTime | + | Date | Time of validating the signature by the service. |
| validationWarnings | ValidationWarnings | - | Array | Array of SiVa validation warnings that do not affect the overall validation result. See also signatures.warnings parameter. |
| validationWarnings[0] | ValidationWarning | + | Object | Object containing the warning. |
| validationWarnings[0]. content | ValidationWarning. Content | + | String | Description of the warning. |
| validatedDocument | ValidatedDocument | + | Object | Object containing information about validated document. |
| validatedDocument. filename | ValidatedDocument. Filename | + | String | Digitally signed document's file name. |
| validatedDocument. fileHashInHex | ValidatedDocument. FileHashInHex | - | String | Calculated hash in hex of validated document. |
| validatedDocument. hashAlgo | ValidatedDocument. HashAlgo | - | String | Hash algorithm used. |
| signatureForm | SignatureForm | - | String | Format (and optionally version) of the digitally signed document container. In case of documents in DIGIDOC-XML (DDOC) format, the "hashcode" suffix is used to denote that the container was validated in hashcode mode, i.e. without original data files. Possible values: DIGIDOC_XML_1.0 DIGIDOC_XML_1.0_hashcode DIGIDOC_XML_1.1 DIGIDOC_XML_1.1_hashcode DIGIDOC_XML_1.2 DIGIDOC_XML_1.2_hashcode DIGIDOC_XML_1.3 DIGIDOC_XML_1.3_hashcode ASiC_E - used in case of all ASIC-E (BDOC) documents and X-Road simple containers that don't use batch time-stamping (see specification document) ASiC_E_batchsignature - used in case of X-Road containers with batch signature (see specification document) ASiC_S - used in case of all ASIC-S documents |
| signatures | Signatures | - | Array | Collection of signatures found in digitally signed document |
| signatures[0] | Signature | + | Object | Signature information object |
| signatures[0]. claimedSigningTime | Signature. ClaimedSigningTime | + | Date | Claimed signing time, i.e. signer's computer time during signature creation |
| signatures[0].id | Signature.Id | + | String | Signature ID attribute |
| signatures[0].indication | Signature.Indication | + | String | Overall result of the signature's validation process, according to ETSI EN 319 102-1 "Table 5: Status indications of the signature validation process". Note that the validation results of different signatures in one signed document (signature container) may vary. See also validSignaturesCount and SignaturesCount fields. Possible values: TOTAL-PASSED TOTAL-FAILED INDETERMINATE |
| signatures[0]. subIndication | Signature. SubIndication | - | String | Additional subindication in case of failed or indeterminate validation result, according to ETSI EN 319 102-1 "Table 6: Validation Report Structure and Semantics" |
| signatures[0].errors | Signature.Errors | - | Array | Information about validation error(s), array of error messages. |
| signatures[0].errors[0] | Signature.Errors. Error | + | Object | Object containing the error |
| signatures[0].errors[0]. content | Signature.Errors. Error.Content | + | String | Error message, as returned by the base library that was used for signature validation. |
| signatures[0].info | Signature.Info | - | Object | Object containing trusted signing time information. |
| signatures[0].info. bestSignatureTime | Signature.Info. BestSignatureTime | + | Date | Time value that is regarded as trusted signing time, denoting the earliest time when it can be trusted by the validation application (because proven by some Proof-of-Existence present in the signature) that a signature has existed. The source of the value depends on the signature profile (see also SignatureFormat parameter):- Signature with time-mark (LT_TM level) - the producedAt value of the earliest valid time-mark (OCSP confirmation of the signer's certificate) in the signature. - Signature with time-stamp (LT or LTA level) - the genTime value of the earliest valid signature time-stamp token in the signature. - Signature with BES or EPES level - the value is empty, i.e. there is no trusted signing time value available. |
| signatures[0]. signatureFormat | Signature. SignatureFormat | + | String | Format and profile (according to Baseline Profile) of the signature. See XAdES Baseline Profile, CAdES Baseline Profile and PAdES Baseline Profile for detailed description of the Baseline Profile levels. Levels that are accepted in SiVa validation policy are described in SiVa signature validation policy Possible values: XAdES_BASELINE_B XAdES_BASELINE_B_BES XAdES_BASELINE_B_EPES XAdES_BASELINE_T XAdES_BASELINE_LT - long-term level XAdES signature where time-stamp is used as a assertion of trusted signing time XAdES_BASELINE_LT_TM - long-term level XAdES signature where time-mark is used as a assertion of trusted signing time. Used in case of BDOC signatures with time-mark profile and DIGIDOC-XML (DDOC) signatures. XAdES_BASELINE_LTA CAdES_BASELINE_B CAdES_BASELINE_T CAdES_BASELINE_LT CAdES_BASELINE_LTA PAdES_BASELINE_B PAdES_BASELINE_T PAdES_BASELINE_LT PAdES_BASELINE_LTA |
| signatures[0]. signatureLevel | Signature. SignatureLevel | - | String | Legal level of the signature, according to Regulation (EU) No 910/2014. - Possible values on positive validation result: QESIG QESEAL QES ADESIG_QC ADESEAL_QC ADES_QC ADESIG ADESEAL ADES - Possible values on indeterminate validation result: prefix INDETERMINATE is added to the level described in positive result. For example INDETERMINATE_QESIG - Possible values on negative validation result: In addition to abovementioned NOT_ADES_QC_QSCD NOT_ADES_QC NOT_ADES NA - In case of DIGIDOC-XML 1.0..1.3 formats, value is missing as the signature level is not checked by the JDigiDoc base library that is used for validation. However, the signatures can be indirectly regarded as QES level signatures, see also SiVa Validation Policy - In case of XROAD ASICE containers the value is missing as the asicverifier base library do not check the signature level. |
| signatures[0].signedBy | Signature.SignedBy | + | String | Signers name and identification number, i.e. value of the CN field of the signer's certificate |
| signatures[0]. signatureScopes | Signature. SignatureScopes | - | Array | Contains information of the original data that is covered by the signature. |
| signatures[0]. signatureScopes[0]. name | Signature. SignatureScopes. SignatureScope.Name | + | String | Name of the signature scope. |
| signatures[0]. signatureScopes[0]. scope | Signature. SignatureScopes. SignatureScope. Scope | + | String | Type of the signature scope. |
| signatures[0]. signatureScopes[0]. content | Signature. SignatureScopes. SignatureScope. Content | + | String | Description of the scope. |
| signatures[0]. warnings | Signature.Warnings | - | Array | Block of validation warnings that do not affect the overall validation result. |
| signatures[0]. warnings[0] | Signature.Warnings. Warning | + | Object | Object containing the warning |
| signatures[0]. warnings[0]. content | Signature.Warnings. Warning.Description | + | String | Warning description, as retuned by the base library that was used for validation. |
| timeStampTokens | TimeStampTokens | - | Array | Array containing the time stamp tokens |
| timeStampTokens[0]. | TimeStampToken | + | Object | Object containing the time stamp token (TST) |
| timeStampTokens[0]. indication | TimeStampToken. Indication | + | String | Result of the time stamp token validation. Possible values: TOTAL-PASSED TOTAL-FAILED |
| timeStampTokens[0]. signedBy | TimeStampToken. SignedBy | + | String | Signer of the time stamp token. |
| timeStampTokens[0]. signedTime | TimeStampToken. SignedTime | + | String | Time when the time stamp token was given. |
| timeStampTokens[0]. error | TimeStampToken. Errors | - | Array | Errors returned in time stamp token validation. |
| timeStampTokens[0]. error[0] | Errors. Error | + | Object | Object containing the error. |
| timeStampTokens[0]. error[0]. content | Error. Content | + | String | Error description. |
Sample JSON response Simple Report (successful scenario)
{"validationReport":
{"validationConclusion": {
"validationTime": "2017-11-07T08:14:07Z",
"signaturesCount": 1,
"validationLevel": "ARCHIVAL_DATA",
"validatedDocument": {
"filename": "ValidLiveSignature.asice",
"fileHashInHex": "0A805C920603750E0B427C3F25D7B22DCEC183DEF3CA14BE9A2D4488887DD501",
"hashAlgo": "SHA-256"
},
"validSignaturesCount": 1,
"signatures": [{
"signatureFormat": "XAdES_BASELINE_LT",
"signedBy": "NURM,AARE,38211015222",
"claimedSigningTime": "2016-10-11T09:35:48Z",
"signatureLevel": "QESIG",
"warnings": [{"content": "The trusted list is not fresh!"}],
"signatureScopes": [{
"scope": "FullSignatureScope",
"name": "Tresting.txt",
"content": "Full document"
}],
"id": "S0",
"indication": "TOTAL-PASSED",
"info": {"bestSignatureTime": "2016-10-11T09:36:10Z"}
}],
"policy": {
"policyDescription": "Policy for validating Qualified Electronic Signatures and Qualified Electronic Seals (according to Regulation (EU) No 910/2014). I.e. signatures that have been recognized as Advanced electronic Signatures (AdES) and AdES supported by a Qualified Certificate (AdES/QC) do not produce a positive validation result.",
"policyUrl": "http://open-eid.github.io/SiVa/siva2/appendix/validation_policy/#POLv4",
"policyName": "POLv4"
},
"signatureForm": "ASiC_E"
}}}
Sample SOAP response Simple Report (successful scenario)
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:ValidateDocumentResponse xmlns:ns2="http://soap.webapp.siva.openeid.ee/" xmlns:ns3="http://dss.esig.europa.eu/validation/detailed-report" xmlns:ns4="http://x-road.eu/xsd/identifiers" xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">
<ns2:ValidationReport>
<ns2:ValidationConclusion>
<Policy>
<PolicyDescription>Policy for validating Qualified Electronic Signatures and Qualified Electronic Seals (according to Regulation (EU) No 910/2014). I.e. signatures that have been recognized as Advanced electronic Signatures (AdES) and AdES supported by a Qualified Certificate (AdES/QC) do not produce a positive validation result.</PolicyDescription>
<PolicyName>POLv4</PolicyName>
<PolicyUrl>http://open-eid.github.io/SiVa/siva/appendix/validation_policy/#POLv4</PolicyUrl>
</Policy>
<ValidationTime>2017-11-07T08:14:07Z</ValidationTime>
<ValidatedDocument>
<Filename>ValidLiveSignature.asice</Filename>
<FileHashInHex>0A805C920603750E0B427C3F25D7B22DCEC183DEF3CA14BE9A2D4488887DD501</FileHashInHex>
<HashAlgo>SHA-256</HashAlgo>
</ValidatedDocument>
<ValidationLevel>ARCHIVAL_DATA</ValidationLevel>
<ValidationWarnings/>
<SignatureForm>ASiC_E</SignatureForm>
<Signatures>
<Signature>
<Id>S0</Id>
<SignatureFormat>XAdES_BASELINE_LT</SignatureFormat>
<SignatureLevel>QESIG</SignatureLevel>
<SignedBy>NURM,AARE,38211015222</SignedBy>
<Indication>TOTAL-PASSED</Indication>
<SubIndication/>
<Errors/>
<SignatureScopes>
<SignatureScope>
<Name>Tresting.txt</Name>
<Scope>FullSignatureScope</Scope>
<Content>Full document</Content>
</SignatureScope>
</SignatureScopes>
<ClaimedSigningTime>2016-10-11T09:35:48Z</ClaimedSigningTime>
<Warnings>
<Warning>
<Content>The trusted list is not fresh!</Content>
</Warning>
</Warnings>
<Info>
<bestSignatureTime>2016-10-11T09:36:10Z</bestSignatureTime>
</Info>
</Signature>
</Signatures>
<ValidSignaturesCount>1</ValidSignaturesCount>
<SignaturesCount>1</SignaturesCount>
</ns2:ValidationConclusion>
</ns2:ValidationReport>
</ns2:ValidateDocumentResponse>
</soap:Body>
</soap:Envelope>
Validation response parameters Detailed Report (successful scenario)
General structure of validation response.
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| validationReport | ValidationReport | + | Object | Object containing SIVA validation report. |
| validationReport. validationConclusion | ValidationReport. ValidationConclusion | + | Object | Object containing information of the validation conclusion. The same object that is present in Simple Report. |
| validationReport. validationProcess | ValidationReport. ValidationProcess | - | Object | Object containing information of the validation process. This block is present only on DSS library based validations and is built on DSS detailed report. For more information visit DSS documentation. |
| validationReportSignature | ValidationReportSignature | - | String | Base64 string of ASIC-E container that includes the detailed report and is signed by the validation service provider |
Sample JSON response Detailed Report (successful scenario). The report is shortened but gives general overview of structure.
{
"validationReport": {
"validationProcess": {
"qmatrixBlock": {
"tlanalysis": [{
"conclusion": {"indication": "PASSED"},
"countryCode": "EU",
"constraint": [
{
"name": {
"nameId": "QUAL_TL_FRESH",
"value": "Is the trusted list fresh ?"
},
"status": "OK"
},
...
]
},
{
"conclusion": {"indication": "PASSED"},
"countryCode": "EE",
"constraint": [{
"name": {
"nameId": "QUAL_TL_FRESH",
"value": "Is the trusted list fresh ?"
},
"status": "OK"
},
...
]
}
],
"signatureAnalysis": [{
"conclusion": {"indication": "PASSED"},
"signatureQualification": "QESIG",
"constraint": [{
"name": {
"nameId": "QUAL_IS_ADES",
"value": "Is the signature/seal an acceptable AdES (ETSI EN 319 102-1) ?"
},
"status": "OK"
},
...
],
"id": "S0"
}]
},
"basicBuildingBlocks": [{
"conclusion": {"indication": "PASSED"},
"cv": {
"conclusion": {"indication": "PASSED"},
"constraint": [{
"name": {
"nameId": "BBB_CV_IRDOF",
"value": "Is the reference data object(s) found?"
},
"status": "OK"
},
...
]},
...
"id": "1561CD6BEA97B0A72664067021330509894BE1EBA586D3057D77787E5F4180A4",
"type": "TIMESTAMP"
},
...
"signatures": [{
"validationProcessArchivalData": {
"conclusion": {"indication": "PASSED"},
"constraint": [{
"name": {
"nameId": "ARCH_LTVV",
"value": "Is the result of the LTV validation process acceptable?"
},
"status": "OK"
}]},
...
},
"id": "S0",
"validationProcessLongTermData": {
"conclusion": {"indication": "PASSED"},
"constraint": [{
"name": {
"nameId": "LTV_ABSV",
"value": "Is the result of the Basic Validation Process acceptable?"},
"status": "OK"
},
...
}]}}]
},
"validationConclusion": {
"validationTime": "2017-11-07T09:20:18Z",
"signaturesCount": 1,
"validationLevel": "ARCHIVAL_DATA",
"validatedDocument": {
"filename": "ValidLiveSignature.asice",
"fileHashInHex": "0A805C920603750E0B427C3F25D7B22DCEC183DEF3CA14BE9A2D4488887DD501",
"hashAlgo": "SHA-256"
},
"validSignaturesCount": 1,
"signatures": [{
"signatureFormat": "XAdES_BASELINE_LT",
"signedBy": "NURM,AARE,38211015222",
"claimedSigningTime": "2016-10-11T09:35:48Z",
"signatureLevel": "QESIG",
"signatureScopes": [{
"scope": "FullSignatureScope",
"name": "Tresting.txt",
"content": "Full document"
}],
"id": "S0",
"indication": "TOTAL-PASSED",
"info": {"bestSignatureTime": "2016-10-11T09:36:10Z"}
}],
"policy": {
"policyDescription": "Policy for validating Qualified Electronic Signatures and Qualified Electronic Seals (according to Regulation (EU) No 910/2014). I.e. signatures that have been recognized as Advanced electronic Signatures (AdES) and AdES supported by a Qualified Certificate (AdES/QC) do not produce a positive validation result.",
"policyUrl": "http://open-eid.github.io/SiVa/siva/appendix/validation_policy/#POLv4",
"policyName": "POLv4"
},
"signatureForm": "ASiC_E"
}
},
"validationReportSignature": "UEsDBBQACAgIAIlaZ0sAA..."
}
Sample SOAP response Simple Report (successful scenario)
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:ValidateDocumentResponse xmlns:ns2="http://soap.webapp.siva.openeid.ee/" xmlns:ns3="http://dss.esig.europa.eu/validation/detailed-report" xmlns:ns4="http://x-road.eu/xsd/identifiers" xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">
<ns2:ValidationReport>
<ns2:ValidationConclusion>
<Policy>
<PolicyDescription>Policy for validating Qualified Electronic Signatures and Qualified Electronic Seals (according to Regulation (EU) No 910/2014). I.e. signatures that have been recognized as Advanced electronic Signatures (AdES) and AdES supported by a Qualified Certificate (AdES/QC) do not produce a positive validation result.</PolicyDescription>
<PolicyName>POLv4</PolicyName>
<PolicyUrl>http://open-eid.github.io/SiVa/siva/appendix/validation_policy/#POLv4</PolicyUrl>
</Policy>
<ValidationTime>2017-11-07T09:20:18Z</ValidationTime>
<ValidatedDocument>
<Filename>ValidLiveSignature.asice</Filename>
<FileHashInHex>0A805C920603750E0B427C3F25D7B22DCEC183DEF3CA14BE9A2D4488887DD501</FileHashInHex>
<HashAlgo>SHA-256</HashAlgo>
</ValidatedDocument>
<ValidationLevel>ARCHIVAL_DATA</ValidationLevel>
<ValidationWarnings/>
<SignatureForm>ASiC-E</SignatureForm>
<Signatures>
<Signature>
<Id>S0</Id>
<SignatureFormat>XAdES_BASELINE_LT</SignatureFormat>
<SignatureLevel>QESIG</SignatureLevel>
<SignedBy>NURM,AARE,38211015222</SignedBy>
<Indication>TOTAL-PASSED</Indication>
<SubIndication/>
<Errors/>
<SignatureScopes>
<SignatureScope>
<Name>Tresting.txt</Name>
<Scope>FullSignatureScope</Scope>
<Content>Full document</Content>
</SignatureScope>
</SignatureScopes>
<ClaimedSigningTime>2016-10-11T09:35:48Z</ClaimedSigningTime>
<Warnings/>
<Info>
<bestSignatureTime>2016-10-11T09:36:10Z</bestSignatureTime>
</Info>
</Signature>
</Signatures>
<ValidSignaturesCount>1</ValidSignaturesCount>
<SignaturesCount>1</SignaturesCount>
</ns2:ValidationConclusion>
<ns2:ValidationProcess>
<ns3:Signatures Id="S0">
<ns3:ValidationProcessBasicSignatures>
<ns3:Constraint Id="S0">
<ns3:Name NameId="ADEST_ROBVPIIC">Is the result of the Basic Validation Process conclusive?</ns3:Name>
<ns3:Status>OK</ns3:Status>
</ns3:Constraint>
<ns3:Conclusion>
<ns3:Indication>PASSED</ns3:Indication>
</ns3:Conclusion>
</ns3:ValidationProcessBasicSignatures>
...
<ns3:ValidationProcessArchivalData>
<ns3:Constraint>
<ns3:Name NameId="ARCH_LTVV">Is the result of the LTV validation process acceptable?</ns3:Name>
<ns3:Status>OK</ns3:Status>
</ns3:Constraint>
<ns3:Conclusion>
<ns3:Indication>PASSED</ns3:Indication>
</ns3:Conclusion>
</ns3:ValidationProcessArchivalData>
</ns3:Signatures>
...
<ns3:BasicBuildingBlocks Id="S0" Type="SIGNATURE">
<ns3:FC>
<ns3:Constraint>
<ns3:Name NameId="BBB_FC_IEFF">Is the expected format found?</ns3:Name>
<ns3:Status>OK</ns3:Status>
</ns3:Constraint>
...
<ns3:XCV>
<ns3:Constraint>
<ns3:Name NameId="BBB_XCV_CCCBB">Can the certificate chain be built till the trust anchor?</ns3:Name>
<ns3:Status>OK</ns3:Status>
</ns3:Constraint>
</ns3:BasicBuildingBlocks>
<ns3:QMatrixBlock>
<ns3:TLAnalysis CountryCode="EU">
...
<ns3:Constraint>
<ns3:Name NameId="QUAL_TL_WS">Is the trusted list well signed ?</ns3:Name>
<ns3:Status>OK</ns3:Status>
</ns3:Constraint>
<ns3:Conclusion>
<ns3:Indication>PASSED</ns3:Indication>
</ns3:Conclusion>
</ns3:TLAnalysis>
...
<ns3:SignatureAnalysis Id="S0" SignatureQualification="QESig">
<ns3:Constraint>
<ns3:Name NameId="QUAL_IS_ADES">Is the signature/seal an acceptable AdES (ETSI EN 319 102-1) ?</ns3:Name>
<ns3:Status>OK</ns3:Status>
</ns3:Constraint>
...
<ns3:Conclusion>
<ns3:Indication>PASSED</ns3:Indication>
</ns3:Conclusion>
</ns3:SignatureAnalysis>
</ns3:QMatrixBlock>
</ns2:ValidationProcess>
</ns2:ValidationReport>
<ValidationReportSignature>UEsDBBQACAgIAIlaZ0s...</ValidationReportSignature>
</ns2:ValidateDocumentResponse>
</soap:Body>
</soap:Envelope>
Sample JSON response (error situation)
In case of error (when validation report is not returned) status code 400 is returned together with following message body:
{"requestErrors": [{
"message": "Document malformed or not matching documentType",
"key": "document"
}]}
Sample SOAP response (error situation)
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Server</faultcode>
<faultstring>Document malformed or not matching documentType</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
Data files request interface
** REST JSON Endpoint **
POST https://<server url>/getDataFiles
** SOAP Endpoint **
POST https://<server url>/soap/dataFilesWebService/getDocumentDataFiles
** SOAP WSDL **
POST https://<server url>/soap/dataFilesWebService/getDocumentDataFiles?wsdl
Data files request parameters
Data files request parameters for JSON and SOAP interfaces are described in the table below. Data types of SOAP parameters are defined in the SiVa WSDL document.
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| document | Document | + | String | Base64 encoded string of digitally signed DDOC document |
| filename | Filename | + | String | File name of the digitally signed document (i.e. sample.ddoc), max length 255 characters. Currently only DDOC file format is supported for this operation |
Sample JSON request
{
"filename":"sample.ddoc",
"document":"PD94bWwgdmVyc2lvbj0iMS4...."
}
Sample SOAP request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://soap.webapp.siva.openeid.ee/">
<soapenv:Header/>
<soapenv:Body>
<soap:GetDocumentDataFiles>
<soap:DataFilesRequest>
<Document>PD94bWwgdmVyc2lvbj0iMS4wI...</Document>
<Filename>sample.ddoc</Filename>
</soap:DataFilesRequest>
</soap:GetDocumentDataFiles>
</soapenv:Body>
</soapenv:Envelope>
Data files response interface
Data files response parameters (successful scenario)
The data file extraction report (i.e. the data files response) for JSON and SOAP interfaces is described in the table below. Data types of SOAP parameters are defined in the SiVa WSDL document. SiVa returns all data files as they are extracted by JDigiDoc library in an as is form. No extra operations or validations are done.
| JSON parameter | SOAP parameter | Mandatory | JSON data type | Description |
|---|---|---|---|---|
| dataFiles | DataFiles | - | Array | Collection of data files found in digitally signed document |
| dataFiles[0] | DataFile | + | Object | Extracted data file object |
| dataFiles[0].fileName | DataFile.FileName | - | String | File name of the extracted data file |
| dataFiles[0].size | DataFile.Size | - | Long | Extracted data file size in bytes |
| dataFiles[0].base64 | DataFile.Base64 | - | String | Base64 encoded string of extracted data file |
| dataFiles[0].mimeType | DataFile.MimeType | - | String | MIME type of the extracted data file |
Sample JSON response (successful scenario)
{
"dataFiles": [{
"fileName": "Glitter-rock-4_gallery.jpg",
"size": 41114,
"base64": "/9j/4AAQSkZJ...",
"mimeType": "application/octet-stream" }]
}
Sample SOAP response (successful scenario)
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:GetDocumentDataFilesResponse xmlns:ns2="http://soap.webapp.siva.openeid.ee/" xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd">
<ns2:DataFilesReport>
<DataFiles>
<DataFile>
<Base64>UCgUCgUCgUCgUCgUCgUCgUCgUCgUCgUCgUH...</Base64>
<FileName>Glitter-rock-4_gallery.jpg</FileName>
<MimeType>application/octet-stream</MimeType>
<Size>41114</Size>
</DataFile>
</DataFiles>
</ns2:DataFilesReport>
</ns2:GetDocumentDataFilesResponse>
</soap:Body>
</soap:Envelope>
Sample JSON response (error situation)
In case of error (when datafiles are not returned) status code 400 is returned together with following message body:
{"requestErrors": [{
"message": "Invalid document type. Can only return data files for DDOC type containers.",
"key": "documentType"
}]}
Sample SOAP response (error situation)
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Invalid document type. Can only return data files for DDOC type containers.</faultstring>
</soap:Fault>
</soap:Body>
</soap:Envelope>
Service health monitoring
SiVa webapps provide an interface for external monitoring tools (to periodically check the generic service health status).
The request
The monitoring endpoint is accessible via HTTP GET at /monitoring/health or /monitoring/health.json url.
Sample request:
GET https://<server url>/monitoring/health
The response
As a response, a JSON object is returned with the following information:
| Field | Description |
|---|---|
| status | General status of the webapp. Possible values:
|
| health.status | Status of current webapp - constant value UP |
| health.webappName | The artifact name of the webapp. Taken from the MANIFEST.MF file (inside the jar/war file). |
| health.version | The release version fo the webapp. Taken from the MANIFEST.MF (inside the jar/war file). |
| health.buildTime | Build date and time (format yyyy-MM-dd'T'HH:mm:ss'Z') of the webapp. Taken from the MANIFEST.MF (inside the jar/war file). |
| health.startTime | Webapp startup date and time (format yyyy-MM-dd'T'HH:mm:ss'Z') |
| health.currentTime | Current server date and time (format yyyy-MM-dd'T'HH:mm:ss'Z') |
| link{number}.status | (OPTIONAL) Represents the status of a link to the external system that the webapp depends on.
|
| link{number}.name | (OPTIONAL) Descriptive name for the link to the external system |
Sample response:
{
"status":"UP",
"health":{
"status":"UP",
"webappName":"siva-demo-application",
"version":"3.1.0",
"buildTime":"2016-10-21T15:56:21Z",
"startTime":"2016-10-21T15:57:48Z",
"currentTime":"2016-10-21T15:58:39Z"
},
"link1":{
"status":"UP",
"name":"sivaService"
}
}