Merge remote-tracking branch 'origin/chore/callback-validation-docu' into...

Merge remote-tracking branch 'origin/chore/callback-validation-docu' into 775-validate_schema_attribute

README.md

@@ -229,6 +229,26 @@ Current status for submission 43cf7163-5163-4bc8-865e-be96e271ecc3 => incomplete
 
 <img src="https://docs.fitko.de/fit-connect/assets/images/status-ebe91122f32321e22f094882a66c1139.svg">
 
+### Validating callbacks
+
+When receiving callbacks from the FIT-Connect system, sender (and subscriber) of submissions have to check if the received data is valid to prevent unauthorized calls from messing with the business processes and user data. The values needed for this validation are transmitted  within the received HTTP requests. FIT-Connect uses the HMAC mechanism to proof the validity of its calls.
+
+More details on how this method works can be found here:
+- https://docs.fitko.de/fit-connect/docs/details/callbacks/#callback-validation
+- https://www.rfc-editor.org/rfc/rfc2104
+
+The Java SDK provides a convenient method for validating callbacks, its usage could look like this:
+
+```java
+final SenderClient senderClient = ClientFactory.senderClient(config);
+
+final ValidationResult validationResult = senderClient.validateCallback("hmac", 0L, "body", "secret");
+
+if(validationResult.hasError()){
+    LOGGER.error(validationresult.getError().getMessage());
+}
+```
+
 ## API Usage for Subscriber
 
 ### Retrieving submissions
@@ -339,6 +359,20 @@ The log contains the event, issuer and occurred problems like shown in the examp
 For more details please see the [event-log documentation](https://docs.fitko.de/fit-connect/docs/getting-started/event-log/overview). 
 <p align="right">(<a href="#top">back to top</a>)</p>
 
+### Validating callbacks
+
+The validation of callbacks works similar to the sender side (see [Sender Callback Validation](#validating-callbacks)), but instead of the `SenderClient`, we use the `SubscriberClient`:
+
+```java
+final SubscriberClient subscriberClient = ClientFactory.subscriberClient(config);
+
+final ValidationResult validationResult = subscriberClient.validateCallback("hmac", 0L, "body", "secret");
+
+if(validationResult.hasError()){
+    LOGGER.error(validationresult.getError().getMessage());
+}
+```
+
 ## Roadmap
 - [ ] Add Routing features
 - [ ] Add Callback validation

client/src/main/java/dev/fitko/fitconnect/client/SenderClient.java

@@ -70,8 +70,17 @@ public class SenderClient {
         return sender.getLastedEvent(destinationId, caseId, submissionId, authenticationTags);
     }
 
-    public ValidationResult validateCallback(String hmac, Long timestamp, String httpBody, String callbackSecret) {
-        return this.sender.validateCallback(hmac, timestamp, httpBody, callbackSecret);
+    /**
+     * Checks if a received callback can be trusted by validating the provided request data.
+     *
+     * @param hmac           authentication code provided by the callback
+     * @param timestamp      timestamp provided by the callback
+     * @param httpBody       HTTP body provided by the callback
+     * @param callbackSecret secret owned by the client, which is used to calculate the hmac
+     * @return {@code true} if hmac and timestamp provided by the callback meet the required conditions
+     */
+    public ValidationResult validateCallback(final String hmac, final Long timestamp, final String httpBody, final String callbackSecret) {
+        return sender.validateCallback(hmac, timestamp, httpBody, callbackSecret);
     }
 
     /**