Skip to content

Datafiles API description

Jump to bottom
Juku Trump edited this page May 6, 2024 · 18 revisions

Introduction

This document describes the methods used for datafile container manipulation.

Contents

1. 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"
}

2. 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"
}

3. 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"
}

4. 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="
    }
  ]
}

5. 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"
}

6. Remote signing

6.1 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 value LT - TimeStamp based signature.
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"
}

6.2 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"
}

7. Mobile-ID signing

7.1. 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 value LT - TimeStamp based signature.
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

7.2 Request Mobile-ID signing status

Method for requesting status of the signing process (signer to enter a PIN on the mobile device). This method should be polled with interval while the status is OUTSTANDING_TRANSACTION in all other statuses polling should be stopped.

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"
}

8. Smart-ID signing

8.1 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"
}

8.2 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 request should be polled with interval while the status is OUTSTANDING_TRANSACTION, in all other statuses polling should be stopped.

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.

8.3 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 value LT - TimeStamp based signature.
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"
}

8.4 Request Smart-ID signing status

Method for requesting status of the signing process.

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.

9. 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"
    }
  ]
}

10. 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
Type
Mandatory
Description






validationConclusion
Object
+
Check SIVA validationConclusion block







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
Type
Mandatory
Description






validationConclusion
Object
+
Object containinig validation information




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[].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 (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		




validationConclusion.signatures
Array
-
Collection of signatures found in digitally signed document




validationConclusion.signatures[].claimedSigningTime
Date
+
Claimed signing time, i.e. signer`s computer time during signature creation




validationConclusion.signatures[].id
String
+
Signature ID attribute




validationConclusion.signatures[].indication
String
+
Overall result of the signatures validation process, according to [ETSI EN 319 102-1](http://www.etsi.org/deliver/etsi_en/319100_319199/31910201/01.01.01_60/en_31910201v010101p.pdf) "Table 5: Status indications of the signature validation process". <br> Note that the validation results of different signatures in one signed document (signature container) may vary. <br> See also validSignaturesCountandSignaturesCount` fields. 
Possible values: 
 TOTAL-PASSED 
 TOTAL-FAILED 
 INDETERMINATE		




validationConclusion.signatures[].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[].errors
Array
-
Information about validation error(s), array of error messages.




validationConclusion.signatures[].errors[].content
String
+
Error message, as returned by the base library that was used for signature validation.




validationConclusion.signatures[].info
Object
-
Object containing trusted signing time information.




validationConclusion.signatures[].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[].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[].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.		




validationConclusion.signatures[].signedBy
String
+
Signers name and identification number, i.e. value of the CN field of the signer`s certificate




validationConclusion.signatures[].subjectDistinguishedName
Object
-
Object containing subject`s distinguished name information.




validationConclusion.signatures[].subjectDistinguishedName.serialNumber
String
+
SERIALNUMBER value portion in signers certificates subject distinguished name




validationConclusion.signatures[].subjectDistinguishedName.commonName
String
+
CN (common name) value portion in signers certificates subject distinguished name




validationConclusion.signatures[].signatureScopes
Array
-
Contains information of the original data that is covered by the signature.




validationConclusion.signatures[].signatureScopes[].name
String
+
Name of the signature scope.




validationConclusion.signatures[].signatureScopes[].scope
String
+
Type of the signature scope.




validationConclusion.signatures[].signatureScopes[].content
String
+
Description of the scope.




validationConclusion.signatures[].warnings
Array
-
Validation warnings that do not affect the overall validation result.




validationConclusion.signatures[].warnings[].content
String
+
Warning description, as retuned by the base library that was used for validation.






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






Error responses






Parameter
Type
Mandatory
Description






errorCode
String
+
Error code




errorMessage
String
+
Error description






              


          



  
          

            

              

                

                  

                    
1. Introduction

2. Authorization

3. Hashcode main usage flows

4. Hashcode container form

5. Hashcode API description

6. Datafiles API description

7. Best practices

8. Roadmap


                  

                

              


            
Clone this wiki locally