add possibility to request mobile device IP address to be returned (#78)

* add possibility to request mobile device IP address to be returned
* add implements Serializable

---------

Co-authored-by: juhanaasaru <Juhan.Aasaru@nortal.com>

Author: aasaru

CHANGELOG.md

@@ -2,10 +2,20 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [2.3] - UPCOMING
+- To request the IP address of the device running Smart-ID app, the following methods were added:
+  - AuthenticationRequestBuilder.withShareMdClientIpAddress(boolean)
+  - CertificateRequestBuilder.withShareMdClientIpAddress(boolean)
+  - SignatureRequestBuilder.withShareMdClientIpAddress(boolean)
+- The IP address returned can be read out using:
+  - SmartIdAuthenticationResponse.getDeviceIpAddress()
+  - SmartIdCertificate.getDeviceIpAddress()
+  - SmartIdSignature.getDeviceIpAddress()
+
 ## [2.2.2] - 2022-11-14
 
 ### Changed
--  upgrade jackson, jersey and dependency-check-maven plugin
+- upgrade jackson, jersey and dependency-check-maven plugin
 ### Documented
 - How to extract date-of-birth from a certificate added as a separate paragraph to readme.
 - Added two tests into SmartIdIntegrationTest that demonstrate fetching and parsing a certificate with date-of-birth
@@ -84,7 +94,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - all endpoints using `NationalIdentityNumber` are now removed as this functionality has been removed from Smart-ID API 2.0
 - errors that the caller cannot recover from are now removed from method throws list.
 - Hard-coded certificates were removed together with methods:
-  -  SmartIdClient.useDemoEnvSSLCertificates()
+  - SmartIdClient.useDemoEnvSSLCertificates()
   - SmartIdClient.useLiveEnvSSLCertificates()
 
 ## [1.6] - 2020-05-25
@@ -101,6 +111,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - AuthenticationRequestBuilder method withRequestProperties access modifier changed to public
 
 ### Added
+
 - Maven wrapper to project
 
 ## [1.5] - 2019-11-12
@@ -127,7 +138,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [1.3] - 2019-09-13
 ### Added
 - Capabilities parameter ([#25](https://github.com/SK-EID/smart-id-java-client/pull/25))
-- [Request properties](https://github.com/SK-EID/smart-id-documentation#416-request-properties) (vcChoice) for authentication and signing ([#21](https://github.com/SK-EID/smart-id-java-client/pull/21)) 
+- [Request properties](https://github.com/SK-EID/smart-id-documentation#416-request-properties) (vcChoice) for authentication and signing ([#21](https://github.com/SK-EID/smart-id-java-client/pull/21))
 
 ## [1.2] - 2019-08-21
 ### Added

README.md

@@ -102,12 +102,21 @@ logging.level.ee.sk.smartid.rest.LoggingFilter: trace
 
 ### Get the IP address of user's device
 
-Smart-ID API returns the IP address of the user's device for subscribed Relying Parties.
-This info can be retrieved using one of:
+Smart-ID API returns the IP address of the user's device for subscribed Relying Parties who
+ask it to be returned.
 
-* [SmartIdAuthenticationResponse.getDeviceIpAddress()](src/main/java/ee/sk/smartid/SmartIdAuthenticationResponse.java#:~:text=getDeviceIpAddress())
-* [SmartIdSignature.getDeviceIpAddress()](src/main/java/ee/sk/smartid/SmartIdSignature.java#:~:text=getDeviceIpAddress())
-* [SessionStatus.getDeviceIpAddress()](src/main/java/ee/sk/smartid/rest/dao/SessionStatus.java#:~:text=getDeviceIpAddress())
+Requesting for the IP address to be returned: 
+
+* [AuthenticationRequestBuilder.withShareMdClientIpAddress()](src/main/java/ee/sk/smartid/AuthenticationRequestBuilder.java) -> withShareMdClientIpAddress()
+* [SignatureRequestBuilder.withShareMdClientIpAddress()](src/main/java/ee/sk/smartid/SignatureRequestBuilder.java) -> withShareMdClientIpAddress()
+* [CertificateRequestBuilder.withShareMdClientIpAddress()](src/main/java/ee/sk/smartid/CertificateRequestBuilder.java) -> withShareMdClientIpAddress()
+
+
+The returned info can be retrieved using one of:
+
+* [SmartIdAuthenticationResponse.getDeviceIpAddress()](src/main/java/ee/sk/smartid/SmartIdAuthenticationResponse.java) -> getDeviceIpAddress()
+* [SmartIdSignature.getDeviceIpAddress()](src/main/java/ee/sk/smartid/SmartIdSignature.java) -> getDeviceIpAddress()
+* [SessionStatus.getDeviceIpAddress()](src/main/java/ee/sk/smartid/rest/dao/SessionStatus.java) -> getDeviceIpAddress()
 
 
 ## Example of configuring the client
@@ -188,10 +197,16 @@ SmartIdAuthenticationResponse authenticationResponse = client
     .withAllowedInteractionsOrder(
             Collections.singletonList(Interaction.displayTextAndPIN("Log in to self-service?")
     ))
+    // we want to get the IP address of the device running Smart-ID app
+    // for the IP to be returned the service provider (SK) must switch on this option
+    .withShareMdClientIpAddress(true)
     .authenticate();
 
 // You need this later to pull user's signing certificate   
 String documentNumberForFurtherReference = authenticationResponse.getDocumentNumber();
+
+// We get IP of Smart-ID app since we made the request .withShareMdClientIpAddress(true)
+String deviceIpAddress = authenticationResponse.getDeviceIpAddress();
 ```
 
 Note that verificationCode should be displayed by the web service, so the person signing through the Smart-ID mobile app can verify if the verification code displayed on the phone matches with the one shown on the web page.

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

@@ -227,7 +227,7 @@ public AuthenticationRequestBuilder withCapabilities(Capability... capabilities)
    * Specifies capabilities of the user
    * <p>
    *
-   * By default there are no specified capabilities.
+   * By default, there are no specified capabilities.
    * The capabilities need to be specified in case of
    * a restricted Smart ID user
    * {@link #withCapabilities(Capability...)}
@@ -250,6 +250,17 @@ public AuthenticationRequestBuilder withAllowedInteractionsOrder(List<Interactio
     return this;
   }
 
+  /**
+   * Ask to return the IP address of the mobile device where Smart-ID app was running.
+   * @see <a href="https://github.com/SK-EID/smart-id-documentation#238-mobile-device-ip-sharing">Mobile Device IP sharing</a>
+   *
+   * @return this builder
+   */
+  public AuthenticationRequestBuilder withShareMdClientIpAddress(boolean shareMdClientIpAddress) {
+    this.shareMdClientIpAddress = shareMdClientIpAddress;
+    return this;
+  }
+
   /**
    * Send the authentication request and get the response
    * <p>
@@ -360,6 +371,13 @@ private AuthenticationSessionRequest createAuthenticationSessionRequest() {
     request.setNonce(getNonce());
     request.setCapabilities(getCapabilities());
     request.setAllowedInteractionsOrder(getAllowedInteractionsOrder());
+
+    RequestProperties requestProperties = new RequestProperties();
+    requestProperties.setShareMdClientIpAddress(this.shareMdClientIpAddress);
+    if (requestProperties.hasProperties()) {
+      request.setRequestProperties(requestProperties);
+    }
+
     return request;
   }
 

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

@@ -221,6 +221,17 @@ public CertificateRequestBuilder withSemanticsIdentifier(SemanticsIdentifier sem
     return this;
   }
 
+  /**
+   * Ask to return the IP address of the mobile device where Smart-ID app was running.
+   * @see <a href="https://github.com/SK-EID/smart-id-documentation#238-mobile-device-ip-sharing">Mobile Device IP sharing</a>
+   *
+   * @return this builder
+   */
+  public CertificateRequestBuilder withShareMdClientIpAddress(boolean shareMdClientIpAddress) {
+    this.shareMdClientIpAddress = shareMdClientIpAddress;
+    return this;
+  }
+
   /**
    * Send the certificate choice request and get the response
    *x
@@ -278,6 +289,8 @@ public SmartIdCertificate createSmartIdCertificate(SessionStatus sessionStatus)
     smartIdCertificate.setCertificate(CertificateParser.parseX509Certificate(certificate.getValue()));
     smartIdCertificate.setCertificateLevel(certificate.getCertificateLevel());
     smartIdCertificate.setDocumentNumber(getDocumentNumber(sessionStatus));
+    smartIdCertificate.setDeviceIpAddress(sessionStatus.getDeviceIpAddress());
+
     return smartIdCertificate;
   }
 
@@ -300,6 +313,13 @@ private CertificateRequest createCertificateRequest() {
     request.setCertificateLevel(getCertificateLevel());
     request.setNonce(getNonce());
     request.setCapabilities(getCapabilities());
+
+    RequestProperties requestProperties = new RequestProperties();
+    requestProperties.setShareMdClientIpAddress(this.shareMdClientIpAddress);
+    if (requestProperties.hasProperties()) {
+      request.setRequestProperties(requestProperties);
+    }
+
     return request;
   }
 

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

@@ -253,7 +253,18 @@ public SignatureRequestBuilder withCapabilities(String... capabilities) {
     this.capabilities = new HashSet<>(Arrays.asList(capabilities));
     return this;
   }
- 
+
+  /**
+   * Ask to return the IP address of the mobile device where Smart-ID app was running.
+   * @see <a href="https://github.com/SK-EID/smart-id-documentation#238-mobile-device-ip-sharing">Mobile Device IP sharing</a>
+   *
+   * @return this builder
+   */
+  public SignatureRequestBuilder withShareMdClientIpAddress(boolean shareMdClientIpAddress) {
+    this.shareMdClientIpAddress = shareMdClientIpAddress;
+    return this;
+  }
+
   /**
    * @param allowedInteractionsOrder Preferred order of what dialog to present to user. What actually gets displayed depends on user's device and its software version.
    *                                 First option from this list that the device is capable of handling is displayed to the user.
@@ -360,6 +371,13 @@ private SignatureSessionRequest createSignatureSessionRequest() {
     request.setNonce(getNonce());
     request.setCapabilities(getCapabilities());
     request.setAllowedInteractionsOrder(getAllowedInteractionsOrder());
+
+    RequestProperties requestProperties = new RequestProperties();
+    requestProperties.setShareMdClientIpAddress(this.shareMdClientIpAddress);
+    if (requestProperties.hasProperties()) {
+      request.setRequestProperties(requestProperties);
+    }
+
     return request;
   }
 }

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

@@ -34,6 +34,7 @@ public class SmartIdCertificate implements Serializable {
   private X509Certificate certificate;
   private String documentNumber;
   private String certificateLevel;
+  private String deviceIpAddress;
 
   public void setCertificate(X509Certificate certificate) {
     this.certificate = certificate;
@@ -58,4 +59,13 @@ public String getCertificateLevel() {
   public void setCertificateLevel(String certificateLevel) {
     this.certificateLevel = certificateLevel;
   }
+
+  public void setDeviceIpAddress(String deviceIpAddress) {
+    this.deviceIpAddress = deviceIpAddress;
+  }
+
+  public String getDeviceIpAddress() {
+    return deviceIpAddress;
+  }
+
 }

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

@@ -60,6 +60,7 @@ public abstract class SmartIdRequestBuilder {
   protected String nonce;
   protected Set<String> capabilities;
   protected List<Interaction> allowedInteractionsOrder;
+  protected Boolean shareMdClientIpAddress;
 
   protected SmartIdRequestBuilder(SmartIdConnector connector, SessionStatusPoller sessionStatusPoller) {
     this.connector = connector;

src/main/java/ee/sk/smartid/rest/dao/AuthenticationSessionRequest.java

@@ -54,6 +54,9 @@ public class AuthenticationSessionRequest implements Serializable {
   @JsonInclude(JsonInclude.Include.NON_EMPTY)
   private List<Interaction> allowedInteractionsOrder;
 
+  @JsonInclude(JsonInclude.Include.NON_NULL)
+  private RequestProperties requestProperties;
+
   public String getCertificateLevel() {
     return certificateLevel;
   }
@@ -121,4 +124,13 @@ public List<Interaction> getAllowedInteractionsOrder() {
   public void setAllowedInteractionsOrder(List<Interaction> allowedInteractionsOrder) {
     this.allowedInteractionsOrder = allowedInteractionsOrder;
   }
+
+  public RequestProperties getRequestProperties() {
+    return requestProperties;
+  }
+
+  public void setRequestProperties(RequestProperties requestProperties) {
+    this.requestProperties = requestProperties;
+  }
+
 }

src/main/java/ee/sk/smartid/rest/dao/CertificateRequest.java

@@ -34,14 +34,21 @@
 public class CertificateRequest implements Serializable {
 
   private String relyingPartyUUID;
+
   private String relyingPartyName;
+
   @JsonInclude(JsonInclude.Include.NON_EMPTY)
   private String certificateLevel;
+
   @JsonInclude(JsonInclude.Include.NON_EMPTY)
   private String nonce;
+
   @JsonInclude(JsonInclude.Include.NON_NULL)
   private Set capabilities;
 
+  @JsonInclude(JsonInclude.Include.NON_NULL)
+  private RequestProperties requestProperties;
+
   public String getCertificateLevel() {
     return certificateLevel;
   }
@@ -81,4 +88,13 @@ public Set getCapabilities() {
   public void setCapabilities(Set capabilities) {
     this.capabilities = capabilities;
   }
+
+  public RequestProperties getRequestProperties() {
+    return requestProperties;
+  }
+
+  public void setRequestProperties(RequestProperties requestProperties) {
+    this.requestProperties = requestProperties;
+  }
+
 }

src/main/java/ee/sk/smartid/rest/dao/RequestProperties.java

@@ -0,0 +1,26 @@
+package ee.sk.smartid.rest.dao;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonInclude;
+
+import java.io.Serializable;
+
+public class RequestProperties implements Serializable {
+
+    @JsonInclude(JsonInclude.Include.NON_NULL)
+    Boolean shareMdClientIpAddress;
+
+    public Boolean getShareMdClientIpAddress() {
+        return shareMdClientIpAddress;
+    }
+
+    public void setShareMdClientIpAddress(Boolean shareMdClientIpAddress) {
+        this.shareMdClientIpAddress = shareMdClientIpAddress;
+    }
+
+    @JsonIgnore
+    public boolean hasProperties() {
+        return shareMdClientIpAddress != null;
+    }
+
+}