Skip to content

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 XAdES signature without datafiles.
  • Request datafiles inside of 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.
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).
Diagnostic - returns diagnostic data about the information contained in the signature itself, it's revocation data and mathematical validity (validationConclusion, diagnosticData block)

Sample JSON request with mandatory parameters

{
  "filename":"sample.bdoc",
  "document":"PD94bWwgdmVyc2lvbj0iMS4...."
}

Sample JSON request with all parameters

{
  "filename":"sample.asice",
  "document":"PD94bWwgdmVyc2lvbj0iMS4....",
  "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>
        <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

Two different use cases are supported for the hashcode validation. 1) Providing the data file name, hash algorithm and hash on validation. 2) Providing only signature file. NB! This method requires validation result change on integrator side when the local datafile hashes do not match with hashes returned in validation result!

Validation request parameters for JSON interface are described in the table below.

JSON parameter SOAP parameter Mandatory JSON data type Description
signatureFiles SignatureFiles + Array Array containing the signature objects.
signatureFiles[0] SignatureFiles.SignatureFile + Object Object containing one signature file.
signatureFiles[0].signature SignatureFiles.SignatureFile.Signature + String Base64 encoded string of signature file
signatureFiles[0].datafiles SignatureFiles.SignatureFile.Signature.DataFiles - Array Array containing the information for datafiles that signature is covering
signatureFiles[0].datafiles[0] SignatureFiles.SignatureFile.Signature.DataFiles.DataFile + Object Object containing data file information
signatureFiles[0].datafiles[0].filename SignatureFiles.SignatureFile.Signature.DataFiles.DataFile.Filename + String File name of the hashed data file, max length 255 characters.
signatureFiles[0].datafiles[0].hashAlgo SignatureFiles.SignatureFile.Signature.DataFiles.DataFile.HashAlgo + String Hash algorithm used for hashing the data file (must match with algorithm in signature file). Accepted values are dependant of validation policy
signatureFiles[0].datafiles[0].hash SignatureFiles.SignatureFile.Signature.DataFiles.DataFile.Hash + String Data file hash in Base64 encoded 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
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 not supported for hashcode).
Diagnostic - returns diagnostic data about the information contained in the signature itself, it's revocation data and mathematical validity (validationConclusion, diagnosticData block. Last one is not support for hashcode)

Sample JSON request with mandatory parameters (datafile hashcode match verification done on integrators side)

{
  "signatureFiles": [
    {
      "signature": "PD9094wskjd..."
    },
    {
      "signature": "AD9sa4wsfsd..."
    }
  ]
}

Sample JSON request with all parameters (datafile hashcode match verification done on SIVA side)

{
    "signatureFiles": [
        {
            "signature": "PD94bWwgdmVyc2lvbj...",
            "datafiles": [
                {
                    "filename": "leping.pdf",
                    "hashAlgo": "SHA256",
                    "hash": "WRlczpSZXZvY2F0aW9uVmFsd..."
                },
                                {
                    "filename": "leping2.pdf",
                    "hashAlgo": "SHA256",
                    "hash": "WRlpzaF0F0sda2vaW9uVmFsd..."
                }
            ]
        },
        {
            "signature": "PDadw4mVyc2lvbj...",
            "datafiles": [
                {
                    "filename": "leping.pdf",
                    "hashAlgo": "SHA256",
                    "hash": "WRlczpSZXZvY2F0aW9uVmFsd..."
                },
                                {
                    "filename": "leping2.pdf",
                    "hashAlgo": "SHA256",
                    "hash": "WRlpzaF0F0sda2vaW9uVmFsd..."
                }
            ]
        }
    ],
    "reportType": "Simple",
    "signaturePolicy": "POLv4"
}

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>
            <SignatureFiles>
                <SignatureFile>
                    <Signature>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGlu...</Signature>
                </SignatureFile>
                <SignatureFile>
                    <Signature>PD94bW2lvbj0wgdmVyciMS4wIvZG2lvbj0lu...</Signature>
                </SignatureFile>
            </SignatureFiles>
         </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>
            <SignatureFiles>
                <SignatureFile>
                    <Signature>PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGlu...</Signature>
                    <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>
                    </DataFiles>
                </SignatureFile>
                <SignatureFile>
                    <Signature>PiBlbmNvZD94bWwgdmVyc2lvbj0PD94bWwGlu...</Signature>
                    <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>
                    </DataFiles>
                </SignatureFile>
            </SignatureFiles>
         </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. Not present for hashcode validation.
