- 1. Introduction
- 2. General description
- 3. REST API
- 4. REST API main flows
- 5. Session end result codes
MID REST interface offers the entry point to main use cases for Mobile-ID, i.e. certificate choice, creating signature and authentication.
- Relying Party (RP) - a provider of some kind of e-service. Relying Party authenticates users via MID REST service.
- Session- A proccess initated by Relying Party, which contains a single certificate choice, authentication or signing operation.
Mobile-ID API is exposed over a REST interface as described below. All messages are encoded using UTF-8.
UUID values are encoded as strings containing hexadecimal digits, in canonical 8-4-4-4-12 format, for example:
de305d54-75b4-431b-adb2-eb6b9e546014
relyingPartyName request field is case insensitive. The string is passed to end user as sent in via API.
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 which is cryptographically linked with hash value to be signed. Verification code is displayed both in mobile phone and application in order to provide for authenticity of the signing request.
During Mobile-ID authentication and signing this 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 DTBS (hash senior bits) and 7 bits from the end of DTBS 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
Session is created using one of the POST requests and it ends when a result gets created or when session ends with an error. Session result can be obtained using GET request described below.
Normally, all positive responses are given using HTTP status code "200 OK".
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.
Response on successful session creation
This response is returned from all POST method calls that create a new session.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| sessionId | string | + | A string that can be used to request operation result, see below. |
|
|
BASE: mid-api
| **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.
NB! This method will be updated during February 2018. Please come back for updated version soon.
- User identified in the request (by relyingPartyName, relyingPartyUUID and IP-address)
- Request result has been returned to user.
|
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) |
|
|
|
|
|
Parameter |
Type |
Mandatory |
Description |
|---|---|---|---|
| result | string | + | End result of the transaction. |
| cert | string | for OK result | Certificate value, DER + Base64 encoded. |
| Error code | Error message | Reason |
|---|---|---|
| 500 | Error retrieving certificate response | Getting sessionId from cert-store fails. Cert-store throws internal server error |
| 404 | Something went wrong, response not found | Cert-store cannot find response for given request. |
| 400 | RelyingParty name cannot be null. | 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 |
| Response | Reason |
|---|---|
| OK | Active certificate was found |
| NOT_FOUND | No certificate for the user was found |
| NOT_ACTIVE | Certificate was found but is not active |
| **Method** | **URL** |
| POST | BASE/signature |
This method is the main entry point to signing logic.
- User identified in the request.
- a new session with ID is returned in response.
|
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) |
| hash | string | + | Base64 encoded hash function output to be signed. |
| hashType | string | + | Hash algorithm. |
| language | string | + | Language for user dialog in mobile phone. 3-letters capitalized acronyms are used. Possible values: EST, ENG, RUS, LIT |
| displayText | 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. |
|
|
|
|
| Error code | Error message | Reason |
|---|---|---|
| 500 | Error retrieving certificate/mssp response | Happens when getting sessionId from cert-store/mssp fails. Cert-store/MSSP throws internal server error |
| 404 | Something went wrong, response not found | Happens when cert-store/mssp cannot find response for given request. |
| 400 | Happens when parameter in request is missing on has incorrect format/value | |
| 400 | Required sessionId is missing :sessionID | Happens when sessionID is missing. |
| 400 | The length of the hash must match the type of hash | Hash length does not match the type of hash. For example: hash: SHA256, hashtype:SHA384 |
| 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 |
| **Method** | **URL** |
| GET | BASE/signature/session/:sessionId |
Query parameter timeoutMs Request long poll timeout value in milliseconds. If not provided, a default is used. Server configuration may force this value into a certain range
This method can be used to retrieve session result for signature from MID.
This is a long poll method, meaning it might not return until a timeout expires. Caller can tune the request parameters inside the bounds set by service operator by using the timeoutMs query parameter.
Example:
BASE/signature/session/93de76af-68c1-4b55-91f7-3dad52b3115d?timeoutMs=10000
- Session is present in the system and the request is either running or has been completed less than x minutes ago.
- Request result has been returned to user.
|
Parameter |
Type |
Mandatory |
Description |
|---|---|---|---|
| state | string | + | State of request. "RUNNING"/"COMPLETE". |
| result | string | + | End result of the transaction. |
| signature | string | + | Structure describing the signature result, if any. |
| signature.value | string | + | Signature value, base64 encoded. |
| signature.algorithm | string | + | Signature algorithm, in the form of sha256WithRSAEncryption |
successful response when still waiting for user's response
|
|
successful response after completion
|
|
| Error code | Error message | Reason |
|---|---|---|
| 500 | Error retrieving mssp response | Happens when getting session status from mssp fails. MSSP throws internal server error |
| 404 | SessionId not found :sessionID | SessionID in request is not found |
| 400 | Required sessionId is missing :sessionID | Happens when sessionID is missing. |
| 401 | Failed to authorize user | User authorization by sessionID and IP-address fails |
| 405 | Method Not Allowed |
| **Method** | **URL** |
| POST | BASE/authentication |
This method is the main entry point to authentication logic.
- User identified in the request.
- New session has been created in the system and its ID returned in response.
|
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) |
| hash | string | + | Base64 encoded hash function output to be signed. |
| hashType | string | + | Hash algorithm. |
| language | string | + | Language for user dialog in mobile phone. 3-letters capitalized acronyms are used. Possible values: EST, ENG, RUS, LIT |
| displayText | 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. |
|
|
|
|
| Error code | Error message | Reason |
|---|---|---|
| 500 | Error retrieving certificate/mssp response | Happens when getting sessionId from cert-store/mssp fails. Cert-store/MSSP throws internal server error |
| 404 | Something went wrong, response not found | Happens when cert-store/mssp cannot find response for given request. |
| 400 | Happens when parameter in request is missing on has incorrect format/value | |
| 400 | Required sessionId is missing :sessionID | Happens when sessionID is missing. |
| 400 | The length of the hash must match the type of hash | Hash length does not match the type of hash. For example: hash: SHA256, hashtype:SHA384 |
| 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 |
| **Method** | **URL** |
| GET | BASE/authentication/session/:sessionId |
Query parameter timeoutMs Request long poll timeout value in milliseconds. If not provided, a default is used. Server configuration may force this value into a certain range
This method can be used to retrieve session result for authentication from MID.
This is a long poll method, meaning it might not return until a timeout expires. Caller can tune the request parameters inside the bounds set by service operator by using the timeoutMs query parameter.
Example:
BASE/authentication/session/93de76af-68c1-4b55-91f7-3dad52b3115d?timeoutMs=10000
- Session is present in the system and the request is either running or has been completed less than x minutes ago.
- Request result has been returned to user.
|
Parameter |
Type |
Mandatory |
Description |
|---|---|---|---|
| state | string | + | State of request. "RUNNING"/"COMPLETE". |
| result | string | + | End result of the transaction. |
| signature | string | + | Structure describing the signature result, if any. |
| signature.value | string | + | Signature value, base64 encoded. |
| signature.algorithm | string | + | Signature algorithm, in the form of sha256WithRSAEncryption |
| cert | string | for OK | Certificate value, DER + Base64 encoded. |
successful response when still waiting for user's response
|
|
successful response after completion
|
|
| Error code | Error message | Reason |
|---|---|---|
| 500 | Error retrieving signature response | Happens when getting session status from mssp fails. MSSP throws internal server error |
| 404 | SessionId not found :sessionID | SessionID in request is not found |
| 400 | Required sessionId is missing :sessionID | Happens when sessionID is missing. |
| 401 | Failed to authorize user | User authorization by sessionID and IP-address fails |
| 405 | Method Not Allowed |
| Response | Reason |
|---|---|
| OK | Session was completed successfully |
| TIMEOUT | There was a timeout, i.e. end user did not confirm or refuse the operation within given timeframe. |
| ERROR | There was error getting response from MSSP/certificate service |
| NOT_MID_CLIENT | Given user has no active certificates and is not M-ID client. |
| EXPIRED_TRANSACTION | MSSP transaction timed out. |
| USER_CANCELLED | User cancelled the operation |
| MID_NOT_READY | Mobile-ID not ready |
| PHONE_ABSENT | Sim not available |
| DELIVERY_ERROR | SMS sending error |
| SIM_ERROR | Invalid response from card |
| SIGNATURE_HASH_MISMATCH | Hash does not match with certificate type |
| INTERNAL_ERROR | All other technical errors |