Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
jalukse Update README.md
Long Poll default timeoutMs is 10000ms
Latest commit 15a12f4 Aug 29, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
DDS-to-MID-migration typo fix Mar 20, 2019
images Changes introduced for java-mid-rest-client version 1.1 Mar 18, 2019
README.md Update README.md Aug 29, 2019

README.md

Mobile ID (MID) REST API

1. Introduction

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

1.1. Terminology

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

2. General description

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

2.1. relyingPartyName

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.

2.2. relyingPartyUUID

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.

2.3. Creating the hash

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 either 32 characters (if hashType is SHA-256), 48 characters (SHA-384) or 64 characters (SHA-512).

2.3.1. Supported hashing algorithms

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

2.4. Verification code

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.

2.4.1. Verification code calculation algorithm

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

2.5. HTTP status code usage

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. 

2.6. Session management 

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.

3. REST API flows

BASE: mid-api

3.1. Certificate request

Method

URL

POST BASE/certificate

This method retrieves the signing certificate.

This method is necessary for *AdES-styled digital signatures which require knowledge of the certificate before creating the signature. For other types of digital signatures knowledge of the certificate is not needed.

This endpoint can be used 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).

3.1.1. Pre-Conditions 

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

3.1.2. Post-Conditions

  • Request result has been returned to caller. 

3.1.3. Request parameters

Parameter

Type

Mandatory

Description

relyingPartyName string + Name of the relying party – previously agreed with Application Provider and DigiDocService operator.
relyingPartyUUID string + UUID of the relying party
phoneNumber string + Phone number of the signer with the country code in the format of +xxxxxxxxx
nationalIdentityNumber string + Identification number of the signer (personal national ID number). For example 38412319871

3.1.4. Example request

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

3.1.5. Example response

{  
    "result": "OK",  
    "cert": "MIIHhjCCBW6gAwIBAgIQDNYLtVwrKURYStrYApYViTANBgkqhkiG9w0B..."  
}

3.1.6. Response structure 

Parameter

Type

Mandatory

Description

result string + End result of the transaction.
cert string for OK result Certificate value, DER + Base64 encoded.

3.1.7. Possible result values

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

Result Reason
OK An active certificate was found
NOT_FOUND No certificate for the user was found
NOT_ACTIVE Certificate was found but is not active

3.1.8. Error conditions

HTTP status code Error message Reason
400 {parameterName} cannot be null. Required parameter in request is missing on has incorrect format/value
401 Failed to authorize user User authorization by relyingPartyName, relyingPartyUUID and IP-address fails
405 Method Not Allowed Only POST and OPTIONS methods are allowed.
500 Internal error MID-REST internal error. Retry the operation.

3.2. Initiating signing and authentication

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

Process

Method

URL

Signing POST BASE/signature
Authenticate POST BASE/authentication

3.2.1. Pre-Conditions

  • End User in the request is identified.

3.2.2. Post-Conditions

  • A new session with ID is returned in response. 

3.2.3. Request parameters

Parameter

Type

Mandatory

Description

relyingPartyName string + Name of the Relying Party, previously agreed with Application Provider. Displayed together with displayText and Verification Code on cellphone screen before End User can insert PIN.
relyingPartyUUID string + UUID of the Relying Party - previously agreed with Application Provider.
phoneNumber string + Phone number of the signer with the country code in the format of +xxxxxxxxx
nationalIdentityNumber string + Identification number of the signer (personal national ID number)
hash string + Base64 encoded hash function output to be signed.
hashType string + Hash algorithm used to create the hash.
language string + Language for user dialog in mobile phone. 3-letters capitalized acronyms are used. Possible values: EST, ENG, RUS, LIT. NB! If you use language="LIT" to send to Estonian number (+372...) or you use language="EST" to send to Lithuanian number (+370...) then internally language is replaced with "ENG".
displayText string Text displayed in addition to relyingPartyName and Verification Code before asking authentication PIN. Maximum length is 40 bytes that is either 20 or 40 characters depending on the encoding - see displayTextFormat. If you set displayTextFormat="GSM-7" then all characters not beloning to this alphabet are replaced with spaces.
displayTextFormat string Specifies which characters and how many can be used in "displayText". Possible values are "GSM-7" and "UCS-2”, if nothing is specified then defaults to "GSM-7". GSM-7 allows displayText to contain up to 40 characters from standard GSM 7-bit alpabet including up to 5 characters from extension table ( €[]^|{}\ ). UCS-2 allows up to 20 characters from UCS-2 alpabet (this has all Cyrillic characters, ÕŠŽ šžõ and ĄČĘĖĮŠŲŪŽ ąčęėįšųūž). [More info about encoding](https://en.wikipedia.org/wiki/GSM_03.38).

