Mobile-ID (MID) REST interface offers the entry point to main use cases for Mobile-ID:

• digital signing
• authentication
• pulling an End Users's signing certificate

• Application Provider - provider of the MID service (SK ID Solutions AS)
• Relying Party (RP) - e-service provider - client for the MID REST API. Authenticates users via MID REST service and/or uses MID REST for users to sign documents inside the e-service.
• Session - A process initiated by Relying Party, which contains authentication or signing operation.
• End User - Person that has a mobile phone with Mobile-ID SIM and who initiates authentication or signing in e-service.
• Mobile Signing - A process where (besides other operations) the hash value of document to be signed is encrypted using secret signing key (stored on SIM-card, protected by 5-digit PIN)
• Mobile Authentication - A process where generated hash is encrypted using secret authentication key (stored on SIM-card, protected by 4-digit PIN)
• Verification Code - A 4-digit number displayed both in e-service and in cellphone screen during authentication and signing. See paragraph 2.4 for more info.
• OCSP - The Online Certificate Status Protocol

Mobile-ID API is exposed over REST interface as described below. All messages are encoded using UTF-8. 

Possible string values of RelyingPartyName are agreed between Relying Party and Application Provider during registration. The value from request is checked during authorization and is displayed to the End User on cell phone screen during authentication and signing. This field is case insensitive.

E-Service provider can have more than one relyingPartyName for different e-services.

relyingPartyUuid is a shared secret that is handed to Relying Party by Application Provider during registration.

This value contains hexadecimal digits in canonical 8-4-4-4-12 format, for example:    de305d54-75b4-431b-adb2-eb6b9e546014 

E-Service provider can have more than one relyingPartyUUID for different e-services.

Relying Party creates the hash using one of the supported hashing algorithms. For signing the document to be signed is the input for the chosen hash algorithm.

For authentication the hash can be random HEX string with correct length. The length has to be one of:

• 32 bytes = 64 HEX characters (if hashType is SHA-256)
• 48 bytes = 96 HEX characters (if hashType is SHA-384)
• 64 bytes = 128 HEX characters (if hashType is SHA-512)

MID REST supports signature operations based on SHA-2 family of hash algorithms, namely SHA-256, SHA-384 and SHA-512. Their corresponding identifiers in API are "SHA256", "SHA384" and "SHA512".

Verification code is a 4-digit number used in mobile authentication and mobile signing. Verification code is cryptographically linked with hash value to be signed. Verification code is displayed both in mobile phone and in e-service provider application in order to provide authenticity of the signing request and enable end user to verify what is exactly being signed.

During Mobile-ID authentication and signing it is required that e-service provider calculates verification code from the hash what will be signed and displays it to the user.

6 bits from the beginning of hash and 7 bits from the end of hash are taken. The resulting 13 bits are transformed into decimal number and printed out. The Verification code is a decimal 4-digits number in range 0000...8192, always 4 digits are displayed (e.g. 0041).

Example:

• Hash value: 2f665f6a6999e0ef0752e00ec9f453adf59d8cb6
• Binary representation of hash: 0010 1111 0110 0110 1111 .... 1000 1100 1011 0110
• Verification code – binary value: 0010110110110
• Verification code – decimal value (displayed for the user): 1462

All positive responses are given using HTTP status code "200 OK". Cases where end user is not a Mobile ID customer or the certificate of End User is not active are also considered as positive responses and HTTP status code 200 is used.

In some cases, 4xx series error codes are used, those cases are described per request. All 5xx series error codes indicate some kind of fatal server error. 

Main flows of MID REST API - authentication and signing - include involvement from End User who has to enter PIN on the cellphone. As this can take time - these processes are split in two parts:

• First request initiates the process and immediately returns session id to the Relying Party.
• Relying Party has to then periodically make status check requests until the process has finished.

MID-REST API-s remain backwards compatible with following exceptions:

• new request fields may be added over time
• new fields may be added to JSON responses. Developers need to take this into account when de-serializing JSON fields into objects. For example when using Jackson to de-serialize JSON objects into Java objects the Java classes should be annotated with @JsonIgnoreProperties(ignoreUnknown = true) or the configuration parameter FAIL_ON_UNKNOWN_PROPERTIES should be set to false. Otherwise Jackson starts throwing com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException when a new field is added to a MID-REST API response.

See chapter 3.4. for fetching current API version.

It is essential that RP performs all the required checks when connecting to the HTTPS API endpoint, to make sure that the connection endpoint is authentic and that the connection is secure. This is required to prevent MITM (Man-in-the-middle) attacks for the authentication and signature protocols.

