Hashcode API description

Introduction

This document describes the methods used for hashcode container manipulation.

Creating container

Method for creating container structure.

Method	URL
POST	/hashcodecontainers

Request parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	+	Array containing data file objects.
hashcodeDataFile	Object	+	Object containing data files information.
hashcodeDataFile[0].fileName	String	+	Name of the data file. Folder structure for data files is not supported.
hashcodeDataFile[0].fileHashSha256	String	+	SHA256 hash of the data file in Base64.
hashcodeDataFile[0].fileHashSha512	String	+	SHA512 hash of the data file in Base64.
hashcodeDataFile[0].fileSize	Integer	+	size of the file in bytes.

Response parameters

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

Upload container

Method for uploading hashcode container.

Method	URL
POST	/upload/hashcodecontainers

Request parameters

Parameter	Type	Mandatory	Description
container	String	+	Base64 encoded container.

Response parameters

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

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	/hashcodecontainers/{containerId}/datafiles

Request parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	+	Array containing data file objects.
hashcodeDataFile	Object	+	Object containing data files information.
hashcodeDataFile[0].fileName	String	+	Name of the data file. Folder structure for data files is not supported.
hashcodeDataFile[0].fileHashSha256	String	+	SHA256 hash of the data file in Base64.
hashcodeDataFile[0].fileHashSha512	String	+	SHA512 hash of the data file in Base64.
hashcodeDataFile[0].fileSize	Integer	+	size of the file in bytes.

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK on succes.

Get data files list

Method for retrieving container data file list.

Method	URL
GET	/hashcodecontainers/{containerId}/datafiles

Response parameters

Parameter	Type	Mandatory	Description
dataFiles	Array	+	Array containing data file objects.
hashcodeDataFile	Object	+	Object containing data files information.
hashcodeDataFile[0].fileName	String	+	Name of the data file.
hashcodeDataFile[0].fileHashSha256	String	+	SHA256 hash of the data file in Base64.
hashcodeDataFile[0].fileHashSha512	String	+	SHA512 hash of the data file in Base64.
hashcodeDataFile[0].fileSize	Integer	+	size of the file in bytes.

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	/hashcodecontainers/{containerId}/datafiles/{datafileName}

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK on success.

Start remote signing

Method for generating data to be signed externally

