Datafiles API description

Introduction

This document describes the methods used for datafile container manipulation.

Contents

• Introduction
• Creating a container
• Upload container
• Add datafiles to unsigned container
• Get data files list
• Delete datafile from unsigned container
• Remote signing
  • Start remote signing
  • Finalize remote signing
• Mobile-ID signing
  • Start Mobile-ID signing
  • Request Mobile-ID signing status
• Smart-ID signing
  • Trigger certificate selection for Smart-ID signing
  • Request certificate selection status
  • Start Smart-ID signing
  • Request Smart-ID signing status
• Request signature list of given container
• Request signer info on given signature
• Request validation of container in session
• Request validation of container without session
• Request container
• Delete container
• Augment container
• Error responses

Creating a container

Method for creating container structure. The default size limit of the request (not just the data file!) is 4 MB.

Method	URL
POST	/containers

Request parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
dataFiles	Array	+	Array containing dataFile objects.
dataFiles[].fileName	String	+	Name of the data file. Limitations: Folder structure for data files is not supported. Length must be between 1 and 260 characters; Must contain at least 1 character which is not whitespace; Must not contain any of the following characters: /, ', ?, *, \, <, >, |, ", :.
dataFiles[].fileContent	String	+	Base64 encoded data file content.

Example request:

{
    "containerName": "containerTest.asice",
    "dataFiles": [
        {
            "fileName": "testFile.txt",
            "fileContent": "dGVzdGZhaWw="
        }
    ]
}

Response parameters

Parameter	Type	Mandatory	Description
containerId	String	+	Container ID that is used to identify the container in use.

Example response

{
  "containerId": "72aae27c-540d-4324-9dd9-6732b2bc8252"
}

Upload container

Method for uploading datafile container.

Method	URL
POST	/upload/containers

Request parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
container	String	+	Base64 encoded container.

Example request:

{
  "containerName": "container.asice",
  "container": "RnKZobNWVy8u92sDL4S2j1BUzMT5qTgt6hm90TfAGRo="
}

Response parameters

Parameter	Type	Mandatory	Description
containerId	String	+	Container ID that is used to identify the container in use.

Example response

{
  "containerId": "72aae27c-540d-4324-9dd9-6732b2bc8252"
}

Add datafiles to unsigned container

Method for adding data files to container. NB! It is possible to add data files only to unsigned container!

Method	URL
POST	/containers/{containerId}/datafiles

Request parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	-	Array containing dataFile objects.
dataFiles[].fileName	String	+	Name of the data file. Limitations: Folder structure for data files is not supported. Length must be between 1 and 260 characters; Must contain at least 1 character which is not whitespace; Must not contain any of the following characters: /, ', ?, *, \, <, >, |, ", :.
dataFiles[].fileContent	String	+	Base64 encoded data file content.

Example request:

{
    "dataFiles": [
        {
            "fileName": "testFile.txt",
            "fileContent": "dGVzdGZhaWw="
        }
    ]
}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK on success.

Example response

{
  "result": "OK"
}

Get data files list

Method for retrieving container data file list.

Method	URL
GET	/containers/{containerId}/datafiles

Response parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	-	Array containing dataFile objects.
dataFiles[].fileName	String	+	Name of the data file.
dataFiles[].fileContent	String	+	Base64 encoded data file content.

Example response

{
  "dataFiles": [
    {
      "fileName": "testFile.txt",
      "fileContent": "dGVzdGZhaWw="
    }
  ]
}

Delete datafile from unsigned container

Method for deleting data files from container. NB! It is possible to remove data files only from unsigned container!

Method	URL
DELETE	/containers/{containerId}/datafiles/{datafileName}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK on success.

Example response

{
  "result": "OK"
}

Remote signing

Start remote signing

Method for generating data to be signed externally

Method	URL
POST	/containers/{containerId}/remotesigning

Request parameters