The RP must do the following checks :

1. Verify if the HTTPS connection and the TLS handshake is performed with the secure TLS ciphersuite.
2. The RP must implement HTTPS pinning (https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning) and verify that the X.509 certificate of the HTTPS endpoint belongs to MID API and is trusted. The HTTPS certificate of MID API can be downloaded here: https://www.skidsolutions.eu/en/Repository/certs/other-important-certificates - section "mid.sk.ee"
3. Verify that the X.509 certificate of the HTTPS endpoint is valid (not expired, signed by trusted CA and not revoked)

These checks are incorporated into:

• mid-rest-java-client
• mid-rest-php-client

In case the RP fails to verify the connection security and the attacks is able to launch MITM attack (you can find more info here)

BASE: mid-api

This method retrieves the signing certificate. Use cases for fetching of the signing certificate:

• to verify the signature obtained by the signature endpoint (as the signing certificate is not included in the signing response)
• for embedding the certificate into *AdES-styled digital signatures which require knowledge of the certificate before creating the signature. (See Java code example that first pulls the certificate and then starts the signing process.)
• to test if end user is a Mobile ID customer.

If end user has two pairs of certificates (RSA and Elliptic Curve Cryptography (ECC)) then system returns preferred certificate (ECC).

• User identified in the request (by relyingPartyName, relyingPartyUUID and IP-address)

• Request result has been returned to caller. 

{
   "relyingPartyUUID": "de305d54-75b4-431b-adb2-eb6b9e546014" ,  
   "relyingPartyName": "BANK123",  
   "phoneNumber": "+3726234566" ,  
   "nationalIdentityNumber": "38412319871"
}

{  
    "result": "OK",  
    "cert": "MIIHhjCCBW6gAwIBAgIQDNYLtVwrKURYStrYApYViTANBgkqhkiG9w0B...",
    "time": "2019-07-23T11:32:01",
    "traceId": "5ffc28098bb14341"
}

For all the result values HTTP status code 200 is used.

Different URL-s need to be used to initiate signing or authentication:

• End User in the request is identified.

• A new session with ID is returned in response. 

{
    "relyingPartyUUID": "00000000-0000-0000-0000-000000000000",
    "relyingPartyName": "DEMO",
    "phoneNumber": "+3726234566",
    "nationalIdentityNumber": "38412319871",
    "hash": "0nbgC2fVdLVQFZJdBbmG7oPoElpCYsQMtrY0c0wKYRg=",
    "hashType": "SHA256",
    "language": "ENG",
    "displayText": "This is display text.",
    "displayTextFormat": "GSM-7"
}

Following dialogues are displayed on end user cellphone screen for authentication and signing. Actual design varies on different phone models.

Note that when the process is signing the prompt to End User has "Sign?" in the end and authentication has "Enter?".

{
  "sessionID": "de305d54-75b4-431b-adb2-eb6b9e546015"  
}

Any response where HTTP status code is not 200 is considered an error condition. HTTP status code 4xx refers to errors made by the Relying Party and HTTP status code 5xx refers to an error on the Application Provider's side.

If authentication or signing is not successful because of End User not entering PIN or due to communication failure this is not considered an error condition but rather a something that can be predicted and expected i.e. it is part of the normal flow.

See next chapter for body of the error.

Example error response contents:

{
    "error": "relyingPartyUUID must not be null",
    "time": "2019-07-23T11:27:49",
    "traceId": "4a295f2786d6dc89"
}

Any error response (when HTTP status code is not 200) contains an error message. This response is meant for the developer to fix the call. There is no need to parse any error responses (where HTTP status code is not 200) and these error messages should not be shown to the End User. Also error responses hold time and traceId parameters which are for Application Provider to find the application logs for any reports about possible errors of MID-REST API.

Polling of the authentication and signing status differs from endpoint name to be used.

• Session is present in the system and the request is either running or has been completed recently. 

• Current session state has been returned to user.

In order to avoid making many requests towards Application Provider the E-Service provider is recommended to use long polling by setting parameter timeoutMs.

If the session is in RUNNING state (meaning waiting for user to enter the PIN to the cellphone and the response to arrive) the server waits this amount of time before responding.

If this parameter is not provided, a default is used (can change, value 10000ms). For very large values the service silently reverts to configuration specific maximum value (can change, value around 60000-12000ms). For very low values the service silently reverts to configuration specific minimum value (can change, value around 1000ms)

If the state of session changes during the wait time then the response is sent out immediately. If the wait time is over but the response has not yet arrived from phone then the service responds back that the session is RUNNING and the caller is encouraged to immediately create a new long polling request.