validatedDocument. fileHash ValidatedDocument. FileHash - String Calculated hash for validated document in Base64. Present when report signing is enabled.
validatedDocument. hashAlgo ValidatedDocument. HashAlgo - String Hash algorithm used. Present when report signing is enabled.
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
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 and user added additional signing info.
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].info. timeAssertionMessageImprint Signature.Info. TimeAssertionMessageImprint - String Base64 encoded value of message imprint retrieved from time assertion. In case of LT_TM (TimeMark) signatures, OCSP nonce value is returned. In case of T, LT or LTA (TimeStamp) signatures, TimeStamp message imprint is returned.
signatures[0].info. ocspResponseCreationTime Signatures.Info. OcspResponseCreationTime - Date Time value that is regarded as the original OCSP response creation time.
signatures[0].info. timestampCreationTime Signatures.Info. TimestampCreationTime - Date Time value of the timestamp creation
signatures[0].info. signerRole Signature.Info. SignerRole - Array Array of roles attached to the signature.
signatures[0].info. signerRole[0] Signature.Info. SignerRole[0] + Object Object containing claimed roles.
signatures[0].info. signerRole[0]. claimedRole Signature.Info. SignerRole[0].ClaimedRole + String Role stated by signer on signing.
signatures[0].info. signatureProductionPlace Signature.Info. SignatureProductionPlace - Object Object containing stated signing location info.
signatures[0].info. signatureProductionPlace.countryName Signature.Info. SignatureProductionPlace.CountryName - String Stated signing country.
signatures[0].info. signatureProductionPlace.stateOrProvince Signature.Info. SignatureProductionPlace.StateOrProvince - String Stated state or province.
signatures[0].info. signatureProductionPlace.city Signature.Info. SignatureProductionPlace.City - String Stated city.
signatures[0].info. signatureProductionPlace.postalCode Signature.Info. SignatureProductionPlace.PostalCode - String Stated postal code.
signatures[0].info. signingReason Signature.Info SigningReason - String Free text field for PAdES type signatures for stating the signing reason
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]. signatureMethod Signature. SignatureMethod + String Signature method specification URI used in signature creation.
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
signatures[0].signedBy Signature.SignedBy + String In format of "surname, givenName, serialNumber" if these fields are present in subject distinguished name field. In other cases, value of common name field.
signatures[0].subjectDistinguishedName.serialNumber Signature.SubjectDistinguishedName.SerialNumber - String SERIALNUMBER value portion in signer's certificate's subject distinguished name
signatures[0].subjectDistinguishedName.commonName Signature.SubjectDistinguishedName.CommonName - String CN (common name) value portion in signer's certificate's subject distinguished name
signatures[0].subjectDistinguishedName.givenName Signature.SubjectDistinguishedName.GivenName - String Given name value portion in signer's certificate's subject distinguished name
signatures[0].subjectDistinguishedName.surname Signature.SubjectDistinguishedName.Surname - String Surname value portion in signer's certificate's subject distinguished name
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]. signatureScopes[0]. hashAlgo Signature. SignatureScopes. SignatureScope. HashAlgo - String Hash algorithm used for datafile hash calculation. Present for hashcode validation.
signatures[0]. signatureScopes[0]. hash Signature. SignatureScopes. SignatureScope. Hash - String Hash of data file encoded in Base64. Present for hashcode validation.
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.
signatures[0].certificates Signature.Certificates - Array Array containing certificates that are present in the signature or can be fetched from TSL.
signatures[0].certificates[0] Signature.Certificates.Certificate + Object Object containinig certificate type, common name and certificate. Minimal object is signer certificate. If present contains certificates for TimeStamps and OCSP as well.
signatures[0].certificates[0].commonName Signature.Certificates.Certificate.CommonName + String CN (common name) value in certificate.
signatures[0].certificates[0].type Signature.Certificates.Certificate.Type + String Type of the certificate. Can be SIGNING, REVOCATION, SIGNATURE_TIMESTAMP, ARCHIVE_TIMESTAMP or CONTENT_TIMESTAMP.
signatures[0].certificates[0].content Signature.Certificates.Certificate.Content + String DER encoded X.509 certificate in Base64.
signatures[0].certificates[0].issuer Signature.Certificates.Certificate.Issuer + String Object containing issuer certificate information. Can create chain til the trust anchor.
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": "2020-06-15T11:45:52Z",
    "signaturesCount": 1,
    "validationLevel": "ARCHIVAL_DATA",
    "validatedDocument": {"filename": "singleValidSignatureTS.asice"},
    "validSignaturesCount": 1,
    "signatures": [{
        "signatureFormat": "XAdES_BASELINE_LT",
        "subjectDistinguishedName": {
            "commonName": "JÕEORG,JAAK-KRISTJAN,38001085718",
            "serialNumber": "PNOEE-38001085718"
        },
        "certificates": [
            {
                "commonName": "DEMO of SK TSA 2014",
                "type": "SIGNATURE_TIMESTAMP",
                "content": "MII..."
            },
            {
                "commonName": "JÕEORG,JAAK-KRISTJAN,38001085718",
                "type": "SIGNING",
                "content": "MII...",
                "issuer": {
                    "commonName": "TEST of ESTEID2018",
                    "content": "MII..."
                }
            },
            {
                "commonName": "TEST of SK OCSP RESPONDER 2011",
                "type": "REVOCATION",
                "content": "MII..."
            }
        ],
        "signedBy": "JÕEORG,JAAK-KRISTJAN,38001085718",
        "claimedSigningTime": "2020-05-21T13:56:52Z",
        "signatureLevel": "QESIG",
        "signatureScopes": [{
            "scope": "FULL",
            "name": "test.txt",
            "content": "Full document"
        }],
        "signatureMethod": "http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256",
        "id": "id-a9ce7f66cff1d17ddaab37c46a88f5f4",
        "indication": "TOTAL-PASSED",
        "info": {
            "timestampCreationTime": "2020-05-21T13:56:48Z",
            "timeAssertionMessageImprint": "MDEwDQYJYIZIAWUDBAIBBQAEID3j1ceryQp4ZNP8iVfd50l/0JXvpry+XS+ajiAUA+Su",
            "bestSignatureTime": "2020-05-21T13:56:48Z",
            "ocspResponseCreationTime": "2020-05-21T13:56:49Z"
        }
    }],
    "policy": {
        "policyDescription": "Policy according most common requirements of Estonian Public Administration, to validate Qualified Electronic Signatures and Electronic Seals with Qualified Certificates (according to Regulation (EU) No 910/2014, aka eIDAS). 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, with exception for seals, where AdES/QC and above will produce positive result. Signatures and Seals which are not compliant with ETSI standards (referred by eIDAS) may produce unknown or invalid validation result. Validation process is based on eIDAS Article 32 and referred ETSI standards.",
        "policyUrl": "http://open-eid.github.io/SiVa/siva3/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://soap.webapp.siva.openeid.ee/response/" xmlns:ns4="http://dss.esig.europa.eu/validation/detailed-report" xmlns:ns5="http://dss.esig.europa.eu/validation/diagnostic" xmlns:ns6="http://x-road.eu/xsd/identifiers" xmlns:ns7="http://x-road.eu/xsd/xroad.xsd">
      <ns3:ValidationReport>
        <ns3:ValidationConclusion>
          <ns3:Policy>
            <ns3:PolicyDescription>Policy according most common requirements of Estonian Public Administration, to validate Qualified Electronic Signatures and Electronic Seals with Qualified Certificates (according to Regulation (EU) No 910/2014, aka eIDAS). 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, with exception for seals, where AdES/QC and above will produce positive result. Signatures and Seals which are not compliant with ETSI standards (referred by eIDAS) may produce unknown or invalid validation result. Validation process is based on eIDAS Article 32 and referred ETSI standards.</ns3:PolicyDescription>
            <ns3:PolicyName>POLv4</ns3:PolicyName>
            <ns3:PolicyUrl>http://open-eid.github.io/SiVa/siva3/appendix/validation_policy/#POLv4</ns3:PolicyUrl>
          </ns3:Policy>
          <ns3:ValidationTime>2020-06-15T11:45:52Z</ns3:ValidationTime>
          <ns3:ValidatedDocument>
            <ns3:Filename>singleValidSignatureTS.asice</ns3:Filename>
          </ns3:ValidatedDocument>
          <ns3:ValidationLevel>ARCHIVAL_DATA</ns3:ValidationLevel>
          <ns3:ValidationWarnings/>
          <ns3:SignatureForm>ASiC-E</ns3:SignatureForm>
          <ns3:Signatures>
            <ns3:Signature>
              <ns3:Id>id-a9ce7f66cff1d17ddaab37c46a88f5f4</ns3:Id>
              <ns3:SignatureFormat>XAdES_BASELINE_LT</ns3:SignatureFormat>
              <ns3:SignatureMethod>http://www.w3.org/2001/04/xmldsig-more#ecdsa-sha256</ns3:SignatureMethod>
              <ns3:SignatureLevel>QESIG</ns3:SignatureLevel>
              <ns3:SignedBy>JÕEORG,JAAK-KRISTJAN,38001085718</ns3:SignedBy>
              <ns3:SubjectDistinguishedName>
                <ns3:SerialNumber>PNOEE-38001085718</ns3:SerialNumber>
                <ns3:CommonName>JÕEORG,JAAK-KRISTJAN,38001085718</ns3:CommonName>
                <ns3:GivenName>JAAK-KRISTJAN</ns3:GivenName>
                <ns3:Surname>JÕEORG</ns3:Surname>
              </ns3:SubjectDistinguishedName>
              <ns3:Certificates>
                <ns3:Certificate>
                  <ns3:Content>MIIE...</ns3:Content>
                  <ns3:CommonName>DEMO of SK TSA 2014</ns3:CommonName>
                  <ns3:Type>SIGNATURE_TIMESTAMP</ns3:Type>
                </ns3:Certificate>
                <ns3:Certificate>
                  <ns3:Content>MIIE...</ns3:Content>
                  <ns3:CommonName>JÕEORG,JAAK-KRISTJAN,38001085718</ns3:CommonName>
                  <ns3:Issuer>
                    <ns3:Content>MIIE...</ns3:Content>
                    <ns3:CommonName>TEST of ESTEID2018</ns3:CommonName>
                  </ns3:Issuer>
                  <ns3:Type>SIGNING</ns3:Type>
                </ns3:Certificate>
                <ns3:Certificate>
                  <ns3:Content>MIIE...</ns3:Content>
                  <ns3:CommonName>TEST of SK OCSP RESPONDER 2011</ns3:CommonName>
                  <ns3:Type>REVOCATION</ns3:Type>
                </ns3:Certificate>
              </ns3:Certificates>
              <ns3:Indication>TOTAL-PASSED</ns3:Indication>
              <ns3:SubIndication/>
              <ns3:Errors/>
              <ns3:SignatureScopes>
                <ns3:SignatureScope>
                  <ns3:Name>test.txt</ns3:Name>
                  <ns3:Scope>FULL</ns3:Scope>
                  <ns3:Content>Full document</ns3:Content>
                </ns3:SignatureScope>
              </ns3:SignatureScopes>
              <ns3:ClaimedSigningTime>2020-05-21T13:56:52Z</ns3:ClaimedSigningTime>
              <ns3:Warnings/>
              <ns3:Info>
                <ns3:OcspResponseCreationTime>2020-05-21T13:56:49Z</ns3:OcspResponseCreationTime>
                <ns3:TimestampCreationTime>2020-05-21T13:56:48Z</ns3:TimestampCreationTime>
                <ns3:BestSignatureTime>2020-05-21T13:56:48Z</ns3:BestSignatureTime>
                <ns3:TimeAssertionMessageImprint>MDEwDQYJYIZIAWUDBAIBBQAEID3j1ceryQp4ZNP8iVfd50l/0JXvpry+XS+ajiAUA+Su</ns3:TimeAssertionMessageImprint>
              </ns3:Info>
            </ns3:Signature>
          </ns3:Signatures>
          <ns3:ValidSignaturesCount>1</ns3:ValidSignaturesCount>
          <ns3:SignaturesCount>1</ns3:SignaturesCount>
        </ns3:ValidationConclusion>
      </ns3:ValidationReport>
    </ns2:ValidateDocumentResponse>
  </soap:Body>
</soap:Envelope>

Warning/error messages filtered out in Simple Report

From Simple Report following messages, that are considered false-positive in Estonian context, are filtered out: * Warning: The organization name is missing in the trusted certificate! * Warning: The trusted certificate does not match the trust service! * Error: The certificate is not related to a granted status at time-stamp lowest POE time!

Above messages are filtered out only in Simple Report.

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

Validation response parameters for Diagnostic Data 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 and Detailed Report.
validationReport. diagnosticData ValidationReport. DiagnosticData - Object Object containing diagnostic data about the information contained in the signature itself, it's revocation data and mathematical validity. This block is present only on DSS library based validations (excluding hashcode validation) and is built on DSS diagnostic data. For more information visit DSS documentation.

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:
  • DOWN - when some of the dependent indicators status are down (ie when link{number}.status is DOWN, the overall service status is DOWN)
  • UP - the default value.
components.health.status Status of current webapp - constant value UP
components.health.details.webappName The artifact name of the webapp. Taken from the MANIFEST.MF file (inside the jar/war file).
components.health.details.version The release version fo the webapp. Taken from the MANIFEST.MF (inside the jar/war file).
components.health.details.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).
components.health.details.startTime Webapp startup date and time (format yyyy-MM-dd'T'HH:mm:ss'Z')
components.health.details.currentTime Current server date and time (format yyyy-MM-dd'T'HH:mm:ss'Z')
components.link{number}.status (OPTIONAL) Represents the status of a link to the external system that the webapp depends on.
  • DOWN when the webapp does not respond (within a specified timeout limit - default 10 seconds) or the response is in invalid format (default Spring boot actuator /health endpoint format is expected).
  • UP if the service responds with HTTP status code 200 and returns a valid JSON object with status "UP"