Parameter	Type	Mandatory	Description
signingCertificate	String	+	DER encoded X.509 signers certificate in Base64.
signatureProfile	String	+	Profile of the signature. Available values are LT (timestamp with OCSP response) and LTA (LT profile with added data for long-term integrity validation).
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Example request:

{
    "signingCertificate": "MIID..",
    "signatureProfile": "LT"
}

Response parameters

Parameter	Type	Mandatory	Description
generatedSignatureId	String	+	Signature ID needed for finalization of signature.
dataToSign	String	+	Data to be signed on client side. XML structure to be signed encoded in Base64.
digestAlgorithm	String	+	Digest algorithm used to calculate dataToSign. Service uses SHA512.

{
    "generatedSignatureId": "5df71690-dc2a-4906-8ceb-f5e7b3036ce3",
    "dataToSign": "PGRz...",
    "digestAlgorithm": "SHA512"
}

Finalize remote signing

Method for returning signature value to service

Method	URL
PUT	/containers/{containerId}/remotesigning/{generatedSignatureId}

Request parameters

Parameter	Type	Mandatory	Description
signatureValue	String	+	Signature value created by client encoded in Base64. Signature must be created using the algorithm returned in POST /containers/{containerId}/remotesigning response (SHA512).

{
    "signatureValue": "MGQC..."
}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK is returned.

{
    "result": "OK"
}

Mobile-ID signing

Start Mobile-ID signing

Method for starting Mobile-ID signing of container

Method	URL
POST	/containers/{containerId}/mobileidsigning

Request parameters

Parameter	Type	Mandatory	Description
personIdentifier	String	+	Signers personal national identification code.
phoneNo	String	+	Signers phone number with +372 prefix.
language	String	+	Language for user dialog in mobile phone. 3-character capitalized acronyms are used. Possible values: ENG, EST, RUS, LIT.
messageToDisplay	String	-	Text displayed in addition to ServiceName and before asking PIN2. Maximum length is 40 bytes. In case of Latin letters, this means also a 40 character long text, but Cyrillic characters may be encoded by two bytes and you will not be able to send more than 20 symbols.
signatureProfile	String	+	Profile of the signature. Available values are LT and LTA - TimeStamp based signatures.
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Example request

{
    "signatureProfile": "LT",
    "personIdentifier": "60001019906",
    "language": "EST",
    "messageToDisplay": "Test",
    "phoneNo": "+37200000766"
}

Response parameters

Parameter	Type	Mandatory	Description
generatedSignatureId	String	+	Signature ID needed for finalization of signature.
challengeId	String	+	4-character control code calculated on basis of the Challenge value to be signed. This code is displayed on mobile phone's screen and must be also displayed by integrating web service in order to ensure the user on authenticity of the query.

Example response:

{
    "generatedSignatureId": "81b1c675-abc7-4752-9ee2-89d80b3ab7ef",
    "challengeId": "3664"
}

In case of not MID user and revoked/suspended certificate error is returned.

For testing in Demo environment TEST Mobile-ID number can be found here

Request Mobile-ID signing status

Method for requesting status of the signing process (signer to enter a PIN on the mobile device). This method must be polled with a delay (read "Prevent spamming") while the status is OUTSTANDING_TRANSACTION. Polling should be stopped for all other statuses.

Method	URL
GET	/containers/{containerId}/mobileidsigning/{generatedSignatureId}/status

Response parameters

Parameter	Type	Mandatory	Description
midStatus	String	+	SIGNATURE – signature was successfully created; OUTSTANDING_TRANSACTION – signing is still on the way, the status query shall be repeated; EXPIRED_TRANSACTION – service timed out before user managed to complete the signing; USER_CANCEL – the user refused or cancelled the signing process; MID_NOT_READY – the Mobile-ID of the SIM is not yet ready for the operations; INTERNAL_ERROR – technical error. NOT_VALID - signature is not valid SENDING_ERROR – other error when sending message (phone is incapable of receiving the message, error in messaging server etc.); SIM_ERROR – SIM application error; PHONE_ABSENT – phone is switched off or out of coverage;

