API technical description

Relying Party API is exposed over a REST interface.

All messages are encoded using UTF-8.

All requests only support HTTP/1.1, as described in RFC 2616.

HTTP status codes

Normally, all positive responses are returned with HTTP status code 200.

In some cases, 400 series error codes are used, those cases are described per request.

All 500 series error codes indicate some kind of fatal server error.

Error responses

Smart-ID RP API returns different error codes for different error cases. However, to prevent data mining the RPs must not show different UI messages for those cases and make enumeration attacks more difficult.

In cases where the user does not have an account, HTTP status code 404 is returned by the RP API. This could be caused by the user entering wrong ID code. It is recommended that RPs verify the user ID code checksums when possible to catch these errors.

Idempotent behaviour

Whenever an RP session creation request (POST to signature/certificate-choice/ or signature/) is repeated inside a 15-second timeframe with exactly the same parameters, session ID of an existing session can be returned as a result.

This allows to retry RP POST requests in case of communication errors.

When the caller wants, it can override the idempotent behaviour inside this timeframe using an optional nonce parameter present for signature/certificate-choice and signature POST requests. Normally, that parameter can be omitted.

IMPORTANT

Providing nonce parameter is not allowed for authentication requests, since each authentication request must provide a randomly generated value for rpChallenge, making each authentication request already unique.

Interface authentication

RP API clients are authenticated based on their originating IP-address and relyingPartyUUID protocol parameter combinations.

When authentication fails, server responds with HTTP error 401.

relyingPartyName request field is case-insensitive and must match one of the names configured for the calling RP. The names are UTF-8 encoded and are displayed to the user in the Smart-ID application.

API client must ignore unknown names (fields) in JSON response object

The Smart-ID service reserves the right to add new fields into responses of the current RP API version.

Therefore, the RP must ignore unknown names (fields) in JSON response objects at any location within the JSON structure.

RP API endpoint authentication

It is essential that RP client performs all the required checks when connecting to the Smart-ID RP API HTTPS endpoint, to make sure that the connection endpoint is authentic and that the connection is secure.

This is required to prevent man-in-the-middle (MITM) attacks for the authentication and signature protocols.

The RP must perform the following checks:

  1. Verify the HTTPS connection and the TLS handshake is performed with a secure TLS cipher suite.

  2. Verify the X.509 certificate of the HTTPS endpoint belongs to the well-known public key of the Smart-ID API. The RP must implement HTTPS key (or certificate) pinning.

  3. Verify the X.509 certificate of the HTTPS endpoint is valid (not expired, signed by trusted CA and not revoked).

In case the RP fails to verify the connection is genuine and secure an attacker might be able to launch a MITM attack on the connection and either login as the user or have the user sign a forged document.