Resolve VCSWP-19101 (#34)

Add signing secret verification util classes

Author: amahadaya

.openapi-generator/FILES

@@ -286,4 +286,3 @@ src/main/java/com/github/freeclimbapi/auth/ApiKeyAuth.java
 src/main/java/com/github/freeclimbapi/auth/Authentication.java
 src/main/java/com/github/freeclimbapi/auth/HttpBasicAuth.java
 src/main/java/com/github/freeclimbapi/auth/HttpBearerAuth.java
-src/test/java/com/github/freeclimbapi/DefaultApiTest.java

CHANGELOG.md

@@ -9,6 +9,14 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 None
 
+<a name="5.2.0"></a>
+
+## [5.2.0] 2023-04-03
+
+### Added
+
+- Introduce signing secret verification class (RequestVerifier) - https://docs.freeclimb.com/docs/validating-requests-from-freeclimb#how-to-verify-requests-manually
+
 <a name="5.1.3"></a>
 
 ## [5.1.3] 2023-03-13

README.md

@@ -40,7 +40,7 @@ Add this dependency to your project's POM:
 <dependency>
   <groupId>com.github.freeclimbapi</groupId>
   <artifactId>freeclimb-java-client</artifactId>
-  <version>5.1.3</version>
+  <version>5.2.0</version>
   <scope>compile</scope>
 </dependency>
 ```
@@ -56,7 +56,7 @@ Add this dependency to your project's build file:
   }
 
   dependencies {
-     implementation "com.github.freeclimbapi:freeclimb-java-client:5.1.3"
+     implementation "com.github.freeclimbapi:freeclimb-java-client:5.2.0"
   }
 ```
 
@@ -70,7 +70,7 @@ mvn clean package
 
 Then manually install the following JARs:
 
-* `target/freeclimb-java-client-5.1.3.jar`
+* `target/freeclimb-java-client-5.2.0.jar`
 * `target/lib/*.jar`
 
 ## Getting Started
@@ -328,6 +328,37 @@ Authentication schemes defined for the API:
 
 - **Type**: HTTP basic authentication
 
+<a name="documentation-for-verify-request-signature"></a>
+
+## Documentation for verifying request signature
+
+- To verify the request signature, we will need to use the verifyRequestSignature method within the Request Verifier class
+
+  RequestVerifier.verifyRequestSignature(requestBody, requestHeader, signingSecret, tolerance)
+
+  This is a method that you can call directly from the request verifier class, it will throw exceptions depending on whether all parts of the request signature is valid otherwise it will throw a specific error message depending on which request signature part is causing issues
+
+  This method requires a requestBody of type String, a requestHeader of type String, a signingSecret of type String, and a tolerance value of type Integer
+
+  Example code down below
+
+  ```java
+    package com.github.freeclimbapi;
+
+    import com.github.freeclimbapi.utils.*;
+    import java.security.NoSuchAlgorithmException;
+    import java.security.InvalidKeyException;
+
+    public class Example {
+        public void verifyRequestSignatureExample() throws NoSuchAlgorithmException, InvalidKeyException {
+            String requestBody = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}";
+            String signingSecret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793";
+            String requestHeader = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8";
+            Integer tolerance = 5 * 60;
+            RequestVerifier.verifyRequestSignature(requestBody, requestHeader, signingSecret, tolerance);
+        }
+     }
+  ```
 
 ## Recommendation
 
@@ -336,4 +367,3 @@ It's recommended to create an instance of `ApiClient` per thread in a multithrea
 ## Author
 
 [email protected]
-

build.gradle

@@ -4,7 +4,7 @@ apply plugin: 'java'
 apply plugin: 'com.diffplug.spotless'
 
 group = 'com.github.freeclimbapi'
-version = '5.1.3'
+version = '5.2.0'
 
 buildscript {
     repositories {
@@ -114,6 +114,7 @@ dependencies {
     implementation 'io.gsonfire:gson-fire:1.8.4'
     implementation 'org.openapitools:jackson-databind-nullable:0.2.1'
     implementation group: 'org.apache.commons', name: 'commons-lang3', version: '3.10'
+    implementation group: 'commons-codec', name: 'commons-codec', version: '1.7'
     implementation 'org.threeten:threetenbp:1.4.3'
     implementation "jakarta.annotation:jakarta.annotation-api:$jakarta_annotation_version"
     testImplementation 'junit:junit:4.13.1'

build.sbt

@@ -2,7 +2,7 @@ lazy val root = (project in file(".")).
   settings(
     organization := "com.github.freeclimbapi",
     name := "freeclimb-java-client",
-    version := "5.1.3",
+    version := "5.2.0",
     scalaVersion := "2.11.4",
     scalacOptions ++= Seq("-feature"),
     javacOptions in compile ++= Seq("-Xlint:deprecation"),

pom.xml

@@ -5,7 +5,7 @@
     <artifactId>freeclimb-java-client</artifactId>
     <packaging>jar</packaging>
     <name>freeclimb-java-client</name>
-    <version>5.1.3</version>
+    <version>5.2.0</version>
     <url>https://github.com/freeclimbapi/java-sdk</url>
     <description>FreeClimb Java Client</description>
     <scm>

src/main/java/com/github/freeclimbapi/ApiClient.java

@@ -131,7 +131,7 @@ private void init() {
         json = new JSON();
 
         // Set default User-Agent.
-        setUserAgent("OpenAPI-Generator/5.1.3/java");
+        setUserAgent("OpenAPI-Generator/5.2.0/java");
 
         authentications = new HashMap<String, Authentication>();
     }

src/main/java/com/github/freeclimbapi/utils/RequestVerifier.java

@@ -0,0 +1,80 @@
+package com.github.freeclimbapi.utils;
+
+import java.io.UnsupportedEncodingException;
+import java.security.NoSuchAlgorithmException;
+import java.security.InvalidKeyException;
+import java.net.URLDecoder;
+import java.util.Arrays;
+import java.util.List;
+import java.util.ArrayList;
+import java.util.Date;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import org.apache.commons.codec.binary.Hex;
+
+public class RequestVerifier {
+    public static final Integer DEFAULT_TOLERANCE = 5 * 60 * 1000;
+
+    public static void verifyRequestSignature(String requestBody, String requestHeader, String signingSecret,
+            Integer tolerance) throws NoSuchAlgorithmException, InvalidKeyException {
+        RequestVerifier verifier = new RequestVerifier();
+        verifier.checkRequestBody(requestBody);
+        verifier.checkRequestHeader(requestHeader);
+        verifier.checkSigningSecret(signingSecret);
+        verifier.checkTolerance(tolerance);
+        SignatureInformation info = new SignatureInformation(requestHeader);
+        verifier.verifyTolerance(info, tolerance);
+        verifier.verifySignature(info, requestBody, signingSecret);
+    }
+
+    private void verifyRequestSignature(String requestBody, String requestHeader, String signingSecret)
+            throws NoSuchAlgorithmException, InvalidKeyException {
+        verifyRequestSignature(requestBody, requestHeader, signingSecret, DEFAULT_TOLERANCE);
+    }
+
+    private void checkRequestBody(String requestBody) {
+        if (requestBody == "" || requestBody == null) {
+            throw new java.lang.RuntimeException("Request Body cannot be empty or null");
+        }
+    }
+
+    private void checkRequestHeader(String requestHeader) {
+        if (requestHeader == "" || requestHeader == null) {
+            throw new java.lang.RuntimeException("Error with request header, Request header is empty");
+        } else if (!requestHeader.contains("t=")) {
+            throw new java.lang.RuntimeException("Error with request header, timestamp is not present");
+        } else if (!requestHeader.contains("v1=")) {
+            throw new java.lang.RuntimeException("Error with request header, signatures are not present");
+        }
+    }
+
+    private void checkSigningSecret(String signingSecret) {
+        if (signingSecret.equals("") || signingSecret.equals(null)) {
+            throw new java.lang.RuntimeException("Signing secret cannot be empty or null");
+        }
+    }
+
+    private void checkTolerance(Integer tolerance) {
+        if ((tolerance <= 0) || tolerance >= Integer.MAX_VALUE) {
+            throw new java.lang.RuntimeException("Tolerance value must be a positive integer");
+        }
+    }
+
+    private void verifyTolerance(SignatureInformation info, Integer tolerance) {
+        int currentTime = info.getCurrentUnixTime();
+        if (!info.isRequestTimeValid(tolerance)) {
+            throw new java.lang.RuntimeException(
+                    "Request time exceeded tolerance threshold. Request: " + info.requestTimestamp
+                            + ", CurrentTime: " + Integer.toString(currentTime) + ", tolerance: " + tolerance);
+        }
+    }
+
+    private void verifySignature(SignatureInformation info, String requestBody, String signingSecret)
+            throws NoSuchAlgorithmException, InvalidKeyException {
+        if (!info.isSignatureSafe(requestBody, signingSecret)) {
+            throw new java.lang.RuntimeException(
+                    "Unverified signature request, If this request was unexpected, it may be from a bad actor. Please proceed with caution. If the request was exepected, please check any typos or issues with the signingSecret");
+        }
+    }
+}

src/main/java/com/github/freeclimbapi/utils/SignatureInformation.java

@@ -0,0 +1,59 @@
+package com.github.freeclimbapi.utils;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLDecoder;
+import java.security.NoSuchAlgorithmException;
+import java.security.InvalidKeyException;
+import java.util.Arrays;
+import java.util.List;
+import java.util.ArrayList;
+import java.util.Date;
+
+import javax.crypto.Mac;
+import javax.crypto.spec.SecretKeySpec;
+import org.apache.commons.codec.binary.Hex;
+
+public class SignatureInformation {
+    public Integer requestTimestamp;
+    public List<String> signatures;
+
+    public SignatureInformation(String requestHeader) {
+        signatures = new ArrayList<String>();
+        String[] signatureHeaders = requestHeader.split(",");
+        for (String signatureHeader : signatureHeaders) {
+            String[] split = signatureHeader.split("=");
+            String header = split[0];
+            String value = split[1];
+            if (header.equals("t")) {
+                requestTimestamp = Integer.valueOf(value);
+            } else if (header.equals("v1")) {
+                signatures.add(value);
+            }
+        }
+    }
+
+    public boolean isRequestTimeValid(Integer tolerance) {
+        Integer currentUnixTimestamp = getCurrentUnixTime();
+        return (requestTimestamp + tolerance) < currentUnixTimestamp;
+    }
+
+    public boolean isSignatureSafe(String requestBody, String signingSecret)
+            throws NoSuchAlgorithmException, InvalidKeyException {
+        String hashValue = computeHash(requestBody, signingSecret);
+        return signatures.contains(hashValue);
+    }
+
+    private String computeHash(String requestBody, String signingSecret)
+            throws NoSuchAlgorithmException, InvalidKeyException {
+        String hashHexadecimalValue = "";
+        String hashSeedString = requestTimestamp + "." + requestBody;
+        Mac mac = Mac.getInstance("HmacSHA256");
+        mac.init(new SecretKeySpec(signingSecret.getBytes(), "HmacSHA256"));
+        return Hex.encodeHexString(mac.doFinal(hashSeedString.getBytes()));
+    }
+
+    public Integer getCurrentUnixTime() {
+        Long timeCalculation = (System.currentTimeMillis() / 1000L);
+        return Integer.valueOf(timeCalculation.intValue());
+    }
+}