Example response:

{
    "midStatus": "SIGNATURE"
}

Smart-ID signing

Trigger certificate selection for Smart-ID signing

Smart-ID users may have several active accounts (devices) for signing. These accounts are identified by unique documentNumber which is tied to specific certificate. This endpoint is used to trigger device selection prompt on user devices. When user selects device, certificate is retrieved for signing. In case user has only one active account, no prompt is given to user and certificate is retrieved immediately.

NB! Only certificates with QSCD level are accepted.

See Smart-ID documentation for additional information.

If Smart-ID documentNumber was received in some other way (e.g by authentication process) then certificate selection step can be omitted.

Method	URL
POST	/containers/{containerId}/smartidsigning/certificatechoice

Request parameters

Parameter	Type	Mandatory	Description
personIdentifier	String	+	Signers personal national identification code.
country	String	+	Signers country of residence. 2 character ISO 3166-1 alpha-2 country code.

{
  "country": "EE",
  "personIdentifier": "30303039914"
}

Response parameters

Parameter	Type	Mandatory	Description
generatedCertificateId	String	+	Certfificate id required to poll the status.

{
    "generatedCertificateId": "4acd9982-21c6-4626-a4fe-9e544fe2e981"
}

Request certificate selection status

Method for requesting status of the certificate selection process. In case of multiple Smart-ID accounts user has around 90 seconds to choose correct device before timeout is given. This method must be polled with a delay (read "Prevent spamming") while the status is OUTSTANDING_TRANSACTION. Polling should be stopped for all other statuses.

Method	URL
GET	/containers/{containerId}/smartidsigning/certificatechoice/{generatedCertificateId}/status

Response parameters

Parameter	Type	Mandatory	Description
sidStatus	String	+	CERTIFICATE – User has chosen the device to be used OUTSTANDING_TRANSACTION – certificate selection is still on the way, the status query shall be repeated; EXPIRED_TRANSACTION – service timed out before user managed to complete the selection; USER_CANCEL – the user refused or cancelled the process; DOCUMENT_UNUSABLE – signing can not be completed;
documentNumber	String	-	Value is present in case of CERTIFICATE sidStatus. This number is used to initiate signing process in device selected by user.

Example response

{
  "sidStatus": "CERTIFICATE",
  "documentNumber": "PNOEE-30303039914-MOCK-Q"
}

In case of not Smart-ID user and revoked/suspended certificate, error is returned.

Start Smart-ID signing

Method for starting Smart-ID signing of container.

Method	URL
POST	/containers/{containerId}/smartidsigning/

Request parameters

Parameter	Type	Mandatory	Description
documentNumber	String	+	Document number identifying device selected by user. If Smart-ID was used for authentication then this number can be received from authentication process and certificate choice step in signing can be skipped.
messageToDisplay	String	-	Text displayed in addition to ServiceName. Maximum length is 60 characters.
signatureProfile	String	+	Profile of the signature. Available values are LT and LTA - TimeStamp based signatures.
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	Object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Example request:

{
    "documentNumber": "PNOEE-30303039914-MOCK-Q",
    "signatureProfile": "LT",
    "messageToDisplay": "Test"
}

Response parameters

Parameter	Type	Mandatory	Description
generatedSignatureId	String	+	Signature ID needed for finalization of signature.
challengeId	String	+	4-character control code calculated on basis of the Challenge value to be signed. This code is displayed on device screen and must be also displayed by integrating web service in order to ensure the user on authencity of the query.

Example response:

{
    "generatedSignatureId": "b5b68c92-6243-4d92-851f-89bb9ce64c3e",
    "challengeId": "6702"
}

Request Smart-ID signing status

Method for requesting status of the signing process. This method must be polled with a delay (read "Prevent spamming") while the status is OUTSTANDING_TRANSACTION. Polling should be stopped for all other statuses.

