SK ID Solutions AS DigiDocService specification
Mobile-ID RESTAPI during
Especially when doing
new developments please use new REST API!Starting from June 2019 new customers are only allowed to use Mobile-ID REST API and will no longer granted an access to DigiDocService.
Mobile-ID REST API specificationyou can find here: https://github.com/SK-EID/MID/wiki
Table of contents
- Terms and Acronyms
- Suggestions and requirements for Application providers
- Main use cases
- Authentication API
- Digital Signature API
- Data structures
- Service Change History
DigiDoc is a SOAP-based web service enabling an easy integration for the functionality of digital signing, verifying signatures and authentication with other information systems.
The service is usable in different development environments and platforms featuring SOAP 1.0-encoded support.
Functionality of the service:
- Authentication with Mobile-ID
- Verification of certificate's validity (including any smartcard)
- Creation of DigiDoc/BDOC files
- Digital signing of DigiDoc/BDOC with Mobile-ID
- Digital signing of DigiDoc/BDOC with ID card (and other smartcards)
- Verification of digitally signed files (DigiDoc/BDOC) and validity of signatures
- Hash signing with Mobile-ID.
Access to the service is created on the basis of an IP address. A contract with SK ID Solutions AS needs to be signed for using the service. The price of using the DigiDocService depends on the number of signature and authentication queries per month and on the number of concurrent queries coming from one application.
DigiDocService supports DigiDoc container formats
DIGIDOC-XML 1.3 and
BDOC 2.1 with
time-marks. BDOC with
ASiC-E) format is supported since version 3.8 for
MobileCreateSignature method. Validation of BDOC-TS file format is supported starting from 3.9. Since 3.10 BDOC-TS is fully supported, i.e. support was added for following methods:
Older formats (
DIGIDOC-XML 1.1 and
DIGIDOC-XML 1.2) are only supported for verification (document container format is checked in the
If an inappropriate combination of given format and version number is used in request parameters, a SOAP error object with error message "Invalid format and version combination" will be returned.
Formats of digitally signed files
The format of the digitally signed file is based on ETSI TS 101 903 standard called "XML Advanced Electronic Signatures (XAdES)". This standard provides syntax for digital signatures with various levels of additional validity information.
In order to comply with the security model described above, the XAdES profile of "XAdES-X-L" is used in the DigiDoc system but "time-marks" are used i nstead of "time-stamps" – signing (and certificate validation) time comes with OCSP response.
- Allows for incorporating following signed properties
- Certificate used for signing
- Signing time
- Signature production place
- Signer role or resolution
- Incorporates full certificate validity information within the signature
- OCSP response
- OCSP responder certificate
As of result, it is possible to verify signature validity without any additional external information – the verifier should trust the issuer of signer's certificate and a OCSP responder certificate.
Original files (which were signed) along with the signature(s), validation confirmation(s) and certificates are encapsulated within container with "SignedDoc" being as a root element.
DigiDoc system uses file extension.
ddoc to distinguish digitally signed files according to the described file format.
Syntax of the
.ddoc files is described in the separate document  DigiDoc Format Specification in detail.
In addition starting from version 3.5 DigiDocService also supports BDOC 2.1 with__time-marks (BDOC-TM). BDOC with time-stamps (BDOC-TS, ASiC-E) format is supported since version 3.8 for using MobileCreateSignature method. Validation of BDOC-TS container format is supported starting from 3.9 and since 3.10 BDOC-TS is fully supported, i.e. added support for following methods: CreateSignedDoc, AddDataFile, RemoveDataFile, PrepareSignature, FinalizeSignature, MobileSign, RemoveSignature.
The description of BDOC file format is available in BDOC specification .
Starting from 2015 BDOC is default digital signature format in Estonia, therefore it's important to add BDOC file format support to your service. For more information about BDOC file format, please visit http://www.id.ee/?id=34336
Instructions for DigiDocService service users on how to migrate to BDOC format are available at id.ee website: http://www.id.ee/?lang=en&id=37072 .
DigiDocService supports signatures using the ECDSA (Elliptic Curve Digital Signature Algorithm) and RSA algorithms.
The service automatically chooses the appropriate algorithms for signing and authentication. To learn which algorithm is used in a particular case, application providers should inspect the certificate returned by the service.
ECDSA is currently only supported for Mobile-ID. If user's SIM card does not have ECDSA support, RSA algorithm is used. For DDOC file format only RSA is supported, BDOC format supports RSA and ECDSA.
A single signer can have multiple active certificates, each with a different signing algorithm. In such cases, DigiDocService chooses the most suitable certificate automatically.
The choice is based on following conditions:
- if user's SIM-card supports ECDSA, authentication (operation MobileAuthenticate) is always done using the ECDSA certificate.
- If user's SIM-card supports ECDSA and RSA, then ECDSA is used for signing BDOC files (operation MobileSign and MobileCreateSignature). As the DDOC file format does not support ECDSA, DDOC files are always signed using RSA.
For SIM cards that support both ECDSA and RSA the GetMobileCertificate method by default returns the ECDSA certificate; similarly, the MobileSignHash method chooses ECDSA. But starting from version 3.9 it is possible to request ECDSA (ECC) or RSA certificate.
RSA is commonly used with either 1024-bit or 2048-bit keys. ECDSA is implemented over the NIST P-256  curve and the signatures are encoded according to the XMLDSig specification  (i.e., two 256-bit integers appended to each other, zero-padded on the left if necessary; the result is then converted to Base64). The total raw ECDSA signature size is always 512 bits.
Terms and Acronyms
- Application Provider - Client of the DigiDocService, provides an application that uses digital signing, signature verification and/or authentication.
- Control Code - 4-digit number used in mobile authentication and mobile signing which is cryptographically linked with hash value to be signed. Control Code is displayed both in mobile phone and computer application in order to provide for authenticity of the signing request.
- Hash, Hash value - Data to be signed which is cryptographically derived from Datafiles and other parameters to be signed
- Mobile-ID - Service based on Wireless PKI providing for mobile authentication and digital signing. Mobile-ID user uses special SIM card with private keys on it. Hash to be signed is sent over the mobile network to the phone and the user shall enter PIN code to perform transaction. The signed result is sent back to the service.
- MSSP - Mobile Signature Service Provider. Described in standard ETSI TS 102 204 .
- Original file, Datafile - File to be digitally signed. The file is in arbitrary file format
- Signing - Used in this case as „forming the digital signature" according to the Digital Signature Law. The procedure includes besides signing the validity confirmation request.
- Verification - Checking the validity of signatures of the digitally signed data.
- Transaction, session - Communication while a file (DigiDoc or the original data file) is forwarded to the web service and some operations related to these are followed, i.e. a DigiDoc is created out of the data file, then signed and returned to the application. After closing the transaction all the information created during the transaction is deleted from the service-server |
Main use cases
Verification of the digitally signed file
In need of verifying a digitally signed document the easiest way is to use the StartSession request (described in StartSession) valuing the SigDocXML parameter. If the only purpose is getting the overview of the content of DigiDoc and no further signing or certificate reading is intended, the StartSession request should be called with the parameter bHoldSession value set to false. In this case no further session closing is necessary. The StartSession request returns the signed document information as a structure of SignedDocInfo, where all the necessary parameters the signed document are readable.
If StartSession is called with parameter bHoldSession=true, after verifying it some additional requests about signed document will be possible:
to request the information about a data file (GetDataFile method)
to request the certificate of a certain signer (GetSignerCertificate method)
to request the validity confirmation response for a certain signature (GetNotary method)
-to request the validity confirmation signer's certificate of a certain signature (GetNotaryCertificate method)
If StartSession is called with parameter bHoldSession=true, further session closing will be necessary.
Mobile Signing in Asynchronous Client-Server mode
- Application provider sends the files for signing (DigiDoc files or original files) to DigiDoc Service within the StartSession request.
- As a result of the StartSession request also a created session identifier is returned, what should be used in the headers of following requests.
- The application sends a MobileSign request to start the signing process. If there's a will to sign more than one original file at a time, it's possible to add additional data files with AddDataFile method before sending the MobileSign request.
- DigiDocService forwards the signing request to MSSP service, which forwards it in turn to user's phone via a mobile operator.
- MSSP returns either an errorcode or an information about successful request.
- DigiDocService returns a response to the application with the MobileSign request. The response is either an errorcode or the information about the signing request.
- In asynchronous Client-Server mode the application should keep up sending a GetStatusInfo request to DigiDocService until signing process is either successful or unsuccessful.
- MSSP service sends a note about succeeding/unsucceeding. If signing is successful, also a signature will be sent to the DigiDocService.
- DigiDocService returns the information about receiving the signature to MSSP.
- After receiving the signature DigiDoc service sends a request about the user certificate's validity to the OCSP validity confirmation service.
- The validity confirmation service returns a signed validity confirmation response. A signature, which contains a signed hash and the validity confirmation service response is added to the DigiDoc file in session.
- Another GetSignedDocInfo request is sent by the Application Provider.
- DigiDocService returns GetStatusInfoResponse about success or failure of signing operation
- Application provider request information about document status using GetSignedDocInfo method
- DigiDocService responds to GetSignedDocInfo
- The application provider inquires the content of the signed DigiDoc with GetSignedDoc request.
- DigiDocService returns a DigiDoc file to the application. If the content of the data files is not sent to the service within the StartSession, the application that uses the service has to add it to the DigiDoc container itself.
- The application closes the session with sending a CloseSession request to the service.
- The Service returns the CloseSession response.
Signing with smartcard
The present example is based on the web-page enabling digital signing.
- User of the digital signing application has chosen a procedure that requires data signing. The user starts the signing procedure pressing the respective button or hyperlink in a company web service.
- The data meant to be signed will be sent to DigiDocService by StartSession request. A new session is initiated with that. Every session is connected to a (digitally signed) document. But every digitally signed document may contain plenty of original files.
An application sends to the service either
- a file to be signed
- the meta information and the hash of the file to be signed (the content of the file has been removed)
- the entire container to be signed
- the container to be signed without the bodi(es) of datafile(s) (all the content between the DataFile tags has been removed)
The ways of sending the data necessary for signing are described more precisely in StartSession. Data received within the StartSession request is saved in the session.
- SessionCode is returned to the application, what enables the following procedures with the session data.
- Before signing the application may add supplementary data files (AddDataFile request) or remove some datafiles (RemoveDataFile request) or carry out some other procedures with session data.
- After procedures the current session document information is returned.
- The certificate from the signer's smartcard together with other user inserted signature attributes is forwarded to the signing web-server.
- Signature parameters are forwarded to DigiDocService with PrepareSignature request.
- DigiDocService adds new signature information to the session document – signer's certificate and signature parameters and calculates the hash, what should be signed by the signer. The signed hash is sent to the application provider in PrepareSignature response.
- The hash to be signed together with the signing module is displayed to a user. The user presses the signing button on the webpage. As the result of that the signing module signs the hash (also asks for the PIN-code).
The created signature is set to the hidden field of the form and sent to the web-page which offers the signing functionality.
- The signature is forwarded to the signing web-server (application provider).
- The signature is forwarded to DigiDocService with FinalizeSignature request.
- DigiSocService makes a validity confirmation request about the validity of the signer's certificate to the OCSP validity service.
- OCSP validity confirmation server returns the validity confirmation of the signature.
- If the confirmation is positive (i.e. the signer's certificate is valid), SK web-service adds the entire information (the signature and the validity confirmation of the signer) to the creatable digital signature. From now on the digital signature is consistent added to the DigiDoc in session. DigiDocService returns the digital signing application the SignedDocInfo.
- Application asks for the content of the DigiDoc file with GetSignedDoc request.
- DigiDocService returns the current DigiDoc document which also contains the added signature.
- The user is informed about the happy end in digital signing. A digitally signed DigiDoc file is ready for download.
NB! In case that the content of the data file was not sent to servers within StartSession and AddDataFile requests (described in options b and d), it's necessary to add the bodies of data files to DigiDoc file received from the service. TheContentType has to be changed in
- The last step for the signing application is to close the session with CloseSession request. After that the service deletes all the data saved within the session.
Mobile authentication in asynchronous Client-Server mode
- The Application Provider sends data required for the authentication to DigiDocService using MobileAutheticate (personal identification code, text to be displayed, language)
- DigiDocService makes a validity confirmation request about the validity of the user's certificate to the OCSP service.
- OCSP validity confirmation server returns the validity confirmation of the certificate. If the certificate is valid, go to p. 4, otherwise to p. 6.
- An authentication request is sent to the user's mobile phone through the MSSP service.
- MSSP responses with information about successfulness of message delivery to the mobile phone
- If the certificate was valid and delivery of the authentication message through MSSP was successful, information about the end-user is returned to the Application provider. Otherwise, error message is returned.
- Application Provider will periodically query the Service with GetMobileAuthenticateStatus request. (Note: this is a case for Asynchronous Client-Server Mode; in other mode the Application Provider will just wait for information from the Service).
- DigiDocService in turn will query MSSP
- MSSP responses on status of the query
- Information about authentication status is forwarded to the Application Provider.
- 14 etc - this loop (7. 8. 9. 10.) goes on until positive answer or error message will arrive.
Authentication using smartcard
CheckCertificate method can be used as a part of authentication with ID-card, checking the validity of user authentication certificate (located on the smartcard).
Suggestions and requirements for Application providers
Application provider shall guarantee the following:
- According to the Digital Signature Act passed in the Estonian parliament, a digital signature solution must make it possible to: 1) unambiguously identify the person who owns the signing certificate;
2) identify the time of signing;
3) connect the digital signature with the signed data in a way that makes it impossible to undetectably change the signed data or its meaning after signing.
- The user is informed about the legal consequences of the digital signature before entering PIN2 (i.e., the PIN used for digital signatures).
- Measures are implemented to guarantee a single interpretation of signed data.
- The user shall have the possibility to be sure in the authenticity of the signed data and the attributes added to the signature (place of signing, role/resolution) should they be used.
- The data presented to the user before signing is in compliance with the actual data to be signed.
- The user shall have access to the digitally signed file which is created after the digital signing. Note that this applies to any operation that uses PIN2. For example, when signing online payments on a web site, the signer must be allowed to access the signed container after signing. This allows the signer to verify contents of the signed data.
Starting Mobile-ID operations
Mobile-ID operations (mobile authentication and mobile signing) can be started using DigiDocService methods:
- MobileSign and
All those methods accept Mobile-ID user's Personal Identification Code and phone number as input parameter.
If you would like to provide Mobile-ID operations for Lithuanian Mobile-ID users in your application then both input parameters are mandatory: user's Personal Identification Code and phone number. Otherwise the request fails.
NB! It is highly recommended to use both input parameters - Mobile-ID user's Personal Identification Code and phone number also for Estonian Mobile-ID users. The requirement is planned to be turned obligatory in the future.
Using only phone number is not recommended when security is a concern, because phone numbers are public and Mobile-ID users may get spammed.
Using both Personal Identification Code and phone number:
- When user makes a mistake when entering either his/her Personal Identification Code or phone number, it's very unlikely that Mobile-ID request will appear in another unintended Mobile-ID user's phone.
- Spamming is complicated because Personal Identification Codes are not public
- The user does not necessarily have to enter such data directly: for example, a user name could be tied to a particular combination of personal identification code and a phone number.
It's mandatory for application providers to prevent spamming (by IP-restrictions or by using input parameters mentioned above), otherwise SK ID Solutions AS must limit access to DigiDocService, to guarantee that DigiDocService stays up and running for other application providers that use it.
Application, that enables users to authenticate or digitally sign documents using Mobile-ID, must clearly present challenge number (ChallengeID parameter in MobileAuthenticate response, see below) to user and warn user to check if challenge number presented by application is the same as challenge number on mobile phone screen. If challenge numbers differ, Mobile-ID operation has to be cancelled.
Challenge number should be correctly implemented and highly visible also when Mobile-ID operations are used from Mobile device browser.
Technical suggestions and requirements
- Web applications, that enable authentication or digital signing using Mobile-ID or ID-card, should use encrypted channel (HTTPS) between browser and web server.
- Mobile-ID-enabled web applications, when polling regularly DigiDocService with requests about operation state information (whether user has already entered his/her PIN number and signing/authenticating is completed or not), should, for usability reasons, not reload web page every time request is made to DigiDocService – using Ajax is recommended.
- The file size is limited to 4 MB. StartSession describes how to send larger-scale files to the Service.
Service Change History
Service changes' history can be found at https://github.com/SK-EID/dds-documentation/wiki/Change-log
- Information about canonic XML: http://www.w3.org/TR/xml-c14n