components.link{number}.details.name (OPTIONAL) Descriptive name for the link to the external system

Sample response:

{
    "status": "UP",
    "components": {
        "health": {
            "details": {
               "webappName":"siva-sample-application",
                "version":"3.3.0",
                "buildTime":"2016-10-21T15:56:21Z",
                "startTime":"2016-10-21T15:57:48Z",
                "currentTime":"2016-10-21T15:58:39Z"
            },
            "status": "UP"
        },
        "link1": {
            "details": {
                "name": "sivaService"
            },
            "status": "UP"
        }
    }
}

Simplified health monitoring

SiVa webapps provide a simple interface for external monitoring tools (to periodically check the generic service health status).

The request

The simplified monitoring endpoint is accessible via HTTP GET at /monitoring/heartbeat url.

Sample request:

GET https://<server url>/monitoring/heartbeat

The response

As a response, a JSON object is returned with the following information:

Field Description
status General status of the webapp.
Possible values:
  • DOWN - when the webapp or any of its dependencies down.
  • UP - the default value.

Sample response:

{
    "status": "UP"
}

Version information

SiVa webapps provide a simple interface for querying the application version information.

The request

The version information endpoint is accessible via HTTP GET at /monitoring/version url.

Sample request:

GET https://<server url>/monitoring/version

