Skip to content

Commit

Permalink
Release 5.2.1 (#11)
Browse files Browse the repository at this point in the history 
* comparison about getting auth/sing certificate. OCSP typo fix.
* notes about versioning and backwards compatibility
* added versioning and backwards compatibility info
* added time and traceId documentation and updated example responses
  • Loading branch information
@jalukse
jalukse authored Oct 17, 2019
1 parent 15a12f4 commit 3a01991
Show file tree
Hide file tree
Showing 2 changed files with 132 additions and 8 deletions.
5 changes: 4 additions & 1 deletion DDS-to-MID-migration/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,10 @@ Since launching the DDS service a lot has happened:
| Can be used to verify a certificate's validity (including any smartcard) | yes | no |
| Can be used to create DigiDoc/BDOC containers (even when signing with smart-card) | yes | no |
| Can be used to verify digitally signed files (DigiDoc/BDOC) and validity of signatures | yes | no |
| OSCP during authentication | yes | no |
| OCSP during authentication | yes | no |
| Relying Party can get end user's authentication certificate| yes | only after successful authentication|
| Relying Party can pull end user's signing certificate| yes | yes|
| Relying Party can decide if it wants to use RSA or ECC certificate for signing | yes | no, MID decides which certificate to return|


## How to create and validate containers with MID
Expand Down
135 changes: 128 additions & 7 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
* [2.4.1\. Verification code calculation algorithm](#241-verification-code-calculation-algorithm)
* [2.5\. HTTP status code usage](#25-http-status-code-usage)
* [2.6\. Session management](#26-session-management)
* [2.7. Backwards compatibility](#27-backwards-compatibility)
* [3\. REST API flows](#3-rest-api-flows)
* [3.1\. Certificate request](#31-certificate-request)
* [3.1.1\. Pre-Conditions ](#311-Pre-Conditions)
Expand Down Expand Up @@ -45,6 +46,10 @@
* [3.3.7. Example responses](#337-example-responses)
* [3.3.8. Session end result codes](#338-session-end-result-codes)
* [3.3.9. HTTP error codes](#339-http-error-codes)
* [3.4. API version](#34-api-version)
* [3.4.1. Example response](#341-example-response)
* [3.4.2. Response structure](#342-response-structure)
* [3.4.3. Public demo environment version number](#343-public-demo-environment-version-number)
* [4\. Helper libraries and demo applications](#4-helper-libraries-and-demo-applications)
* [4.1\. Java](#41-java)
* [4.2\. PHP](#42-php)
Expand Down Expand Up @@ -144,6 +149,23 @@ 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.

## <span class="numhead-number">2.7.</span> Backwards compatibility

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](https://github.com/FasterXML/jackson-databind/wiki/Deserialization-Features)
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.](#34-api-version) for fetching current API version.

# <span class="numhead-number">3.</span> REST API flows

<span class="inline-comment-marker" data-ref="37ce9f19-f57b-4c9f-922a-36e89b61c972">BASE: mid-api</span>
Expand Down Expand Up @@ -306,7 +328,9 @@ Description
```json
{
"result": "OK",
"cert": "MIIHhjCCBW6gAwIBAgIQDNYLtVwrKURYStrYApYViTANBgkqhkiG9w0B..."
"cert": "MIIHhjCCBW6gAwIBAgIQDNYLtVwrKURYStrYApYViTANBgkqhkiG9w0B...",
"time": "2019-07-23T11:32:01",
"traceId": "5ffc28098bb14341"
}
```

Expand Down Expand Up @@ -374,6 +398,20 @@ Description

</tr>

<tr>
<td>time</td>
<td>datetime</td>
<td>Since 5.2.1</td>
<td>Used by Application Provider for tracking application logs of any error report.</td>
</tr>
<tr>
<td>traceId</td>
<td>HEX number</td>
<td>Since 5.2.1</td>
<td>Used by Application Provider for tracking application logs of any error report.</td>
</tr>


</tbody>

</table>
Expand Down Expand Up @@ -737,6 +775,15 @@ Note that when the process is signing the prompt to End User has "Sign?" in the

### <span class="numhead-number">3.2.6\.</span> Error conditions

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.


<div class="table-wrap">

<table class="confluenceTable"><colgroup><col> <col> <col></colgroup>
Expand Down Expand Up @@ -810,7 +857,26 @@ Note that when the process is signing the prompt to End User has "Sign?" in the
</table>
</div>

See next chapter for body of the error.

### 3.2.7.</span> Error response contents

Example error response contents:

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


## <span class="numhead-number">3.3\.</span> Status of signing and authentication
Expand Down Expand Up @@ -1069,7 +1135,21 @@ Description
<td colspan="1" class="confluenceTd">cert</td>
<td colspan="1" class="confluenceTd">string</td>
<td colspan="1" class="confluenceTd">Only if process was authentication and signature is present.</td>
<td colspan="1" class="confluenceTd">Authentication certificate used. DER + Base64 encoded. Signing process doesn't return this value.</td>
<td colspan="1" class="confluenceTd">Authentication certificate used. DER + Base64 encoded. Signing process doesn't return this value (need to pull separately).
From the certificate it is possible to obtain end user name, national identity number and country. See [mid-rest-java-client](https://github.com/SK-EID/mid-rest-java-client) or [mid-rest-php-client](https://github.com/SK-EID/mid-rest-php-client) for examples how to parse the certificate.</td>
</tr>

<tr>
<td>time</td>
<td>datetime</td>
<td>Since 5.2.1</td>
<td>Used by Application Provider for tracking application logs of any error report</td>
</tr>
<tr>
<td>traceId</td>
<td>HEX number</td>
<td>Since 5.2.1</td>
<td>Used by Application Provider for tracking application logs of any error report</td>
</tr>

</tbody>
Expand Down Expand Up @@ -1102,7 +1182,9 @@ Response when server is still waiting for user's response to arrive back from ce

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

Expand All @@ -1117,7 +1199,9 @@ Signing response after successful completion:
"signature": {
"value": "B+C9XVjIAZnCHH9vfBSv...",
"algorithm": "SHA256WithECEncryption"
}
},
"time": "2019-07-23T10:52:20",
"traceId": "d8de38e7bb5d8f8a"
}
```

Expand All @@ -1132,7 +1216,9 @@ Authentication response after successful completion (note that unlike signature
"value": "B+C9XVjIAZnCHH9vfBSv...",
"algorithm": "SHA256WithECEncryption"
},
"cert": "MIIFxjCCA66gAwIBAgIQZ6v2ut9..."
"cert": "MIIFxjCCA66gAwIBAgIQZ6v2ut9...",
"time": "2019-07-23T10:52:20",
"traceId": "d8de38e7bb5d8f8a"
}
```

Expand All @@ -1141,7 +1227,9 @@ If user cancelled the operation:
```json
{
"state": "COMPLETE",
"result": "USER_CANCELLED"
"result": "USER_CANCELLED",
"time": "2019-07-23T11:36:38",
"traceId": "2f3bebf7036c51f1"
}
```

Expand All @@ -1151,7 +1239,9 @@ The Application Provider has given up waiting for it to arrive and responds with
```json
{
"state": "COMPLETE",
"result": "TIMEOUT"
"result": "TIMEOUT",
"time": "2019-07-23T11:36:11",
"traceId": "bc861f0cf0568570"
}
```

Expand Down Expand Up @@ -1319,6 +1409,37 @@ and "result" with one of the following values:

</div>

## <span class="numhead-number">3.4.</span> API version

| Method | URL |
| ------ | -------------|
| GET | BASE/version |

### 3.4.1. Example response

```
Version: 5.1.1. Built: 19.06.2019 21:06
```

### 3.4.2. Response structure

```
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.](#27-backwards-compatibility) 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.

### 3.4.3. Public demo environment version number

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


# <span class="numhead-number">4.</span> Helper libraries and demo applications

There are client libraries provided for easier integration for Java and PHP and also
Expand Down

0 comments on commit 3a01991

Please sign in to comment.