The E-Service provider should not make new requests for given session before the previous request gets a response back. However, if Application Provider detects a new request with the same session ID then the previous request is discarded and response with state=RUNNING is replied back to the previous request.

NB! E-Service provider should set its own internal request timeout to a slightly higher value (add additional ~1500ms). For example if E-Service provider makes a request with ?timeoutMs=60000 then it should set a request timeout of 61500ms (and not use the same value of 60000ms) as it takes additional time to transfer the request and response over the network.

For authentication additional steps must be followed to verify that the authentication result is trustworthy and identity of the End User is confirmed:

• "result" has the value "OK"
• "signature.value" is a valid signature over the same "hash", which was submitted by the Relying Party.
• "signature.value" is a valid signature. This can be verified by using the public key taken from the certificate returned on the "cert" field.
• The person's certificate given in the "cert" is valid. This means it is:
  • not expired
  • signed by trusted certificate authority
• The identity of the authenticated person is in the "subject" field of the X.509 certificate included in "cert" field.

After successful authentication, the Relying Party must also invalidate user's browser or API session identifier and generate a new one.

Response when server is still waiting for user's response to arrive back from cellphone:

{
    "state":"RUNNING",
    "time": "2019-07-23T11:36:16",
    "traceId": "460ef8a6be5730da"  
}

Signing response after successful completion:

{
    "state": "COMPLETE",
    "result": "OK",
    "signature": {
        "value": "B+C9XVjIAZnCHH9vfBSv...",
        "algorithm": "SHA256WithECEncryption"
    },
    "time": "2019-07-23T10:52:20",
    "traceId": "d8de38e7bb5d8f8a"
}

Authentication response after successful completion (note that unlike signature response it also includes authentication certificate):

{  
    "state": "COMPLETE",
    "result": "OK",
    "signature": {
        "value": "B+C9XVjIAZnCHH9vfBSv...",
        "algorithm": "SHA256WithECEncryption"  
    },
    "cert": "MIIFxjCCA66gAwIBAgIQZ6v2ut9...",
    "time": "2019-07-23T10:52:20",
    "traceId": "d8de38e7bb5d8f8a"
}

If user cancelled the operation:

{  
    "state": "COMPLETE",
    "result": "USER_CANCELLED",
    "time": "2019-07-23T11:36:38",
    "traceId": "2f3bebf7036c51f1"
}

When response from end user's cell phone has not arrived within a timeout period set by Application Provider. The Application Provider has given up waiting for it to arrive and responds with:

{
    "state": "COMPLETE",
    "result": "TIMEOUT",
    "time": "2019-07-23T11:36:11",
    "traceId": "bc861f0cf0568570"
}

The following is a complete list of possible result codes returned by the service. For all of them a HTTP 200 status code and a JSON string is returned with "state": "COMPLETE" and "result" with one of the following values:

    Version: 5.1.1. Built: 19.06.2019 21:06  

    Version: MAJOR.MINOR.PATCH. Built: dd.MM.yyyy hh:mm

Version numbering:

• MAJOR version is incremented when a new API is released or if there have been major internal changes. See chapter 2.7. for notes about API backwards compatibility.
• MINOR version is incremented when there are smaller internal changes, new request parameters or new response fields are added.
• PATCH version is incremented with backwards-compatible bug fixes. No fields are added with bug fixes.

Built timestamp refers when the release was built from source code.

Open link: https://tsp.demo.sk.ee/mid-api/version

There are client libraries provided for easier integration for Java and PHP and also demo applications that demonstrate usage of the client libraries.

Java Clint allows using all of the MID-REST functionality.

• Java Client
• Java Demo Application

Provided PHP functionality only supports authentication and fetching the signing certificate.

• PHP Client
• PHP Demo Application

The Online Certificate Status Protocol is an Internet protocol used for obtaining the revocation status of an X.509 digital certificate. See Validity Confirmation Services offered by SK for more information.

When digitally signing AsicE and Bdoc containers by standard then for the signature to be valid it is required to perform OCSP for signer's certificate at the time of signing and include OCSP response as part of the signature. MID-REST doesn't perform any OCSP requests.

Digidoc4j performs the OCSP during signing process and includes OCSP response it in the signature. For testing purposes, it is possible to use Test OCSP by building the signature Container with Test Configuration. To use test ocsp you need to upload your signing certificate here.

Configuration configuration = new Configuration(Configuration.Mode.TEST);

Container container = ContainerBuilder.aContainer()
    .withConfiguration(configuration)
    .withDataFile(uploadedFile)
    .build();