This document describes some practices for web applications integrating with SiGa service.

Take a look at the sample application code for Java implementation examples. You can get examples of request and response JSONs as well if you run the sample application and sign with ID card or Mobile-ID. Sample application and SiGa service can be started using docker.

It is only possible to test with TEST certificates if digidoc4jTest profile is active (The profile is active in Docker container by default). This includes ID-Cards, Mobile-ID, e-Seals, Smart-ID etc. Signing certificate issuer must be present in TEST TSL to be accepted by Digital Signature Gateway service. One can use TEST ID-Card/TEST e-Seal (more here), install DEMO Smart-ID following instructions here and use Demo Mobile-ID numbers from here. You can activate and/or change the status of your TEST certificates in here to test signing with revoked/unknown certificate. Uploading your LIVE certificate to DEMO OCSP service or activating your LIVE Mobile-ID in DEMO MID service does NOT enable use of LIVE certificates in Digital Signature Gateway service.

• Be sure that server clock is correctly synchronized. SiGa has the expiration time for timestamps and too big clock skew can result on invalid authorization.
• Calculate new signature for every request, even if you resend the same request again.
• Take care that "X-Authorization-..." headers are not removed by firewall/proxy/... or that no additional data are inserted into the request body after signature calculation.

• Web applications, that enable digital signing using Mobile-ID or ID-card, should use encrypted channel (HTTPS) between browser and web server.
• Web application should trusts SiGa service TSL certificate. It means that web application should use truststore, which contains SiGa service certificate.
• Sensitive information must be handled with care. For example, SiGa signing secret key, truststore passwords etc must be kept secret.
• If your integrating system manipulates containers (which it has to do when using hashcode enpoints) make sure the system is protected from zip related attacks (for example zip bombs).

• SiGa returns dataToSign XML structure in Base64. This structure needs to be signed using some sort of signing device. How the signing is actually done depends on the device. For example Web eID needs the hash to be signed, not the structure itself. Therefore, the structure needs to be hashed before passing it web-eid.js.
• SiGa returns digestAlgorithm, that was used to prepare the dataToSign. This algo must be used on creating the signature. Keep in mind that for your implementation you may need to convert the hash algo name. For Web eID, you need to convert from SHA512 to SHA-512.
• Do not hardcode the digestAlgorithm on your side. Currently SiGa uses SHA512 exclusively, but the algo may change in future.
• Take care that users can not activate signing several times in one signing process (for example click on sign button several times).

Web service needs to poll Mobile-ID signing status with interval. It is recommended that polling delay between Mobile-ID status requests are 2-10 seconds.

Applications that enable users to digitally sign documents using Mobile-ID must clearly present verification code to the user and warn the 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 by the user. Challenge number should be correctly implemented and highly visible also when using mobile devices. Verification code can be found from Start Mobile-ID signing response under challengeId: Start Mobile-ID response.

Web service needs to poll Smart-ID certificate selection status and Smart-ID signing status with interval. It is recommended that polling delay between Smart-ID status requests are 2-10 seconds.

Applications that enable users to digitally sign documents using Smart-ID must clearly present verification code to the user and warn the user to check if challenge number presented by application is the same as challenge number on mobile phone screen. If challenge numbers differ, Smart-ID operation has to be cancelled by the user. Challenge number should be correctly implemented and highly visible also when using mobile device. Verification code can be found from Start Smart-ID response in challangeId field.

Starting from SiGa release 2.5.0, it is possible to opt for a more secure verification code practice where a signer has to choose the correct verification code from possible 3 choices. Please refer to siga.sid.interaction-type.

It is recommended to validate the signature after signature creation for extra confirmation. For that, use endpoint : Get validation report. validSignaturesCount must match the signaturesCount value. For determining the status of each signers signature, signatures indication value can be checked. Signature is valid when the indication is TOTAL-PASSED.

For most cases, it is not needed to show specific error codes from SiGa to end users, these cases can be handled by web applications internally. However, Mobile-ID and Smart-ID requires interaction with user and it is needed to present a suitable information to user.

Handling Mobile-ID responses:

• Start Mobile-ID signing: It is recommended to present a suitable error message to the user when error code is MID_EXCEPTION and error message is NOT_FOUND. This error is returned when phone number and id code combination do not return any Mobile-ID user. This can be due mistake on inputting the values or the certificates have been suspended/revoked.
• Request Mobile-ID signing status: It is recommended to present a suitable error message to the user when midStatus is not SIGNATURE.

Handling Smart-ID responses:

• Request Smart-ID certificate selection status: It is recommended to present a suitable error message to the user when error code is SMARTID_EXCEPTION and error message is NOT_FOUND. This can be due mistake on inputting the personal identification code, user do not have Smart-ID account or the certificates have been suspended/revoked. It is recommended to present a suitable error message to the user when sidStatus is not CERTIFICATE.
• Request Smart-ID signing status: It is recommended to present a suitable error message to the user when sidStatus is not SIGNATURE.

It is recommended to delete container from session after finishing the required actions. This prevents reaching the maximum connection limits. For that, use endpoint: Delete hashcode container.