Method	URL
POST	/hashcodecontainers/{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 LT - TimeStamp based and LT_TM - TimeMark 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.

Response parameters

Parameter	Type	Mandatory	Description
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	String	+	Signature ID needed for finalization of signature.

Finalize remote signing

Method for returning signature value to service

Method	URL
PUT	/hashcodecontainers/{containerId}/remotesigning/{signatureId}

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 /hashcodecontainers/{containerId}/remotesigning response (SHA512).

Response parameters

Parameter	Type	Mandatory	Description
result	String	+	OK is returned.

Start Mobile-ID signing

Method for starting Mobile-ID signing of container

Method	URL
POST	/hashcodecontainers/{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.
signatureProfile	String	+	Profile of the signature. Available values LT - TimeStamp based and LT_TM - TimeMark based signatures.
roles	Array	-	Array of strings describing the signer role.
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.
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.

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 authencity of the query.

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

Method	URL
GET	/hashcodecontainers/{containerId}/mobileidsigning/{signatureId}/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 proces;

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;

|

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.

| POST | /hashcodecontainers/{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.

Response parameters

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

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	/hashcodecontainers/{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 proces;

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. |

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	/hashcodecontainers/{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 and before asking authentication PIN. 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 LT - TimeStamp based and LT_TM - TimeMark 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.

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.

Request Smart-ID signing status

Method for requesting status of the signing process.

Method	URL
GET	/hashcodecontainers/{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 proces;

DOCUMENT_UNUSABLE – signing can not be completed;

|

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 hashcode container

Method for returning all the signers of the container.

Method	URL
GET	/hashcodecontainers/{containerId}/signatures

Response parameters

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

Request signer info on given signature

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

Method	URL
GET	/hashcodecontainers/{containerId}/signatures/{signatureId}

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.

Request validation of hashcode container in session

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

NB! validation of LTA level signatures is not supported in hashcode form

Method	URL
GET	/hashcodecontainers/{containerId}/validationreport

Response parameters

Parameter	Type	Mandatory	Description
validationConclusion	Object	+	Object containing information of the validation conclusion.

Request validation of hashcode container without session

Method for validating a hashcode container.

Method	URL
POST	/hashcodecontainers/validationreport

Request parameters

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

Response parameters

Parameter	Type	Mandatory	Description
validationConclusion	Object	+	Object containinig validation information
policy	+	Object	Object containing information of the SiVa signature validation policy that was used for validation.
policy.policyName	+	String	Name of the validation policy
policy.policyDescription	+	String	Short description of the validation policy.
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	+	Number	Number of signatures found inside digitally signed file.
validSignaturesCount	+	Number	Signatures count that have validated to TOTAL-PASSED. See also Signature.Indication field.
validationLevel	-	Date	Validation process against what the document is validated, only applicable on DSS based validations. Possible values: ARCHIVAL_DATA
validationTime	+	Date	Time of validating the signature by the service.
validationWarnings	-	Array	Array of SiVa validation warnings that do not affect the overall validation result. See also signatures.warnings parameter.
validationWarnings[0] +	Object	Object containing the warning.
validationWarnings[0].content	+	String	Description of the warning.
validatedDocument	-	Object	Object containing information about validated document.
validatedDocument.filename	-	String	Digitally signed document's file name. Not present for hashcode validation.
validatedDocument.fileHash	-	String	Calculated hash for validated document in Base64. Present when report signing is enabled.
validatedDocument.hashAlgo	-	String	Hash algorithm used. Present when report signing is enabled.
signatureForm	-	String	Format (and optionally version) of the digitally signed document container. In case of documents in DIGIDOC-XML (DDOC) format, the "hashcode" suffix is used to denote that the container was validated in hashcode mode, i.e. without original data files. Possible values: DIGIDOC_XML_1.0 DIGIDOC_XML_1.0_hashcode DIGIDOC_XML_1.1 DIGIDOC_XML_1.1_hashcode DIGIDOC_XML_1.2 DIGIDOC_XML_1.2_hashcode DIGIDOC_XML_1.3 DIGIDOC_XML_1.3_hashcode ASiC_E - used in case of all ASIC-E (BDOC) documents and X-Road simple containers that don't use batch time-stamping (see specification document) ASiC_E_batchsignature - used in case of X-Road containers with batch signature (see specification document) ASiC_S - used in case of all ASIC-S documents
signatures	-	Array	Collection of signatures found in digitally signed document
signatures[0]	+	Object	Signature information object
signatures[0].claimedSigningTime	+	Date	Claimed signing time, i.e. signer's computer time during signature creation
signatures[0].id	+	String	Signature ID attribute
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
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"
signatures[0].errors	-	Array	Information about validation error(s), array of error messages.
signatures[0].errors[0]	+	Object	Object containing the error
signatures[0].errors[0].content	+	String	Error message, as returned by the base library that was used for signature validation.
signatures[0].info	-	Object	Object containing trusted signing time information.
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.
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
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 - In case of XROAD ASICE containers the value is missing as the asicverifier base library do not check the signature level.
signatures[0].signedBy	+	String	Signers name and identification number, i.e. value of the CN field of the signer's certificate
signatures[0].subjectDistinguishedName.serialNumber	-	String	SERIALNUMBER value portion in signer's certificate's subject distinguished name
signatures[0].subjectDistinguishedName.commonName	-	String	CN (common name) value portion in signer's certificate's subject distinguished name
signatures[0].signatureScopes	-	Array	Contains information of the original data that is covered by the signature.
signatures[0].signatureScopes[0].name	+	String	Name of the signature scope.
signatures[0].signatureScopes[0].scope	+	String	Type of the signature scope.
signatures[0].signatureScopes[0].content	+	String	Description of the scope.
signatures[0].signatureScopes[0].hashAlgo	-	String	Hash algorithm used for datafile hash calculation. Present for hashcode validation.
signatures[0].signatureScopes[0].hash	-	String	Hash of data file encoded in Base64. Present for hashcode validation.
signatures[0].warnings	-	Array	Block of validation warnings that do not affect the overall validation result.
signatures[0].warnings[0]	+	Object	Object containing the warning
signatures[0].warnings[0].content	+	String	Warning description, as retuned by the base library that was used for validation.

Request hashcode container

Method for retrieving the container.

Method	URL
GET	/hashcodecontainers/{containerId}

Response parameters

Parameter	Type	Mandatory	Description
container	String	+	Base64 encoded container.

Delete hashcode container

Method for deleting hashcode 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	/hashcodecontainers/{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