Merge branch 'master' into legacy-signature-algorithms

Author: kaidohallik

MIGRATION_GUIDE.md

@@ -65,7 +65,7 @@ It is recommended to start using device-link authentication flows from Smart-ID
 3. Replace showing verification code with showing device link or QR-code. Recommended to use device link for same device and QR-code for cross-device authentication.
    - [Create device link or QR-code](README.md#generating-qr-code-or-device-link) from values in session response and display it to the user. QR-code should be recreated after every second.
 4. Querying session status can be done in parallel while displaying device content. Check out [session status poller](README.md#example-of-using-session-status-poller-to-query-final-sessions-status). `ee.sk.smartid.SmartIdClient` provides method `getSessionsStatusPoller()` to get version specific session status poller.
-5. When session status state is `COMPLETE` polling will be stopped and [response should be checked](README.md#example-of-validating-the-authentication-sessions-response) with `AuthenticationResponseValidator`. It will validate required fields, certificate and signature value in sessions status, and it will also handler errors.
+5. When session status state is `COMPLETE` polling will be stopped and [response should be checked](README.md#example-of-validating-the-authentication-sessions-response) with `DeviceLinkAuthenticationResponseValidator` or `NotificationAuthenticationResponseValidator` (depending on the flow). They will validate required fields, certificate and signature value in sessions status, and they will also handle errors.
 6. If everything is ok `AuthenticationIdentity` will be returned. AuthenticationIdentity is same as used for V2.
 
 ## Migrating signing

README.md

@@ -231,16 +231,16 @@ Anonymous authentication is a new feature in Smart-ID API v3.1. It allows to aut
 RP can learn the user's identity only after the user has authenticated themselves.
 
 ```java
-// For security reasons a new hash value must be created for each new authentication request
-String rpChallenge = RpChallengeGenerator.generate();
+// For security reasons a new RP challenge must be created for each new authentication request
+RpChallenge rpChallenge = RpChallengeGenerator.generate();
 // Store generated rpChallenge only on backend side. Do not expose it to the client side. 
 // Used for validating authentication sessions status OK response
 
 // Set up builder
 DeviceLinkAuthenticationSessionRequestBuilder builder = smartIdClient
         .createDeviceLinkAuthentication()
         // to use anonymous authentication, do not set semantics identifier or document number
-        .withRpChallenge(rpChallenge)
+        .withRpChallenge(rpChallenge.toBase64EncodedValue())
         .withSignatureAlgorithm(AuthenticationSignatureAlgorithm.RSASSA_PSS)
         .withHashAlgorithm(HashAlgorithm.SHA3_512)
         .withInteractions(Collections.singletonList(
@@ -805,15 +805,16 @@ if ("RUNNING".equalsIgnoreCase(sessionStatus.getState())) {
 ### Validating session status response
 
 It's important to validate the session status response to ensure that the returned signature or authentication result is valid.
-For validating authentication session status response, use the `AuthenticationResponseValidator`.
+For validating authentication session status response, use `DeviceLinkAuthenticationResponseValidator` for device link flows
+and `NotificationAuthenticationResponseValidator` for notification-based flows.
 For validating signature session status response, use the `SignatureResponseValidator`.
 NB! Integrators must validate signature value against expected signature value.
 
 #### Set up CertificateValidator
 
 CertificateValidator will check if the certificate is not expired and is trusted
 by constructing certificate chain with trust anchors and intermediate CA certificates provided in the TrustedCACertStore.
-Will be used by AuthenticationResponseValidator and SignatureResponseValidator.
+Will be used by DeviceLinkAuthenticationResponseValidator, NotificationAuthenticationResponseValidator, CertificateChoiceResponseValidator and SignatureResponseValidator.
 
 ```java
 // Set up TrustedCACertStore
@@ -848,11 +849,12 @@ CertificateValidator certificateValidator = new CertificateValidatorImpl(trusted
 DeviceLinkAuthenticationResponseValidator depends on CertificateValidator. Checkout [setting up CertificateValidator](#set-up-certificatevalidator) 
 
 ```java
-// Set up AuthenticationResponseValidator with the CertificateValidator
-DeviceLinkAuthenticationResponseValidator deviceLinkAuthenticationResponseValidator = new AuthenticationResponseValidator(certificateValidator);
+// Set up DeviceLinkAuthenticationResponseValidator with the CertificateValidator
+DeviceLinkAuthenticationResponseValidator deviceLinkAuthenticationResponseValidator =
+        DeviceLinkAuthenticationResponseValidator.defaultSetupWithCertificateValidator(certificateValidator);
 
 // Create authentication request builder
-DeviceLinkAuthenticationSessionRequestBuilder authenticationRequestBuilder =  smartIdClient.createDeviceLinkAuthentication()...;
+DeviceLinkAuthenticationSessionRequestBuilder authenticationRequestBuilder = smartIdClient.createDeviceLinkAuthentication()...;
 // Initialize session
 DeviceLinkSessionResponse sessionResponse = authenticationRequestBuilder.initAuthenticationSession();
 // Get request used for starting the authentication session and use it later to validate sessions status response
@@ -863,9 +865,13 @@ SessionStatusPoller poller = smartIdClient.getSessionStatusPoller();
 SessionStatus sessionStatus = poller.fetchFinalSessionStatus(sessionResponse.sessionID());
 
 // validate sessions state is completed
-if("COMPLETE".equals(sessionStatus.getState())){
+if ("COMPLETE".equals(sessionStatus.getState())) {
+    // For same-device flows (Web2App/App2App), get userChallengeVerifier from callback URL
+    String userChallengeVerifier = "<userChallengeVerifier-from-callback-url>";
+
     // validate the session status response with authentication session request and return authentication identity
-    AuthenticationIdentity authenticationIdentity = deviceLinkAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, "smart-id-demo");
+    AuthenticationIdentity authenticationIdentity =
+            deviceLinkAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, userChallengeVerifier, "smart-id-demo");
 }
 ```
 
@@ -874,11 +880,12 @@ if("COMPLETE".equals(sessionStatus.getState())){
 NotificationAuthenticationResponseValidator depends on CertificateValidator. Checkout [setting up CertificateValidator](#set-up-certificatevalidator)
 
 ```java
-// Set up AuthenticationResponseValidator with the CertificateValidator
-NotificationAuthenticationResponseValidator notificationAuthenticationResponseValidator = new AuthenticationResponseValidator(certificateValidator);
+// Set up NotificationAuthenticationResponseValidator with the CertificateValidator
+NotificationAuthenticationResponseValidator notificationAuthenticationResponseValidator =
+        NotificationAuthenticationResponseValidator.defaultSetupWithCertificateValidator(certificateValidator);
 
 // Create authentication request builder
-NotificationAuthenticationSessionRequestBuilder authenticationRequestBuilder =  smartIdClient.createDeviceLinkAuthentication()...;
+NotificationAuthenticationSessionRequestBuilder authenticationRequestBuilder = smartIdClient.createNotificationAuthentication()...;
 // Initialize session
 NotificationAuthenticationSessionResponse sessionResponse = authenticationRequestBuilder.initAuthenticationSession();
 // Get request used for starting the authentication session and use it later to validate sessions status response
@@ -889,9 +896,10 @@ SessionStatusPoller poller = smartIdClient.getSessionStatusPoller();
 SessionStatus sessionStatus = poller.fetchFinalSessionStatus(sessionResponse.sessionID());
 
 // validate sessions state is completed
-if("COMPLETE".equals(sessionStatus.getState())){
+if ("COMPLETE".equals(sessionStatus.getState())) {
     // validate the session status response with authentication session request and return authentication identity
-    AuthenticationIdentity authenticationIdentity = notificationAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, "smart-id-demo");
+    AuthenticationIdentity authenticationIdentity =
+            notificationAuthenticationResponseValidator.validate(sessionStatus, authenticationSessionRequest, "smart-id-demo");
 }
 ```
 

src/main/java/ee/sk/smartid/AuthenticationResponseMapperImpl.java

@@ -224,14 +224,14 @@ private static void validateSignatureAlgorithmParameters(SessionSignature sessio
         }
         Optional<HashAlgorithm> maskGenHashAlgorithm = HashAlgorithm.fromString(maskGenAlgorithm.getParameters().getHashAlgorithm());
         if (maskGenHashAlgorithm.isEmpty()) {
-            logger.error("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.hashAlgorithm' has invalid value: {}", maskGenAlgorithm.getParameters().getHashAlgorithm());
+            logger.error("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' has invalid value: {}", maskGenAlgorithm.getParameters().getHashAlgorithm());
             throw new UnprocessableSmartIdResponseException("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' has unsupported value");
         }
         if (hashAlgorithm.get() != maskGenHashAlgorithm.get()) {
-            logger.error("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.hashAlgorithm' and 'signature.signatureAlgorithmParameters.hashAlgorithm' do not match. Expected: {}, actual: {}",
+            logger.error("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' and 'signature.signatureAlgorithmParameters.hashAlgorithm' do not match. Expected: {}, actual: {}",
                     hashAlgorithm.get().getAlgorithmName(),
                     maskGenHashAlgorithm.get().getAlgorithmName());
-            throw new UnprocessableSmartIdResponseException("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.hashAlgorithm' value does not match 'signature.signatureAlgorithmParameters.hashAlgorithm' value");
+            throw new UnprocessableSmartIdResponseException("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' value does not match 'signature.signatureAlgorithmParameters.hashAlgorithm' value");
         }
 
         if (signatureAlgorithmParameters.getSaltLength() == null) {

src/test/java/ee/sk/smartid/AuthenticationResponseMapperImplTest.java

@@ -4,7 +4,7 @@
  * #%L
  * Smart ID sample Java client
  * %%
- * Copyright (C) 2018 - 2025 SK ID Solutions AS
+ * Copyright (C) 2018 - 2026 SK ID Solutions AS
  * %%
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -30,9 +30,11 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
+import ch.qos.logback.classic.Level;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.ArgumentsSource;
 import org.junit.jupiter.params.provider.EnumSource;
@@ -49,11 +51,18 @@
 import ee.sk.smartid.rest.dao.SessionSignature;
 import ee.sk.smartid.rest.dao.SessionSignatureAlgorithmParameters;
 import ee.sk.smartid.rest.dao.SessionStatus;
+import ee.sk.smartid.testhelper.log.Logs;
+import ee.sk.smartid.testhelper.log.LogsSpy;
+import ee.sk.smartid.testhelper.log.LogsSpyExtension;
 
+@ExtendWith(LogsSpyExtension.class)
 class AuthenticationResponseMapperImplTest {
 
     private static final String AUTH_CERT = FileUtil.readFileToString("test-certs/auth-cert-40504040001.pem.crt");
 
+    @Logs
+    private LogsSpy logs;
+
     private AuthenticationResponseMapper authenticationResponseMapper;
 
     @BeforeEach
@@ -439,6 +448,9 @@ void from_hashAlgorithmIsInvalid_throwException(String invalidHashAlgorithm) {
                 var sessionStatus = toSessionStatus(sessionResult, sessionSignature);
 
                 var exception = assertThrows(UnprocessableSmartIdResponseException.class, () -> authenticationResponseMapper.from(sessionStatus));
+
+                logs.shouldHave(Level.ERROR, "Authentication session status field 'signature.signatureAlgorithmParameters.hashAlgorithm' has invalid value: " + invalidHashAlgorithm);
+
                 assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.hashAlgorithm' has unsupported value", exception.getMessage());
             }
 
@@ -487,6 +499,9 @@ void from_algorithmValueInMaskGenAlgorithmIsInvalid_throwException() {
                 var sessionStatus = toSessionStatus(sessionResult, sessionSignature);
 
                 var exception = assertThrows(UnprocessableSmartIdResponseException.class, () -> authenticationResponseMapper.from(sessionStatus));
+
+                logs.shouldHave(Level.ERROR, "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm' has invalid value: " + maskGenAlgorithm.getAlgorithm());
+
                 assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm' has unsupported value", exception.getMessage());
             }
 
@@ -549,6 +564,9 @@ void from_hashAlgorithmInMaskGenAlgorithmParametersInvalid_throwException(String
                 var sessionStatus = toSessionStatus(sessionResult, sessionSignature);
 
                 var exception = assertThrows(UnprocessableSmartIdResponseException.class, () -> authenticationResponseMapper.from(sessionStatus));
+
+                logs.shouldHave(Level.ERROR, "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' has invalid value: " + maskGenAlgorithmParameters.getHashAlgorithm());
+
                 assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' has unsupported value", exception.getMessage());
             }
 
@@ -570,7 +588,10 @@ void from_hashAlgorithmInMaskGenAlgorithmDoesNotMatchSignaturesHashAlgorithm_thr
                 var sessionStatus = toSessionStatus(sessionResult, sessionSignature);
 
                 var exception = assertThrows(UnprocessableSmartIdResponseException.class, () -> authenticationResponseMapper.from(sessionStatus));
-                assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.hashAlgorithm' value does not match 'signature.signatureAlgorithmParameters.hashAlgorithm' value", exception.getMessage());
+
+                logs.shouldHave(Level.ERROR, "Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' and 'signature.signatureAlgorithmParameters.hashAlgorithm' do not match. Expected: SHA3-512, actual: SHA-512");
+
+                assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.maskGenAlgorithm.parameters.hashAlgorithm' value does not match 'signature.signatureAlgorithmParameters.hashAlgorithm' value", exception.getMessage());
             }
 
             @Test
@@ -608,6 +629,9 @@ void from_saltLengthDoesNotMatchHashAlgorithmOctetLength_throwException() {
                 var sessionStatus = toSessionStatus(sessionResult, sessionSignature);
 
                 var exception = assertThrows(UnprocessableSmartIdResponseException.class, () -> authenticationResponseMapper.from(sessionStatus));
+
+                logs.shouldHave(Level.ERROR, "Authentication session status field 'signature.signatureAlgorithmParameters.saltLength' has invalid value. Expected: 64, actual: 20");
+
                 assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.saltLength' has invalid value", exception.getMessage());
             }
 
@@ -649,6 +673,9 @@ void from_trailerFieldValueIsInvalid_throwException() {
                 var sessionStatus = toSessionStatus(sessionResult, sessionSignature);
 
                 var exception = assertThrows(UnprocessableSmartIdResponseException.class, () -> authenticationResponseMapper.from(sessionStatus));
+
+                logs.shouldHave(Level.ERROR, "Authentication session status field 'signature.signatureAlgorithmParameters.trailerField' has invalid value: invalid");
+
                 assertEquals("Authentication session status field 'signature.signatureAlgorithmParameters.trailerField' has unsupported value", exception.getMessage());
             }
 

src/test/java/ee/sk/smartid/testhelper/log/Logs.java

@@ -0,0 +1,39 @@
+package ee.sk.smartid.testhelper.log;
+
+/*-
+ * #%L
+ * Smart ID sample Java client
+ * %%
+ * Copyright (C) 2018 - 2026 SK ID Solutions AS
+ * %%
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ * #L%
+ */
+
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target({ ElementType.FIELD, ElementType.PARAMETER })
+@Retention(RetentionPolicy.RUNTIME)
+@ExtendWith(LogsSpyExtension.class)
+public @interface Logs {}