Method	URL
GET	/containers/{containerId}/smartidsigning/{generatedSignatureId}/status

Response parameters

Parameter	Type	Mandatory	Description
sidStatus	String	+	SIGNATURE – signature was successfully created; OUTSTANDING_TRANSACTION – user has not entered PIN2, the status query shall be repeated; EXPIRED_TRANSACTION – service timed out before user managed to complete the signing; USER_CANCEL – the user refused or cancelled the signing process or verification code selection; DOCUMENT_UNUSABLE – signing can not be completed; USER_SELECTED_WRONG_VC – wrong verification code selected by the user; NOT_SUPPORTED_BY_APP – the requested action is not supported by user`s Smart-ID app;

Example response:

{
    "sidStatus": "SIGNATURE"
}

In case of not Smart-ID user and revoked/suspended certificate, error is returned. This should not happen as this status should be received in certificate choice process or in authentication.

Request signature list of given container

Method for returning all the signers of the container.

Method	URL
GET	/containers/{containerId}/signatures

Response parameters

Parameter	Type	Mandatory	Description
signatures	Array	-	Array of signature objects.
signatures[].id	String	+	Signature id taken from signature.
signatures[].generatedSignatureId	String	+	Unique signature id generated by the service to enable manipulation of signatures.
signatures[].signerInfo	String	+	Signers certificate DN field. Example "SERIALNUMBER=PNOEE-38001085718, GIVENNAME=JAAK-KRISTJAN, SURNAME=JÕEORG, CN="JÕEORG,JAAK-KRISTJAN,38001085718", C=EE".
signatures[].signatureProfile	String	+	Signature profile.

Example response:

{
  "signatures": [
    {
      "id": "id-d6194c14681afa58fbd521780f6ceb1b",
      "generatedSignatureId": "208d667a-816e-4309-be6a-36dcebc30602",
      "signerInfo": "SERIALNUMBER=PNOEE-38001085718, GIVENNAME=JAAK-KRISTJAN, SURNAME=JÕEORG, CN=\"JÕEORG,JAAK-KRISTJAN,38001085718\", C=EE",
      "signatureProfile": "LT"
    }
  ]
}

Request signer info on given signature

Method of returning information on a specific signer of the container.

Method	URL
GET	/containers/{containerId}/signatures/{generatedSignatureId}

Response parameters

Parameter	Type	Mandatory	Description
id	String	+	Signature id taken from signature
signerInfo	String	+	Signers certificate DN field. Example "SERIALNUMBER=PNOEE-38001085718, GIVENNAME=JAAK-KRISTJAN, SURNAME=JÕEORG, CN="JÕEORG,JAAK-KRISTJAN,38001085718", C=EE".
signatureProfile	String	+	Signature profile.
ocspCertificate	String	-	Certificate of OCSP provider.
timeStampTokenCertificate	String	-	Certificate of timestamp provider.
ocspResponseCreationTime	String	-	OCSP creation time.
timeStampCreationTime	String	-	Timestamp creation time.
trustedSigningTime	String	-	Time considered as trusted signature creation time. Can be either timestamp or OCSP time, depending on signature profile.
signingCertificate	String	+	Signers certificate.
claimedSigningTime	String	+	Computer time on signature creation. This is not trusted signing time!
roles	Array	-	Array of strings describing the signer role.
signatureProductionPlace	object	-	Object containing signing location.
signatureProductionPlace.countryName	String	-	Signing country.
signatureProductionPlace.city	String	-	Signing city.
signatureProductionPlace.stateOrProvince	String	-	Signing state or province.
signatureProductionPlace.postalCode	String	-	Signing postal code.

Example response:

Request validation of container in session

Method for retrieving validation report (simple report from SIVA service is returned).

Method	URL
GET	/containers/{containerId}/validationreport

Response parameters

Parameter	Mandatory	Type	Description
validationConclusion.policy	+	Object	Object containing information of the SiVa signature validation policy that was used for validation.
validationConclusion.policy.policyName	+	String	Name of the validation policy
validationConclusion.policy.policyDescription	+	String	Short description of the validation policy.
validationConclusion.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.
validationConclusion.signaturesCount	+	Number	Number of signatures found inside digitally signed file.
validationConclusion.validSignaturesCount	+	Number	Signatures count that have validated to TOTAL-PASSED. See also Signature.Indication field.
validationConclusion.validationLevel	-	Date	Validation process against what the document is validated, only applicable on DSS based validations. Possible values: ARCHIVAL_DATA
validationConclusion.validationTime	+	Date	Time of validating the signature by the service.
validationConclusion.validationWarnings	-	Array	Array of SiVa validation warnings that do not affect the overall validation result. See also signatures.warnings parameter.
validationConclusion.validationWarnings[0]	+	Object	Object containing the warning.
validationConclusion.validationWarnings[0].content	+	String	Description of the warning.
validationConclusion.validatedDocument	-	Object	Object containing information about validated document.
validationConclusion.validatedDocument.filename	-	String	Digitally signed document's file name. Not present for hashcode validation.
validationConclusion.validatedDocument.fileHash	-	String	Calculated hash for validated document in Base64. Present when report signing is enabled.
validationConclusion.validatedDocument.hashAlgo	-	String	Hash algorithm used. Present when report signing is enabled.
validationConclusion.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 (and BDOC) documents ASiC-S - used in case of all ASiC-S documents
validationConclusion.signatures	-	Array	Collection of signatures found in digitally signed document
validationConclusion.signatures[0]	+	Object	Signature information object
validationConclusion.signatures[0].claimedSigningTime	+	Date	Claimed signing time, i.e. signer's computer time during signature creation
validationConclusion.signatures[0].id	+	String	Signature ID attribute
validationConclusion.signatures[0].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
validationConclusion.signatures[0].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"
validationConclusion.signatures[0].errors	-	Array	Information about validation error(s), array of error messages.
validationConclusion.signatures[0].errors[0]	+	Object	Object containing the error
validationConclusion.signatures[0].errors[0]. content	+	String	Error message, as returned by the base library that was used for signature validation.
validationConclusion.signatures[0].info	-	Object	Object containing trusted signing time information and user added additional signing info.
validationConclusion.signatures[0].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.
validationConclusion.signatures[0].info.archiveTimestamps	-	Array	Array containing archive time-stamp tokens if present.
validationConclusion.signatures[0].info.archiveTimestamps[0].signedTime	+	String	Time when the archive time-stamp token was created.
validationConclusion.signatures[0].info.archiveTimestamps[0].indication	+	String	Result of the archive time-stamp token validation. Possible values: PASSED FAILED NO_SIGNATURE_FOUND
validationConclusion.signatures[0].info.archiveTimestamps[0].subIndication	-	String	Additional subindication in case of failed or indeterminate validation result.
validationConclusion.signatures[0].info.archiveTimestamps[0].signedBy	+	String	Signer of the archive time-stamp token.
validationConclusion.signatures[0].info.archiveTimestamps[0].country	+	String	Issuer country of the archive time-stamp token.
validationConclusion.signatures[0].info.archiveTimestamps[0].content	+	String	Archive time-stamp token encoded in base64.
validationConclusion.signatures[0].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
validationConclusion.signatures[0].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
validationConclusion.signatures[0].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.
validationConclusion.signatures[0].subjectDistinguishedName	-	Object	Object containing subject's distinguished name information.
validationConclusion.signatures[0].subjectDistinguishedName.serialNumber	-	String	SERIALNUMBER value portion in signer's certificate's subject distinguished name
validationConclusion.signatures[0].subjectDistinguishedName.commonName	-	String	CN (common name) value portion in signer's certificate's subject distinguished name
validationConclusion.signatures[0].signatureScopes	-	Array	Contains information of the original data that is covered by the signature.
validationConclusion.signatures[0].signatureScopes[0].name	+	String	Name of the signature scope.
validationConclusion.signatures[0].signatureScopes[0].scope	+	String	Type of the signature scope.
validationConclusion.signatures[0].signatureScopes[0].content	+	String	Description of the scope.
validationConclusion.signatures[0].warnings	-	Array	Block of validation warnings that do not affect the overall validation result.
validationConclusion.signatures[0].warnings[0]	+	Object	Object containing the warning
validationConclusion.signatures[0].warnings[0].content	+	String	Warning description, as returned by the base library that was used for validation.
validationConclusion.timeStampTokens	-	Array	Array containing the time stamp tokens
validationConclusion.timeStampTokens[0]	+	Object	Object containing the time stamp token (TST)
validationConclusion.timeStampTokens[0].indication	+	String	Result of the time stamp token validation. Possible values: TOTAL-PASSED TOTAL-FAILED
validationConclusion.timeStampTokens[0].subIndication	-	String	Additional subindication in case of failed or indeterminate validation result.
validationConclusion.timeStampTokens[0].timestampLevel	-	String	Legal level of the timestamp. - Possible values: QTSA TSA N/A
validationConclusion.timeStampTokens[0].signedBy	+	String	Signer of the time stamp token.
validationConclusion.timeStampTokens[0].signedTime	+	String	Time when the time stamp token was given.
validationConclusion.timeStampTokens[0].warning	-	Array	Array of validation warnings that do not affect the overall validation result.
timeStampTokens[0].warning[0]	+	Object	Object containing the warning.
timeStampTokens[0].warning[0].content	+	String	Warning description.
validationConclusion.timeStampTokens[0].errors	-	Array	Errors returned in time stamp token validation.
validationConclusion.timeStampTokens[0].errors[0]	+	Object	Object containing the error.
validationConclusion.timeStampTokens[0].errors[0].content	+	String	Error description.
validationConclusion.timeStampTokens[0].certificates	+	Array	Array containing certificates that are present in the timestamp.
timeStampTokens[0].certificates[0]	+	Object	Object containing certificate type, common name and certificate.
timeStampTokens[0].certificates[0].commonName	+	String	CN (common name) value in certificate.
timeStampTokens[0].certificates[0].type	+	String	Type of the certificate. Possible value is CONTENT_TIMESTAMP.
timeStampTokens[0].certificates[0].content	+	String	DER encoded X.509 certificate in Base64.
timeStampTokens[0].timestampScopes	-	Array	Contains information of the original data that is covered by the timestamp.
timeStampTokens[0].timestampScopes[0]	+	Object	Object containing the timestamp scope.
timeStampTokens[0].timestampScopes[0].name	+	String	Name of the timestamp scope.
timeStampTokens[0].timestampScopes[0].scope	+	String	Type of the timestamp scope.
timeStampTokens[0].timestampScopes[0].content	+	String	Description of the timestamp scope.
timeStampTokens[0].timestampScopes[0].hashAlgo	-	String	Hash algorithm used.
timeStampTokens[0].timestampScopes[0].hash	-	String	Calculated hash for the timestamp in Base64.

Request validation of container without session

Method for validating a container.

Method	URL
POST	/containers/validationreport

Request parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
container	String	+	Base64 encoded container. ASIC-E, BDOC and DDOC forms are supported.

Response parameters

Parameter	Mandatory	Type	Description
validationConclusion.policy	+	Object	Object containing information of the SiVa signature validation policy that was used for validation.
validationConclusion.policy.policyName	+	String	Name of the validation policy
validationConclusion.policy.policyDescription	+	String	Short description of the validation policy.
validationConclusion.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.
validationConclusion.signaturesCount	+	Number	Number of signatures found inside digitally signed file.
validationConclusion.validSignaturesCount	+	Number	Signatures count that have validated to TOTAL-PASSED. See also Signature.Indication field.
validationConclusion.validationLevel	-	Date	Validation process against what the document is validated, only applicable on DSS based validations. Possible values: ARCHIVAL_DATA
validationConclusion.validationTime	+	Date	Time of validating the signature by the service.
validationConclusion.validationWarnings	-	Array	Array of SiVa validation warnings that do not affect the overall validation result. See also signatures.warnings parameter.
validationConclusion.validationWarnings[0]	+	Object	Object containing the warning.
validationConclusion.validationWarnings[0].content	+	String	Description of the warning.
validationConclusion.validatedDocument	-	Object	Object containing information about validated document.
validationConclusion.validatedDocument.filename	-	String	Digitally signed document's file name. Not present for hashcode validation.
validationConclusion.validatedDocument.fileHash	-	String	Calculated hash for validated document in Base64. Present when report signing is enabled.
validationConclusion.validatedDocument.hashAlgo	-	String	Hash algorithm used. Present when report signing is enabled.
validationConclusion.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 (and BDOC) documents ASiC-S - used in case of all ASiC-S documents
validationConclusion.signatures	-	Array	Collection of signatures found in digitally signed document
validationConclusion.signatures[0]	+	Object	Signature information object
validationConclusion.signatures[0].claimedSigningTime	+	Date	Claimed signing time, i.e. signer's computer time during signature creation
validationConclusion.signatures[0].id	+	String	Signature ID attribute
validationConclusion.signatures[0].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
validationConclusion.signatures[0].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"
validationConclusion.signatures[0].errors	-	Array	Information about validation error(s), array of error messages.
validationConclusion.signatures[0].errors[0]	+	Object	Object containing the error
validationConclusion.signatures[0].errors[0]. content	+	String	Error message, as returned by the base library that was used for signature validation.
validationConclusion.signatures[0].info	-	Object	Object containing trusted signing time information and user added additional signing info.
validationConclusion.signatures[0].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.
validationConclusion.signatures[0].info.archiveTimestamps	-	Array	Array containing archive time-stamp tokens if present.
validationConclusion.signatures[0].info.archiveTimestamps[0].signedTime	+	String	Time when the archive time-stamp token was created.
validationConclusion.signatures[0].info.archiveTimestamps[0].indication	+	String	Result of the archive time-stamp token validation. Possible values: PASSED FAILED NO_SIGNATURE_FOUND
validationConclusion.signatures[0].info.archiveTimestamps[0].subIndication	-	String	Additional subindication in case of failed or indeterminate validation result.
validationConclusion.signatures[0].info.archiveTimestamps[0].signedBy	+	String	Signer of the archive time-stamp token.
validationConclusion.signatures[0].info.archiveTimestamps[0].country	+	String	Issuer country of the archive time-stamp token.
validationConclusion.signatures[0].info.archiveTimestamps[0].content	+	String	Archive time-stamp token encoded in base64.
validationConclusion.signatures[0].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
validationConclusion.signatures[0].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
validationConclusion.signatures[0].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.
validationConclusion.signatures[0].subjectDistinguishedName	-	Object	Object containing subject's distinguished name information.
validationConclusion.signatures[0].subjectDistinguishedName.serialNumber	-	String	SERIALNUMBER value portion in signer's certificate's subject distinguished name
validationConclusion.signatures[0].subjectDistinguishedName.commonName	-	String	CN (common name) value portion in signer's certificate's subject distinguished name
validationConclusion.signatures[0].signatureScopes	-	Array	Contains information of the original data that is covered by the signature.
validationConclusion.signatures[0].signatureScopes[0].name	+	String	Name of the signature scope.
validationConclusion.signatures[0].signatureScopes[0].scope	+	String	Type of the signature scope.
validationConclusion.signatures[0].signatureScopes[0].content	+	String	Description of the scope.
validationConclusion.signatures[0].warnings	-	Array	Block of validation warnings that do not affect the overall validation result.
validationConclusion.signatures[0].warnings[0]	+	Object	Object containing the warning
validationConclusion.signatures[0].warnings[0].content	+	String	Warning description, as returned by the base library that was used for validation.
validationConclusion.timeStampTokens	-	Array	Array containing the time stamp tokens
validationConclusion.timeStampTokens[0]	+	Object	Object containing the time stamp token (TST)
validationConclusion.timeStampTokens[0].indication	+	String	Result of the time stamp token validation. Possible values: TOTAL-PASSED TOTAL-FAILED
validationConclusion.timeStampTokens[0].subIndication	-	String	Additional subindication in case of failed or indeterminate validation result.
validationConclusion.timeStampTokens[0].timestampLevel	-	String	Legal level of the timestamp. - Possible values: QTSA TSA N/A
validationConclusion.timeStampTokens[0].signedBy	+	String	Signer of the time stamp token.
validationConclusion.timeStampTokens[0].signedTime	+	String	Time when the time stamp token was given.
validationConclusion.timeStampTokens[0].warning	-	Array	Array of validation warnings that do not affect the overall validation result.
timeStampTokens[0].warning[0]	+	Object	Object containing the warning.
timeStampTokens[0].warning[0].content	+	String	Warning description.
validationConclusion.timeStampTokens[0].errors	-	Array	Errors returned in time stamp token validation.
validationConclusion.timeStampTokens[0].errors[0]	+	Object	Object containing the error.
validationConclusion.timeStampTokens[0].errors[0].content	+	String	Error description.
validationConclusion.timeStampTokens[0].certificates	+	Array	Array containing certificates that are present in the timestamp.
timeStampTokens[0].certificates[0]	+	Object	Object containing certificate type, common name and certificate.
timeStampTokens[0].certificates[0].commonName	+	String	CN (common name) value in certificate.
timeStampTokens[0].certificates[0].type	+	String	Type of the certificate. Possible value is CONTENT_TIMESTAMP.
timeStampTokens[0].certificates[0].content	+	String	DER encoded X.509 certificate in Base64.
timeStampTokens[0].timestampScopes	-	Array	Contains information of the original data that is covered by the timestamp.
timeStampTokens[0].timestampScopes[0]	+	Object	Object containing the timestamp scope.
timeStampTokens[0].timestampScopes[0].name	+	String	Name of the timestamp scope.
timeStampTokens[0].timestampScopes[0].scope	+	String	Type of the timestamp scope.
timeStampTokens[0].timestampScopes[0].content	+	String	Description of the timestamp scope.
timeStampTokens[0].timestampScopes[0].hashAlgo	-	String	Hash algorithm used.
timeStampTokens[0].timestampScopes[0].hash	-	String	Calculated hash for the timestamp in Base64.

Request container

Method for retrieving the container.

Method	URL
GET	/containers/{containerId}

Response parameters

Parameter	Type	Mandatory	Description
containerName	String	+	Name of the container.
container	String	+	Base64 encoded container.

Delete container

Method for deleting container in use. This closes the active "session". It is recommended to delete container after usage as unclosed sessions may max out allowed connections count for the service.

Method	URL
DELETE	/containers/{containerId}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK is returned

Augment container

Method for augmenting container for long term archival (LTA). Depending on the container type and its contents, the resulting container may either:

• get an additional archival timestamp for every Estonian personal signature inside it (ASiC-E);
• be encapsulated into an ASiC-S container (ASiC-E / BDOC) - note that the file name in session will also change, because the extension becomes .asics;
• get an additional timestamp token (ASiC-S);
• not be augmented - if the container cannot be augmented, an error is thrown.

Method	URL
PUT	/containers/{containerId}/augmentation

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK is returned

Error responses

Parameter	Type	Mandatory	Description
errorCode	String	+	Error code
errorMessage	String	+	Error description