Merge branch 'RM-5029_interaction_params' into 'master'

RM-5029: SID/MID interaction params usage description

See merge request cdoc2/cdoc2-java-ref-impl!111

Author: Olesja Aarma

cdoc2-lib/README.md

@@ -475,6 +475,35 @@ List<String> extractedFiles = new CDocDecrypter()
         .decrypt();
 ```
 
+
+### User interaction with Smart ID and Mobile ID clients
+Smart ID and Mobile ID clients interact with user by display messages and verification code.
+Available interactions are implemented in a class `InteractionParams`, which can be of
+following types `InteractionParams.InteractionType`:
+* DISPLAY_TEXT_AND_PIN
+* CONFIRMATION_MESSAGE
+* VERIFICATION_CODE_CHOICE
+* CONFIRMATION_MESSAGE_AND_VERIFICATION_CODE_CHOICE
+
+Initialized `InteractionParams` will be transferred to Smart ID and Mobile ID clients while
+authenticating.
+
+`InteractionParams` can be configured by initializing `KeyShareDecryptionKeyMaterial`
+with method `InteractionParamsConfigurable.init()` while decrypting:
+```java
+    private static void addInteractionParameters(File cdocFile, DecryptionKeyMaterial dkm) {
+        if (dkm instanceof InteractionParamsConfigurable paramsConfigurable) {
+
+            InteractionParams interactionParams = (cdocFile == null)
+                ? InteractionParams.displayTextAndPin()
+                : InteractionParams.displayTextAndVCCForDocument(cdocFile.toPath().getFileName().toString());
+            interactionParams.addAuthListener(e -> System.out.println("Verification code:" + e.getVerificationCode()));
+            paramsConfigurable.init(interactionParams);
+        }
+    }
+```
+
+
 ## Long-term crypto
 
 Scenarios with id-card are meant for transport cryptography only as id-card certificates expiry and

cdoc2-lib/src/main/java/ee/cyber/cdoc2/crypto/jwt/InteractionParams.java

@@ -7,6 +7,7 @@
 import java.util.LinkedList;
 import java.util.List;
 
+
 /**
  * Smart-ID and Mobile-ID interaction parameters.
  * Optional parameters to drive user interaction and to get verification code.
@@ -28,7 +29,6 @@ public enum InteractionType {
         CONFIRMATION_MESSAGE_AND_VERIFICATION_CODE_CHOICE
     }
 
-
     /** Default text for Smart-ID. Max length 60 chars. Default text for MID is defined in mobile-id.properties */
     public static final String DEFAULT_DISPLAY_TEXT = "Authenticate to decrypt CDOC2 document";
 
@@ -119,7 +119,6 @@ public void setEncoding(String encoding) {
         this.encoding = encoding;
     }
 
-
     /** Get text displayed. If text is longer than 200 chars, will be capped to 200 chars */
     public String getDisplayText200() {
         return getDisplayText(200);
@@ -160,4 +159,5 @@ public void notifyAuthListeners(AuthEvent event) {
             listener.authStarted(event);
         }
     }
+
 }