Fix #1262: FIDO2: Write JavaDoc for classes and methods (#1274)

powerauth-client-model/src/main/java/com/wultra/security/powerauth/client/model/error/PowerAuthClientException.java

@@ -33,7 +33,7 @@ public class PowerAuthClientException extends Exception {
     private final PowerAuthError powerAuthError;
 
     /**
-     * Default constructor.
+     * No-arg constructor.
      */
     public PowerAuthClientException() {
         this.powerAuthError = null;

powerauth-client-model/src/main/java/com/wultra/security/powerauth/client/model/error/PowerAuthErrorRecovery.java

@@ -27,7 +27,7 @@ public class PowerAuthErrorRecovery extends PowerAuthError {
     private int currentRecoveryPukIndex;
 
     /**
-     * Default constructor.
+     * No-arg constructor.
      */
     public PowerAuthErrorRecovery() {
     }

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/errorhandling/Fido2AuthenticationFailedException.java

@@ -30,10 +30,19 @@ public class Fido2AuthenticationFailedException extends Exception {
     @Serial
     private static final long serialVersionUID = -3214199555928548491L;
 
+    /**
+     * Exception constructor with message.
+     * @param message Exception message.
+     */
     public Fido2AuthenticationFailedException(String message) {
         super(message);
     }
 
+    /**
+     * Exception constructor with message and cause.
+     * @param message Exception message.
+     * @param cause Exception cause.
+     */
     public Fido2AuthenticationFailedException(String message, Throwable cause) {
         super(message, cause);
     }

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/errorhandling/Fido2DeserializationException.java

@@ -31,10 +31,19 @@ public class Fido2DeserializationException extends IOException {
     @Serial
     private static final long serialVersionUID = 1835532378587759773L;
 
+    /**
+     * Exception constructor with message.
+     * @param message Exception message.
+     */
     public Fido2DeserializationException(String message) {
         super(message);
     }
 
+    /**
+     * Exception constructor with message and cause.
+     * @param message Exception message.
+     * @param cause Exception cause.
+     */
     public Fido2DeserializationException(String message, Throwable cause) {
         super(message, cause);
     }

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/rest/controller/AssertionController.java

@@ -54,12 +54,23 @@ public class AssertionController {
     private final AssertionRequestValidator assertionRequestValidator;
     private final AssertionService assertionService;
 
+    /**
+     * Assertion controller constructor.
+     * @param assertionRequestValidator Assertion request validator.
+     * @param assertionService Assertion service.
+     */
     @Autowired
     public AssertionController(AssertionRequestValidator assertionRequestValidator, AssertionService assertionService) {
         this.assertionRequestValidator = assertionRequestValidator;
         this.assertionService = assertionService;
     }
 
+    /**
+     * Request generating of an assertion challenge for an operation.
+     * @param request Assertion challenge request.
+     * @return Assertion challenge response.
+     * @throws Exception Thrown in case assertion challenge could not be generated.
+     */
     @Operation(
             summary = "Generate an assertion challenge",
             description = "Generate a FIDO2 assertion challenge for an operation."
@@ -76,13 +87,19 @@ public ObjectResponse<AssertionChallengeResponse> requestAssertionChallenge(@Val
         return new ObjectResponse<>(assertionChallengeResponse);
     }
 
+    /**
+     * Verify a FIDO2 assertion for an operation.
+     * @param request Verify an assertion request.
+     * @return Verify an assertion response.
+     * @throws Fido2AuthenticationFailedException Thrown in case assertion validation fails.
+     */
     @Operation(
             summary = "Verify an assertion",
             description = "Verify a FIDO2 assertion for an operation based on an assertion verification request generated and signed by the authenticator."
     )
     @ApiResponses(value = {
             @ApiResponse(responseCode = "200", description = "Assertion verification succeeded"),
-            @ApiResponse(responseCode = "400", description = "Invalid request or assertion  verification failed"),
+            @ApiResponse(responseCode = "400", description = "Invalid request or assertion verification failed"),
             @ApiResponse(responseCode = "500", description = "Unexpected server error")
     })
     @PostMapping

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/rest/controller/RegistrationController.java

@@ -54,11 +54,21 @@ public class RegistrationController {
 
     private final RegistrationService registrationService;
 
+    /**
+     * Registration controller constructor.
+     * @param registrationService Registration service.
+     */
     @Autowired
     public RegistrationController(RegistrationService registrationService) {
         this.registrationService = registrationService;
     }
 
+    /**
+     * Obtain a list of registered FIDO2 authenticators.
+     * @param request Registered authenticators list request.
+     * @return Registered authenticators list response.
+     * @throws Exception Thrown in case registered authenticators list could not be obtained.
+     */
     @Operation(
             summary = "List registered authenticators",
             description = "Obtain a list of registered FIDO2 authenticators for specified user."
@@ -71,10 +81,16 @@ public RegistrationController(RegistrationService registrationService) {
     @PostMapping("list")
     public ObjectResponse<RegisteredAuthenticatorsResponse> registeredAuthenticators(@Valid @RequestBody ObjectRequest<RegisteredAuthenticatorsRequest> request) throws Exception {
         final RegisteredAuthenticatorsRequest requestObject = request.getRequestObject();
-        final RegisteredAuthenticatorsResponse responseObject = registrationService.registrationsForUser(requestObject.getUserId(), requestObject.getApplicationId());
+        final RegisteredAuthenticatorsResponse responseObject = registrationService.listRegistrationsForUser(requestObject.getUserId(), requestObject.getApplicationId());
         return new ObjectResponse<>(responseObject);
     }
 
+    /**
+     * Request a registration challenge.
+     * @param request Registration challenge request.
+     * @return Registration challenge response.
+     * @throws Exception Thrown in case registration challenge could not be generated.
+     */
     @Operation(
             summary = "Generate a registration challenge",
             description = "Generate a FIDO2 registration challenge for specified user."
@@ -91,6 +107,12 @@ public ObjectResponse<RegistrationChallengeResponse> requestRegistrationChalleng
         return new ObjectResponse<>(responseObject);
     }
 
+    /**
+     * Register an authenticator.
+     * @param request Register an authenticator request.
+     * @return Register an authenticator response.
+     * @throws Exception Thrown in case registration fails.
+     */
     @Operation(
             summary = "Register an authenticator",
             description = "Register a FIDO2 authenticator based on a registration request generated and signed by the authenticator."

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/rest/model/converter/AssertionConverter.java

@@ -32,6 +32,12 @@
 @Slf4j
 public class AssertionConverter {
 
+    /**
+     * Convert authenticator detail to assertion verification response.
+     * @param source Authenticator detail.
+     * @param assertionValid Whether assertion is valid.
+     * @return Converted assertion verification response.
+     */
     public AssertionVerificationResponse fromAuthenticatorDetail(AuthenticatorDetail source, boolean assertionValid) {
         if (source == null) {
             return null;

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/rest/model/converter/RegistrationConverter.java

@@ -45,6 +45,14 @@ public class RegistrationConverter {
 
     private final AaguidList aaguidRegistry = new AaguidList();
 
+    /**
+     * Convert registration challenge to authenticator detail.
+     * @param challenge Registration challenge.
+     * @param requestObject Registration request.
+     * @param aaguid AAGUID bytes.
+     * @param publicKey Public key bytes.
+     * @return Authenticator detail, if present.
+     */
     public Optional<AuthenticatorDetail> convert(RegistrationChallenge challenge, RegistrationRequest requestObject, byte[] aaguid, byte[] publicKey) {
         try {
             final AuthenticatorDetail authenticatorDetail = new AuthenticatorDetail();
@@ -70,19 +78,11 @@ public Optional<AuthenticatorDetail> convert(RegistrationChallenge challenge, Re
         }
     }
 
-    private Map<String, Object> convertExtras(RegistrationRequest requestObject) throws JsonProcessingException {
-        final AuthenticatorParameters authenticatorParameters = requestObject.getAuthenticatorParameters();
-        final Map<String, Object> params = new HashMap<>();
-        params.put("relyingPartyId", authenticatorParameters.getRelyingPartyId());
-        params.put("authenticatorAttachment", authenticatorParameters.getAuthenticatorAttachment());
-        params.put("credentialId", authenticatorParameters.getResponse().getAttestationObject().getAuthData().getAttestedCredentialData().getCredentialId());
-        params.put("origin", authenticatorParameters.getResponse().getClientDataJSON().getOrigin());
-        params.put("topOrigin", authenticatorParameters.getResponse().getClientDataJSON().getTopOrigin());
-        params.put("isCrossOrigin", authenticatorParameters.getResponse().getClientDataJSON().isCrossOrigin());
-        params.put("aaguid", authenticatorParameters.getResponse().getAttestationObject().getAuthData().getAttestedCredentialData().getAaguid());
-        return params;
-    }
-
+    /**
+     * Convert authenticator detail to registration response.
+     * @param source Authenticator detail.
+     * @return Registration response.
+     */
     public RegistrationResponse convertRegistrationResponse(AuthenticatorDetail source) {
         final RegistrationResponse result = new RegistrationResponse();
         result.setUserId(source.getUserId());
@@ -101,4 +101,18 @@ public RegistrationResponse convertRegistrationResponse(AuthenticatorDetail sour
         result.setMaxFailedAttempts(source.getMaxFailedAttempts());
         return result;
     }
+
+    private Map<String, Object> convertExtras(RegistrationRequest requestObject) throws JsonProcessingException {
+        final AuthenticatorParameters authenticatorParameters = requestObject.getAuthenticatorParameters();
+        final Map<String, Object> params = new HashMap<>();
+        params.put("relyingPartyId", authenticatorParameters.getRelyingPartyId());
+        params.put("authenticatorAttachment", authenticatorParameters.getAuthenticatorAttachment());
+        params.put("credentialId", authenticatorParameters.getResponse().getAttestationObject().getAuthData().getAttestedCredentialData().getCredentialId());
+        params.put("origin", authenticatorParameters.getResponse().getClientDataJSON().getOrigin());
+        params.put("topOrigin", authenticatorParameters.getResponse().getClientDataJSON().getTopOrigin());
+        params.put("isCrossOrigin", authenticatorParameters.getResponse().getClientDataJSON().isCrossOrigin());
+        params.put("aaguid", authenticatorParameters.getResponse().getAttestationObject().getAuthData().getAttestedCredentialData().getAaguid());
+        return params;
+    }
+
 }

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/rest/model/converter/serialization/AttestationObjectDeserializer.java

@@ -32,6 +32,8 @@
 import java.util.Base64;
 
 /**
+ * JSON deserializer for the attestation object.
+ *
  * @author Petr Dvorak, [email protected]
  */
 @Component
@@ -43,14 +45,28 @@ public class AttestationObjectDeserializer extends StdDeserializer<AttestationOb
 
     private final CBORMapper cborMapper = new CBORMapper();
 
+    /**
+     * No-arg deserializer constructor.
+     */
     public AttestationObjectDeserializer() {
         this(null);
     }
 
+    /**
+     * Deserializer constructor with value class parameter.
+     * @param vc Value class.
+     */
     public AttestationObjectDeserializer(Class<?> vc) {
         super(vc);
     }
 
+    /**
+     * Deserialize the FIDO2 attestation object from JSON request.
+     * @param jsonParser JSON parser.
+     * @param deserializationContext Deserialization context.
+     * @return Deserialized FIDO2 attestation object.
+     * @throws Fido2DeserializationException Thrown in case JSON deserialization fails.
+     */
     @Override
     public AttestationObject deserialize(JsonParser jsonParser, DeserializationContext deserializationContext) throws Fido2DeserializationException {
         try {

powerauth-fido2/src/main/java/com/wultra/powerauth/fido2/rest/model/converter/serialization/AttestationStatementDeserializer.java

@@ -22,6 +22,7 @@
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
+import com.wultra.powerauth.fido2.errorhandling.Fido2DeserializationException;
 import com.wultra.powerauth.fido2.rest.model.entity.AttestationStatement;
 import com.wultra.powerauth.fido2.rest.model.enumeration.SignatureAlgorithm;
 import lombok.extern.slf4j.Slf4j;
@@ -32,6 +33,8 @@
 import java.util.Map;
 
 /**
+ * JSON deserializer for the attestation statement.
+ *
  * @author Petr Dvorak, [email protected]
  */
 @Component
@@ -41,25 +44,44 @@ public class AttestationStatementDeserializer extends StdDeserializer<Attestatio
     @Serial
     private static final long serialVersionUID = -3598363993363470844L;
 
+    /**
+     * No-arg deserializer constructor.
+     */
     public AttestationStatementDeserializer() {
         this(null);
     }
 
+    /**
+     * Deserializer constructor with value class parameter.
+     * @param vc Value class.
+     */
     public AttestationStatementDeserializer(Class<AttestationStatement> vc) {
         super(vc);
     }
 
+    /**
+     * Deserialize the FIDO2 attestation object from JSON request.
+     * @param jsonParser JSON parser.
+     * @param deserializationContext Deserialization context.
+     * @return Deserialized FIDO2 attestation statement.
+     * @throws Fido2DeserializationException Thrown in case JSON deserialization fails.
+     */
     @Override
-    public AttestationStatement deserialize(JsonParser jsonParser, DeserializationContext deserializationContext) throws IOException {
-        final Map<String, Object> map = jsonParser.readValueAs(new TypeReference<>() {});
-        final AttestationStatement result = new AttestationStatement();
-        final Integer alg = (Integer) map.get("alg");
-        if (alg != null && -7 == alg) {
-            result.setAlgorithm(SignatureAlgorithm.ES256);
-        } else {
-            result.setAlgorithm(SignatureAlgorithm.UNKNOWN);
+    public AttestationStatement deserialize(JsonParser jsonParser, DeserializationContext deserializationContext) throws Fido2DeserializationException {
+        try {
+            final Map<String, Object> map = jsonParser.readValueAs(new TypeReference<>() {});
+            final AttestationStatement result = new AttestationStatement();
+            final Integer alg = (Integer) map.get("alg");
+            if (alg != null && -7 == alg) {
+                result.setAlgorithm(SignatureAlgorithm.ES256);
+            } else {
+                result.setAlgorithm(SignatureAlgorithm.UNKNOWN);
+            }
+            result.setSignature((byte[]) map.get("sig"));
+            return result;
+        } catch (IOException e) {
+            logger.debug(e.getMessage(), e);
+            throw new Fido2DeserializationException(e.getMessage(), e);
         }
-        result.setSignature((byte[]) map.get("sig"));
-        return result;
     }
 }