3.2.4. Example request

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

Prompt for signing Prompt of authentication

Sign prompt on cellphone screen

Auth prompt on cellphone screen

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

3.2.5. Example response

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

3.2.6. Error conditions

HTTP status code Error message Reason
400 Required {parameterName} is missing. Mandatory parameter in request is missing on has incorrect format/value
400 The length of the hash must match the type of hash Hash length does not match the type of hash. For example base64 decoded value of SHA256 hash has to be (256bits divided with 8bits) = 32 bytes.
400 Hash must be Base64 encoded Hash is not base64 encoded.
401 Failed to authorize user User authorization by relyingPartyName, relyingPartyUUID and IP-address fails
405 Method Not Allowed Only HTTP methods POST and OPTIONS are allowed
500 Internal error MID-REST internal error. Try start the process again from the beginning.

3.3. Status of signing and authentication

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

Process

Method

URL

Signing GET BASE/signature/session/:sessionId?timeoutMs=:timeoutMs
Authentication GET BASE/authentication/session/:sessionId?timeoutMs=:timeoutMs

3.3.1. Pre-Conditions

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

3.3.2. Post-Conditions

  • Current session state has been returned to user.

3.3.3. Request parameters

Parameter

Type

Mandatory

Description

sessionId string + Session ID
timeoutMs integer Maximum time in milliseconds the server is allowed to wait before returning a response. See next chapter for more info.

3.3.4. Long polling

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.

3.3.5. Response structure

Parameter

Type

Present

Description

state string + State of request. One of "RUNNING", "COMPLETE".
result string Only if state is COMPLETE Result of the transaction. See paragraph 3.3.7 for possible values.
signature string Only if state is COMPLETE Structure describing the signature result, if any.
signature.value string Only if state is COMPLETE Signature value, base64 encoded.
signature.algorithm string Only if state is COMPLETE Signature algorithm, in the form of sha256WithRSAEncryption
cert string Only if process was authentication and signature is present. Authentication certificate used. DER + Base64 encoded. Signing process doesn't return this value.

3.3.6. Verifying the authentication response

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.

3.3.7. Example responses

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

{
    "state":"RUNNING"  
}

Signing response after successful completion:

{
    "state": "COMPLETE",
    "result": "OK",
    "signature": {
        "value": "B+C9XVjIAZnCHH9vfBSv...",
        "algorithm": "SHA256WithECEncryption"
    }  
}

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

If user cancelled the operation:

{  
    "state": "COMPLETE",
    "result": "USER_CANCELLED"
}

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

3.3.8. Session end result codes

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:

Result Reason
OK Session was completed successfully
TIMEOUT There was a timeout, i.e. end user did not confirm or refuse the operation within maximum time frame allowed (can change, around two minutes).
NOT_MID_CLIENT Given user has no active certificates and is not MID client.
USER_CANCELLED User cancelled the operation
SIGNATURE_HASH_MISMATCH Mobile-ID configuration on user's SIM card differs from what is configured on service provider's side. User needs to contact his/her mobile operator.
PHONE_ABSENT Sim not available
DELIVERY_ERROR SMS sending error
SIM_ERROR Invalid response from card

3.3.9. HTTP error codes

Error code Error message Reason
400 Required sessionId is missing Required paramter sessionId is missing.
401 Failed to authorize user User authorization by sessionId and IP-address fails
404 SessionID not found Sessions expire within 5 minutes.
405 Method Not Allowed Only GET and OPTIONS are allowed methods.
500 Internal error MID-REST internal error. Try start the process again from the beginning.

4. Helper libraries and demo applications

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

4.1. Java

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

4.2. PHP

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

5. Comparison with DigiDocService

Previous generation MID-REST integration has been provided with SOAP-based DigiDocService (DDS). Following page lists the main differences between DDS and new MID-REST (MID) and provides hints for migration from DDS to MID-

You can’t perform that action at this time.