Changes

RP API version 3 changes compared to version 2

This changelog outlines the key differences between Relying Party (RP) API version 3 and version 2.

New features

  • Added device link based interaction flows (QR code, Web2App, App2App) for authentication, signing, and certificate-choice.

  • Added distinct API endpoints for device link and notification based flows.

    • Example: /v3/authentication/device-link/…​ vs. /v3/authentication/notification/…​

  • App2App and Web2App device link flows include a mandatory initialCallbackUrl parameter. It is used to construct the final callback URL to which the end-user is redirected after a successful PIN entry.

  • Added new signature protocols:

    • ACSP_V2 (Authentication Context Signing Protocol)

    • RAW_DIGEST_SIGNATURE (signing pre-computed digests)

  • Added capability to link a device link based certificate-choice request to a subsequent notification based signature request via /v3/signature/notification/linked/{document-number}.

  • Added an endpoint /v3/signature/certificate/{document-number} to request signing certificates when document number is know. This means that certificate-choice should only be used now before signature sessions in cases where document number is not know (e.g., no prior Smart-ID authentication).

Security enhancements

  • To prevent replay attacks, the mandatory rpChallenge parameter (an RP-generated random value) has been introduced for all initial v3 requests, effectively replacing the nonce parameter used in v2.

  • The RSASSA-PKCS#1 v1.5 signature padding scheme has been removed and is replaced by RSASSA-PSS, which is now the only supported option for RSA signatures.

    • This change includes support for SHA-3 hash algorithms (SHA3-256, SHA3-384, SHA3-512) with RSASSA-PSS.

  • Revised Verification Code (VC) generation for notification flows:

    • Authentication flows: VC is derived from rpChallenge.

    • Signing flows: VC is randomly generated by the Smart-ID RP API server.

  • Introduced a possibility for new verification code formats in the future. For now, the existing format (four numbers) will still be the only option.

  • App2App and Web2App device link flows now require callback verification process as part of the response verification process.

API endpoint and parameter changes

  • The certificatechoice (v2) functionality is now certificate-choice (v3).

    • It has been moved to /v3/signature/certificate-choice/…​.

    • It now also supports device link based flows.

  • The allowedInteractionsOrder parameter has been renamed to interactions, and its value (a JSON array of objects) must now be Base64 encoded.

  • The standalone interaction type verificationCodeChoice has been removed. Use confirmationMessageAndVerificationCodeChoice instead for flows that require a verification code choice.

  • The RP API server now provides the device link base URL to RPs.

  • The session status response (GET /session/{sessionID}) now includes userChallenge and flowType.

  • Added interactionTypeUsed to v3 responses.

  • Added new session result.endResult status codes:

    • USER_REFUSED_INTERACTION

    • PROTOCOL_FAILURE

    • SERVER_ERROR

  • USER_REFUSED_INTERACTION replaced previous result.endResult status codes (the used interaction type is now provided separately):

    • USER_REFUSED_DISPLAYTEXTANDPIN

    • USER_REFUSED_VC_CHOICE

    • USER_REFUSED_CONFIRMATIONMESSAGE

    • USER_REFUSED_CONFIRMATIONMESSAGE_WITH_VC_CHOICE

RP API version 2 changes compared to version 1

  • Uses v2 instead of v1 in URL, {rp-api-baseurl}/v2/ instead of {rp-api-baseurl}/v1/.

  • Introduced allowedInteractionsOrder parameter to authentication and signing requests which replaces displayText and requestProperties.vcChoice parameters.

  • Added interactionTypeUsed parameter to the session status response message.

  • Added new session result.endResult status codes:

    • REQUIRED_INTERACTION_NOT_SUPPORTED_BY_APP

    • USER_REFUSED_DISPLAYTEXTANDPIN

    • USER_REFUSED_VC_CHOICE

    • USER_REFUSED_CONFIRMATIONMESSAGE

    • USER_REFUSED_CONFIRMATIONMESSAGE_WITH_VC_CHOICE

    • USER_REFUSED_CERT_CHOICE

  • Added requestProperties parameter for /v2/certificatechoice endpoint.

  • New option shareMdClientIpAddress for parameter requestProperties

  • Removed previously deprecated object reference pno/:country/:national-identity-number. Use etsi/:id-etsi-qcs-SemanticsId-Natural instead.

  • RPs must ignore any unknown names (fields) in the JSON response object.