Add or update documentation with info related to signature validation

Author: Bogdan Mocanu

README.md

@@ -31,6 +31,7 @@ To start using the Swisscom Mobile ID service and this client library, follow th
 5. Learn about the code and the overall architecture of the client. See the [ARCHITECTURE.md](ARCHITECTURE.md) file
 
 For extra help:
+- [How to validate signatures](/docs/validate-signatures.md)
 - [How to use an HTTP proxy with or without authentication](/docs/configure-proxy-connection.md) 
 - [How to solve the most common problems](/docs/troubleshoot-common-problems.md)
 

docs/validate-signatures.md

@@ -0,0 +1,64 @@
+# Validate signature after a successful authentication/authorization process
+
+After successfully performing a mobile signature process, it is a good idea to validate the obtained signature, to ensure it is correct from the 
+following point of views:
+* the signing certificate (user certificate) is still valid
+* the signing certificate has a valid certificate path (it roots to a Certification Authority that is trusted in the context of the client)
+* the performed signature is correct
+* the DTBD/DTBS that was requested is identical to the one that was signed
+
+We start first with the code for performing a mobile signature:
+
+```java
+ClientConfiguration config = new ClientConfiguration();
+// set all the configuration parameters for the client
+    
+// use the config to create a new client; do this only once per application
+MIDClient client = new MIDClientImpl(config);
+
+// configure the request and send it to the Mobile ID backend
+SignatureRequest request = new SignatureRequest();
+request.getDataToBeSigned().setData("Test: Do you want to login?");
+request.setUserLanguage(UserLanguage.ENGLISH);
+request.getMobileUser().setMsisdn("41790000000");
+request.setSignatureProfile(SignatureProfiles.DEFAULT_PROFILE);
+
+SignatureResponse response = client.requestSyncSignature(request);
+
+if (response.getStatus().getStatusCode() == StatusCode.SIGNATURE) {
+    // at this point, we have successfully acquired a mobile signature
+    // you can find it in response.getBase64Signature(), as a Base64-encoded CMS content
+    
+    // let's validate it
+    
+    // just like the client, the signature validator needs a bit of configuration
+    SignatureValidationConfiguration svConfig = new SignatureValidationConfiguration();
+    // you can also set the truststore as a classpath file or as a byte array
+    svConfig.setTrustStoreFile("signature-validation-truststore.jks");
+    svConfig.setTrustStoreType("jks")
+    svConfig.setTrustStorePassword("secret"); // optional
+    
+    // now, with the config, let's create the signature validator and use it
+    SignatureValidator validator = new SignatureValidatorImpl(svConfig);
+    SignatureValidationResult result = validator.validateSignature(response.getBase64Signature(), request.getDataToBeSigned(), null);
+    
+    if (result.isValidationSuccessful()) {
+        // all is good, the signature is perfectly valid
+        // moreover, we can also get some extra data from the signature
+        System.out.println("Mobile ID serial number = " + result.getMobileIdSerialNumber());
+        System.out.println("Signed DTBS = " + result.getSignedDtbs());
+        
+    } else {
+        // something failed
+        System.out.println("Signature validation failure = " + result.getValidationFailureReason());
+        System.out.println("Signing certificate path validation = " + result.isSignerCertificatePathValid());
+        System.out.println("Signing certificate validation = " + result.isSignerCertificateValid());
+        System.out.println("Signature validation = " + result.isSignatureValid());
+        System.out.println("DTBS matching = " + result.isDtbsMatching());
+        if (result.getValidationException() != null) {
+            result.getValidationException().printStackTrace();
+        } 
+    }
+    
+}
+```

docs/version-history.md

@@ -1,5 +1,13 @@
 # Version history
 
+# v1.5.0
+Add support for signature validation, after a mobile signature is successfully created. Add a new component that can be configured separately 
+for validating the signing certificate, the certificate path, the actual signature and the DTBD/DTBS that was signed.
+
+# v1.4.0
+Add support for HTTP proxy configuration. With this version, the Mobile ID Java client can be configured to use an HTTP proxy, with or 
+without Basic authentication. This works both for command line and for programmatic mode. 
+
 # v1.3.0
 Add optional override of AP ID and AP Password for each request and for the tracking object of a signature operation. 
 This helps with sending requests on behalf of various APs, instead of relying only on the common AP ID + AP password 
@@ -17,4 +25,4 @@ The artifacts are now available via Maven Central Repository.
 ## v1.1.0
 First official release of the Mobile ID Java client.
 Contains the usage of the Geofencing additional service (instead of the deprecated Subscriber Info).
-Provides a new CLI parameter called "req-timeout" to allow for setting the signature request timeout.
+Provides a new CLI parameter called "req-timeout" to allow for setting the signature request timeout.