From a93d710e357d9775d65838f9a89b04f0da9deab6 Mon Sep 17 00:00:00 2001 From: Kristjan Jalukse Date: Fri, 22 Feb 2019 17:42:08 +0200 Subject: [PATCH 1/5] Fixed RP API mardown doc json formatting error --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 546db34..f044bc4 100644 --- a/README.md +++ b/README.md @@ -299,7 +299,7 @@ nonce | string | | Random string, up to 30 characters. If present, must have a { "relyingPartyUUID": "00000000-0000-0000-0000-000000000000", "relyingPartyName": "DEMO", - "certificateLevel": "QUALIFIED" + "certificateLevel": "QUALIFIED", "hash": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...", "hashType": "SHA512", "displayText": "Log into internet banking system" From e5352e0d574c56837c90766253726a7f40e3e551 Mon Sep 17 00:00:00 2001 From: Kristjan Jalukse Date: Fri, 22 Feb 2019 17:43:20 +0200 Subject: [PATCH 2/5] SID-5292: Three-choice verification code spec in RP API doc --- README.md | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f044bc4..7d01602 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ * [4.1.3. HTTP status code usage](#413-http-status-code-usage) * [4.1.4. Response on successful session creation](#414-response-on-successful-session-creation) * [4.1.5. Idempotent behaviour](#415-idempotent-behaviour) + * [4.1.6. Request properties](#416-request-properties) + * [4.1.7. Additional request result info](#417-additional-request-result-info) * [4.2. REST API main flows](#42-rest-api-main-flows) * [4.3. Certificate choice session](#43-certificate-choice-session) * [4.3.1. Preconditions](#431-preconditions) @@ -126,7 +128,7 @@ In case the RP fails to verify the connection security and the attacks is able t ## 4.1. Interface patterns -BASE URL value is given in service documentation and may vary between environments and service instances.The base URL for SK DEMO environment is https://sid.demo.sk.ee/smart-id-rp/v1/ +BASE URL value is given in service documentation and may vary between environments and service instances.The base URL for SK DEMO environment is https://sid.demo.sk.ee/smart-id-rp/v1/ NB! The production environment base URL is different and it's fixed in service agreement. ### 4.1.1. Session management @@ -192,6 +194,26 @@ Retry timeframe is **15 seconds**. When requestor wants, it can override the idempotent behaviour inside of this timeframe using an optional "nonce" parameter present for all POST requests. Normally, that parameter can be omitted. +### 4.1.6. Request properties + +The RP can include additional properties to some of the requests (POST to signature/ and authentication/) for requesting some desired behaviour. + +The request parameter "requestProperties" can be used to include a list of properties. + +Supported property values: + +* **THREE_CHOICE_VERIFICATION_CODE** - Can be used to require the Smart-ID App to let the User choose the correct verification code from three differing codes, out of which one code is the real one and the other two are random codes. + +Any defined property that is not supported by Smart-ID or the App (e.g. the App is too old) will be listed in the "ignoredProperties" parameter of the Session status response. + +### 4.1.7 Additional request result info + +The RP API may deem necessary to return some additional information to the RP about the result of the request. For that, the "additionalInfo" session result response parameter is used. + +Possible values: + +* **USER_CHOSE_CORRECT_CODE** - The three-choice verification code request was accepted and processed, and the user chose the correct code. + ## 4.2. REST API main flows ![RP API sequences](https://github.com/SK-EID/smart-id-documentation/blob/master/images/RP_API_sequences_REST.png) @@ -293,6 +315,7 @@ hash | string | + | Base64 encoded hash function output to be signed. hashType | string | + | Hash algorithm. See hash algorithm section. displayText | string | | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. nonce | string | | Random string, up to 30 characters. If present, must have at least 1 character. +requestProperties | array | | An array of optional request properties. See [Request properties](#416-request-properties). **Authentication request:** ``` @@ -302,7 +325,8 @@ nonce | string | | Random string, up to 30 characters. If present, must have a "certificateLevel": "QUALIFIED", "hash": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...", "hashType": "SHA512", - "displayText": "Log into internet banking system" + "displayText": "Log into internet banking system", + "requestProperties": ["THREE_CHOICE_VERIFICATION_CODE"] } ``` @@ -359,6 +383,7 @@ hash | string | + | Base64 encoded hash function output to be signed. hashType | string | + | Hash algorithm. See hash algorithm section. displayText | string | | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. nonce | string | | Random string, up to 30 characters. If present, must have at least 1 character. +requestProperties | array | | An array of optional request properties. See [Request properties](#416-request-properties). **Signature request:** ``` @@ -368,7 +393,8 @@ nonce | string | | Random string, up to 30 characters. If present, must have a "certificateLevel": "QUALIFIED", "hash": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...", "hashType": "SHA512", - "displayText": "Authorize transfer of £10" + "displayText": "Authorize transfer of £10", + "requestProperties": ["THREE_CHOICE_VERIFICATION_CODE"] } ``` @@ -387,8 +413,9 @@ Method | URL -------|---- GET | BASE/session/:sessionId -**Query parameter****Contents**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, see server configuration documentation for details. +Query parameter | Contents +----------------|--------- +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, see server configuration documentation for details. This method can be used to retrieve session result from Smart-ID backend. @@ -408,7 +435,7 @@ Example URL: ### 4.6.3. Error conditions -* HTTP error code 404 - session does not exist or is too old or has expired. +* HTTP error code 404 - session does not exist or is too old or has expired. ### 4.6.4. Response structure @@ -425,6 +452,8 @@ cert | object | for OK | Structure describing the certificate related to request cert.value | string | + | Certificate value, DER+Base64 encoded. The certificate itself contains info on whether the cerificate is QSCD-enabled, data which is not represented by certificate level. cert.assuranceLevel | string | | **DEPRECATED. **Please use cert.certificateLevel parameter instead. cert.certificateLevel | string | + | Level of Smart-ID certificate: **ADVANCED** - Used for Smart-ID basic. **QUALIFIED** - Used for Smart-ID. This means that issued certificate is qualified. +additionalInfo | array | | Additional information about the result of the request. See [Additional request result info](#417-additional-request-result-info). +ignoredProperties | array | | Any values from the requestProperties that were ignored because of Smart-ID Server or Smart-ID App not supporting them. **successful response when still waiting for user's response:** ``` @@ -450,7 +479,8 @@ cert.certificateLevel | string | + | Level of Smart-ID certificate: **ADVANCED** "value": "B+C9XVjIAZnCHH9vfBSv...", "assuranceLevel": "http://eidas.europa.eu/LoA/substantial", "certificateLevel": "QUALIFIED" - } + }, + "additionalInfo": ["USER_CHOSE_CORRECT_CODE"] } ``` @@ -461,6 +491,7 @@ cert.certificateLevel | string | + | Level of Smart-ID certificate: **ADVANCED** * **USER_REFUSED** - user refused the session. * **TIMEOUT** - there was a timeout, i.e. end user did not confirm or refuse the operation within given timeframe. * **DOCUMENT_UNUSABLE** - for some reason, this RP request cannot be completed. User must either check his/her Smart-ID mobile application or turn to customer support for getting the exact reason. +* **USER_CHOSE_WRONG_CODE** - in case the three-choice verification code was requested, the user did not choose the correct verification code # 6. Protocols From b0fbcc715027a14f2f1b864bddd92b0a0176b36c Mon Sep 17 00:00:00 2001 From: Kristjan Jalukse Date: Fri, 22 Feb 2019 17:46:53 +0200 Subject: [PATCH 3/5] SID-5292: A tiny change in the RP API ignoredProperties --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7d01602..e8b00bc 100644 --- a/README.md +++ b/README.md @@ -204,7 +204,9 @@ Supported property values: * **THREE_CHOICE_VERIFICATION_CODE** - Can be used to require the Smart-ID App to let the User choose the correct verification code from three differing codes, out of which one code is the real one and the other two are random codes. -Any defined property that is not supported by Smart-ID or the App (e.g. the App is too old) will be listed in the "ignoredProperties" parameter of the Session status response. +Any unsupported property will produce an error. + +Any defined property that is not supported by the Smart-ID App because the App is too old will be listed in the "ignoredProperties" parameter of the Session status response. ### 4.1.7 Additional request result info @@ -453,7 +455,7 @@ cert.value | string | + | Certificate value, DER+Base64 encoded. The certificate cert.assuranceLevel | string | | **DEPRECATED. **Please use cert.certificateLevel parameter instead. cert.certificateLevel | string | + | Level of Smart-ID certificate: **ADVANCED** - Used for Smart-ID basic. **QUALIFIED** - Used for Smart-ID. This means that issued certificate is qualified. additionalInfo | array | | Additional information about the result of the request. See [Additional request result info](#417-additional-request-result-info). -ignoredProperties | array | | Any values from the requestProperties that were ignored because of Smart-ID Server or Smart-ID App not supporting them. +ignoredProperties | array | | Any values from the requestProperties that were ignored because of the Smart-ID App being too old to support them. **successful response when still waiting for user's response:** ``` From 5ed36d7626ce30e886510ca95e20793f91aa0d9a Mon Sep 17 00:00:00 2001 From: Kristjan Jalukse Date: Fri, 22 Feb 2019 17:47:54 +0200 Subject: [PATCH 4/5] SID-5299: refactor requestProperties to map and other changes --- README.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index e8b00bc..a23ab2f 100644 --- a/README.md +++ b/README.md @@ -198,23 +198,21 @@ When requestor wants, it can override the idempotent behaviour inside of this ti The RP can include additional properties to some of the requests (POST to signature/ and authentication/) for requesting some desired behaviour. -The request parameter "requestProperties" can be used to include a list of properties. +The request parameter "requestProperties" can be used to include properties as a set of name/value pairs. -Supported property values: - -* **THREE_CHOICE_VERIFICATION_CODE** - Can be used to require the Smart-ID App to let the User choose the correct verification code from three differing codes, out of which one code is the real one and the other two are random codes. +Supported property names: -Any unsupported property will produce an error. - -Any defined property that is not supported by the Smart-ID App because the App is too old will be listed in the "ignoredProperties" parameter of the Session status response. +* **threeChoiceVerificationCode** - Can be used to require the Smart-ID App to let the User choose the correct verification code from three differing codes, out of which one code is the real one and the other two are random codes. -### 4.1.7 Additional request result info +Supported property values: -The RP API may deem necessary to return some additional information to the RP about the result of the request. For that, the "additionalInfo" session result response parameter is used. +* **true** - The property is enabled. +* **false** - The property is disabled. +* **null** - The property is disabled. -Possible values: +Any unsupported property will be ignored and will be listed in the "ignoredProperties" parameter of the Session status response. -* **USER_CHOSE_CORRECT_CODE** - The three-choice verification code request was accepted and processed, and the user chose the correct code. +Any defined property that is not supported by the Smart-ID App because the App is too old will be listed in the "ignoredProperties" parameter of the Session status response. ## 4.2. REST API main flows @@ -317,7 +315,7 @@ hash | string | + | Base64 encoded hash function output to be signed. hashType | string | + | Hash algorithm. See hash algorithm section. displayText | string | | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. nonce | string | | Random string, up to 30 characters. If present, must have at least 1 character. -requestProperties | array | | An array of optional request properties. See [Request properties](#416-request-properties). +requestProperties | object | | A request properties object. See [Request properties](#416-request-properties). **Authentication request:** ``` @@ -328,7 +326,9 @@ requestProperties | array | | An array of optional request properties. See [Re "hash": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...", "hashType": "SHA512", "displayText": "Log into internet banking system", - "requestProperties": ["THREE_CHOICE_VERIFICATION_CODE"] + "requestProperties": { + "threeChoiceVerificationCode": true + } } ``` @@ -385,7 +385,7 @@ hash | string | + | Base64 encoded hash function output to be signed. hashType | string | + | Hash algorithm. See hash algorithm section. displayText | string | | Text to display for authentication consent dialog on the mobile device. Limited to 60 characters or 128 bytes in UTF-8 encoding, whichever is reached first. nonce | string | | Random string, up to 30 characters. If present, must have at least 1 character. -requestProperties | array | | An array of optional request properties. See [Request properties](#416-request-properties). +requestProperties | object | | A request properties object. See [Request properties](#416-request-properties). **Signature request:** ``` @@ -396,7 +396,9 @@ requestProperties | array | | An array of optional request properties. See [Re "hash": "ZHNmYmhkZmdoZGcgZmRmMTM0NTM...", "hashType": "SHA512", "displayText": "Authorize transfer of £10", - "requestProperties": ["THREE_CHOICE_VERIFICATION_CODE"] + "requestProperties": { + "threeChoiceVerificationCode": true + } } ``` @@ -454,8 +456,7 @@ cert | object | for OK | Structure describing the certificate related to request cert.value | string | + | Certificate value, DER+Base64 encoded. The certificate itself contains info on whether the cerificate is QSCD-enabled, data which is not represented by certificate level. cert.assuranceLevel | string | | **DEPRECATED. **Please use cert.certificateLevel parameter instead. cert.certificateLevel | string | + | Level of Smart-ID certificate: **ADVANCED** - Used for Smart-ID basic. **QUALIFIED** - Used for Smart-ID. This means that issued certificate is qualified. -additionalInfo | array | | Additional information about the result of the request. See [Additional request result info](#417-additional-request-result-info). -ignoredProperties | array | | Any values from the requestProperties that were ignored because of the Smart-ID App being too old to support them. +ignoredProperties | array | | Any values from the requestProperties that were unsupported or ignored because of the Smart-ID App being too old to support them. **successful response when still waiting for user's response:** ``` @@ -481,8 +482,7 @@ ignoredProperties | array | | Any values from the requestProperties that were "value": "B+C9XVjIAZnCHH9vfBSv...", "assuranceLevel": "http://eidas.europa.eu/LoA/substantial", "certificateLevel": "QUALIFIED" - }, - "additionalInfo": ["USER_CHOSE_CORRECT_CODE"] + } } ``` @@ -493,7 +493,7 @@ ignoredProperties | array | | Any values from the requestProperties that were * **USER_REFUSED** - user refused the session. * **TIMEOUT** - there was a timeout, i.e. end user did not confirm or refuse the operation within given timeframe. * **DOCUMENT_UNUSABLE** - for some reason, this RP request cannot be completed. User must either check his/her Smart-ID mobile application or turn to customer support for getting the exact reason. -* **USER_CHOSE_WRONG_CODE** - in case the three-choice verification code was requested, the user did not choose the correct verification code +* **WRONG_VC** - in case the three-choice verification code was requested, the user did not choose the correct verification code # 6. Protocols From ec20b3fb32773d8c294c061eacd58ad32d0d4d2d Mon Sep 17 00:00:00 2001 From: Kristjan Jalukse Date: Fri, 22 Feb 2019 17:48:20 +0200 Subject: [PATCH 5/5] SID-5407: Updated RP API markdown --- README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a23ab2f..f92c7de 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,6 @@ * [4.1.4. Response on successful session creation](#414-response-on-successful-session-creation) * [4.1.5. Idempotent behaviour](#415-idempotent-behaviour) * [4.1.6. Request properties](#416-request-properties) - * [4.1.7. Additional request result info](#417-additional-request-result-info) * [4.2. REST API main flows](#42-rest-api-main-flows) * [4.3. Certificate choice session](#43-certificate-choice-session) * [4.3.1. Preconditions](#431-preconditions) @@ -198,11 +197,11 @@ When requestor wants, it can override the idempotent behaviour inside of this ti The RP can include additional properties to some of the requests (POST to signature/ and authentication/) for requesting some desired behaviour. -The request parameter "requestProperties" can be used to include properties as a set of name/value pairs. +The request parameter "requestProperties" can be used to include properties as a set of name/value pairs. Supported property names: -* **threeChoiceVerificationCode** - Can be used to require the Smart-ID App to let the User choose the correct verification code from three differing codes, out of which one code is the real one and the other two are random codes. +* **vcChoice** - Can be used to require the Smart-ID App to let the User choose the correct verification code from multiple differing codes, out of which one code is the real one and the others are random codes. Supported property values: @@ -212,8 +211,6 @@ Supported property values: Any unsupported property will be ignored and will be listed in the "ignoredProperties" parameter of the Session status response. -Any defined property that is not supported by the Smart-ID App because the App is too old will be listed in the "ignoredProperties" parameter of the Session status response. - ## 4.2. REST API main flows ![RP API sequences](https://github.com/SK-EID/smart-id-documentation/blob/master/images/RP_API_sequences_REST.png) @@ -327,7 +324,7 @@ requestProperties | object | | A request properties object. See [Request prope "hashType": "SHA512", "displayText": "Log into internet banking system", "requestProperties": { - "threeChoiceVerificationCode": true + "vcChoice": true } } ``` @@ -397,7 +394,7 @@ requestProperties | object | | A request properties object. See [Request prope "hashType": "SHA512", "displayText": "Authorize transfer of £10", "requestProperties": { - "threeChoiceVerificationCode": true + "vcChoice": true } } ``` @@ -456,7 +453,7 @@ cert | object | for OK | Structure describing the certificate related to request cert.value | string | + | Certificate value, DER+Base64 encoded. The certificate itself contains info on whether the cerificate is QSCD-enabled, data which is not represented by certificate level. cert.assuranceLevel | string | | **DEPRECATED. **Please use cert.certificateLevel parameter instead. cert.certificateLevel | string | + | Level of Smart-ID certificate: **ADVANCED** - Used for Smart-ID basic. **QUALIFIED** - Used for Smart-ID. This means that issued certificate is qualified. -ignoredProperties | array | | Any values from the requestProperties that were unsupported or ignored because of the Smart-ID App being too old to support them. +ignoredProperties | array | | Any values from the requestProperties that were unsupported or ignored. **successful response when still waiting for user's response:** ```