The response

As a response, a JSON object is returned with the following information:

Field Description
version Version string of the webapp

Sample response:

{
    "version": "3.5.0"
}

Changes in API compared to V3 v3.4.0

Changes are described using notation from REST endpoint.

New endpoints

Endpoint HTTP Method Link Comment
/monitoring/heartbeat GET Link New monitoring endpoint
/monitoring/version GET Link New monitoring endpoint

Changes in API compared to V3 v3.3.0

Changes are described using notation from REST endpoint.

Changes in response

Report Parameter Change Link Comment
validationConclusion signatures[0].info.timestampCreationTime Parameter added Link Date containing timestamp creation time added
validationConclusion signatures[0].info.ocspResponseCreationTime Parameter added Link Date containing OCSP response creation time added
validationConclusion signatures[0].info.signingReason Parameter added Link String containing signing reason for PAdES added

Changes in API compared to V3 v3.2.0 (non breaking additions to protocol)

Changes are described using notation from REST endpoint.

Changes in response

Report Parameter Change Link Comment
validationConclusion signatures[0].signatureMethod Parameter added Link Used signature method is now returned
validationConclusion signatures[0].info.timeAssertionMessageImprint Parameter added Link Base64 encoded value of message imprint retrieved from time assertion. In case of LT_TM (TimeMark) signatures, OCSP nonce value is returned. In case of T, LT or LTA (TimeStamp) signatures, TimeStamp message imprint is returned.
validationConclusion signatures[0].info.signatureProductionPlace Parameter added Link Object containing optional signing location info added
validationConclusion signatures[0].info.signerRole Parameter added Link Array containing optional signer roles added
validationConclusion signatures[0].certificates Parameter added Link Array containing certificates that are present in the signature or in TSL.

Changes in API compared to V2

Changes are described using notation from REST endpoint.

Changes in request

Endpoint Parameter Change Link Comment
/validateDocument reportType parameter added Link Diagnostic report type added
/validateHashcode whole request request changed Link Request changed to support validation of multiple signatures with one request

Changes in response

Response type Parameter Change Link Comment
Simple validatedDocument now optional Link Object now optional
Simple validatedDocument.filename now optional Link String now optional
Simple validatedDocument.fileHash changed Link Previously validatedDocument.fileHashInHex. Now contains Base64 value
Simple signatures[0].subjectDistinguishedName.serialNumber added Link Added signers serial number field
Simple signatures[0].subjectDistinguishedName.commonName added Link Added signers common name field
Simple signatures[0].subjectDistinguishedName.givenName added Link Added signers given name from SubjectDistinguishedName field
Simple signatures[0].subjectDistinguishedName.surname added Link Added signers surname from SubjectDistinguishedName field
Simple signatures[0].signatureScopes[0].hashAlgo added Link Added datafile hash algo field for hashcode validation
Simple signatures[0].signatureScopes[0].hash added Link Added datafile hash field for hashcode validation
Diagnostic whole response added Link New report type added