Resolve VCSWP-19101 (#35)

Add signing secret verification util classes

Author: amahadaya

.openapi-generator/FILES

@@ -269,5 +269,4 @@ requirements.txt
 setup.cfg
 setup.py
 test/__init__.py
-test/test_default_api.py
 tox.ini

CHANGELOG.md

@@ -9,6 +9,14 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 None
 
+<a name="4.2.0"></a>
+
+## [4.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="4.1.3"></a>
 
 ## [4.1.3] - 2023-03-13

README.md

@@ -4,7 +4,7 @@ FreeClimb is a cloud-based application programming interface (API) that puts the
 This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: 1.0.0
-- Package version: 4.1.3
+- Package version: 4.2.0
 - Build package: org.openapitools.codegen.languages.PythonClientCodegen
 For more information, please visit [https://www.freeclimb.com/support/](https://www.freeclimb.com/support/)
 
@@ -313,7 +313,31 @@ Class | Method | HTTP request | Description
 
 - **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 verify_request_signature method within the Request Verifier class
+
+  RequestVerifier.verify_request_signature(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 int
+
+  Example code down below
+
+  ```python
+  from freeclimb.utils.request_verifier import RequestVerifier
+
+  class RequestVerifierExample():
+        def verify_request_signature_example():
+            request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+            signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+            tolerance = 5 * 60
+            request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+  ```
 ## Author
 
 support@freeclimb.com

freeclimb/__init__.py

@@ -11,7 +11,7 @@
 """
 
 
-__version__ = "4.1.3"
+__version__ = "4.2.0"
 
 # import ApiClient
 from freeclimb.api_client import ApiClient

freeclimb/api_client.py

@@ -77,7 +77,7 @@ def __init__(self, configuration=None, header_name=None, header_value=None,
             self.default_headers[header_name] = header_value
         self.cookie = cookie
         # Set default User-Agent.
-        self.user_agent = 'OpenAPI-Generator/4.1.3/python'
+        self.user_agent = 'OpenAPI-Generator/4.2.0/python'
 
     def __enter__(self):
         return self

freeclimb/configuration.py

@@ -405,7 +405,7 @@ def to_debug_report(self):
                "OS: {env}\n"\
                "Python Version: {pyversion}\n"\
                "Version of the API: 1.0.0\n"\
-               "SDK Package Version: 4.1.3".\
+               "SDK Package Version: 4.2.0".\
                format(env=sys.platform, pyversion=sys.version)
 
     def get_host_settings(self):

freeclimb/utils/request_verifier.py

@@ -0,0 +1,52 @@
+import sys
+
+from freeclimb.utils.signature_information import SignatureInformation
+
+class RequestVerifier:
+    
+    DEFAULT_TOLERANCE = 5*60*1000
+
+    @staticmethod
+    def verify_request_signature(request_body:str, request_header:str, signing_secret:str, tolerance:int=DEFAULT_TOLERANCE):
+        verifier = RequestVerifier()
+        verifier.__check_request_body(request_body)
+        verifier.__check_request_header(request_header)
+        verifier.__check_signing_secret(signing_secret)
+        verifier.__check_tolerance(tolerance)
+        info = SignatureInformation(request_header)
+        verifier.__verify_tolerance(info, tolerance)
+        verifier.__verify_signature(info, request_body, signing_secret)
+    
+    def __check_request_body(self, request_body:str):
+        if request_body == "" or request_body == None:
+            raise Exception("Request Body cannot be empty or null")
+
+    def __check_request_header(self, request_header:str): 
+        if request_header == "" or request_header == None: 
+            raise Exception("Error with request header, Request header is empty")
+        
+        elif not("t" in request_header) :
+            raise Exception("Error with request header, timestamp is not present")
+        
+        elif not("v1" in request_header) :
+            raise Exception("Error with request header, signatures are not present")
+        
+
+    def __check_signing_secret(self, signing_secret:str):
+        if signing_secret == "" or signing_secret == None:
+            raise Exception("Signing secret cannot be empty or null")
+        
+    def __check_tolerance(self, tolerance:int):
+        if tolerance <= 0 or tolerance >= sys.maxsize:
+            raise Exception("Tolerance value must be a positive integer")
+        
+    def __verify_tolerance(self, info:SignatureInformation, tolerance:int):
+        currentTime = info.get_current_unix_time()
+        if not(info.is_request_time_valid(tolerance)):
+            raise Exception("Request time exceeded tolerance threshold. Request: " + str(info.request_timestamp)
+            + ", CurrentTime: " + str(currentTime) + ", tolerance: " + str(tolerance))
+
+    def __verify_signature(self, info:SignatureInformation, request_body:str, signing_secret:str):
+         if not(info.is_signature_safe(request_body, signing_secret)):
+            raise Exception("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")
+

freeclimb/utils/signature_information.py

@@ -0,0 +1,30 @@
+import time, hmac, hashlib
+
+class SignatureInformation:
+    request_timestamp:int = 0
+    signatures = []
+
+    def __init__(self, request_header:str):
+        signature_headers = request_header.split(",")
+        for signature in signature_headers:
+            header, value = signature.split("=")
+            if header == "t":
+                self.request_timestamp = int(value)
+            elif header == "v1":
+                self.signatures.append(value) 
+    
+    def is_request_time_valid(self, tolerance:int) -> bool:
+        current_time = self.get_current_unix_time()
+        time_calculation:int = self.request_timestamp + tolerance
+        return (time_calculation) < current_time
+
+    def is_signature_safe(self, requestBody:str, signingSecret:str) -> bool:
+        hashValue = self.__compute_hash(requestBody, signingSecret)
+        return hashValue in self.signatures
+
+    def __compute_hash(self, requestBody:str, signingSecret:str) -> str:
+        data = str(self.request_timestamp) + "." + requestBody
+        return hmac.new(bytes(signingSecret, 'utf-8'), data.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
+
+    def get_current_unix_time(self) -> int:
+        return int(time.time())

setup.py

@@ -12,7 +12,7 @@
 from setuptools import setup, find_packages  # noqa: H301
 
 NAME = "FreeClimb"
-VERSION = "4.1.3"
+VERSION = "4.2.0"
 # To install the library, run the following
 #
 # python setup.py install

test/test_request_verifier.py

@@ -0,0 +1,123 @@
+import sys
+import time
+import unittest
+
+from freeclimb.utils.request_verifier import RequestVerifier
+
+class TestRequestVerifier(unittest.TestCase):
+    """RequestVerifier unit test stubs"""
+
+    def setUp(self):
+        self.request_verifier = RequestVerifier()
+    
+    def tearDown(self):
+        pass
+
+    def test_check_request_body(self):
+        request_body = ""
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 5 * 60
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Request Body cannot be empty or null")
+    
+    def test_check_request_header_no_signatures(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 5 * 60
+        request_header = "t=1679944186,"
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Error with request header, signatures are not present")
+    
+    def test_check_request_header_no_timestamp(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 5 * 60
+        request_header = "v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Error with request header, timestamp is not present")
+    
+    def test_check_request_header_empty_request_header(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 5 * 60
+        request_header = ""        
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Error with request header, Request header is empty")
+
+    def test_check_signing_secret(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = ""
+        tolerance = 5 * 60
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Signing secret cannot be empty or null")
+    
+    def test_check_tolerance_max_int(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = sys.maxsize
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Tolerance value must be a positive integer")
+    
+    def test_check_tolerance_zero_value(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 0
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        with self.assertRaises(Exception) as exc:
+            self.request_verifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Tolerance value must be a positive integer")
+    
+    def test_check_tolerance_negative_value(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = -5
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Tolerance value must be a positive integer")
+    
+    def test_verify_tolerance(self):
+        current_time = int(time.time())
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 5 * 60
+        request_header = "t=1900871395,v1=1d798c86e977ff734dec3a8b8d67fe8621dcc1df46ef4212e0bfe2e122b01bfd,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "Request time exceeded tolerance threshold. Request: 1900871395" 
+                + ", CurrentTime: " + str(current_time) + ", tolerance: " + str(tolerance))
+    
+    def test_verify_signature(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7794"
+        tolerance = 5 * 60
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        with self.assertRaises(Exception) as exc:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        self.assertEqual(str(exc.exception), "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")
+    
+    def test_verify_request_signature(self):
+        request_body = "{\"accountId\":\"AC1334ffb694cd8d969f51cddf5f7c9b478546d50c\",\"callId\":\"CAccb0b00506553cda09b51c5477f672a49e0b2213\",\"callStatus\":\"ringing\",\"conferenceId\":null,\"direction\":\"inbound\",\"from\":\"+13121000109\",\"parentCallId\":null,\"queueId\":null,\"requestType\":\"inboundCall\",\"to\":\"+13121000096\"}"
+        signing_secret = "sigsec_ead6d3b6904196c60835d039e91b3341c77a7793"
+        tolerance = 5 * 60
+        request_header = "t=1679944186,v1=c3957749baf61df4b1506802579cc69a74c77a1ae21447b930e5a704f9ec4120,v1=1ba18712726898fbbe48cd862dd096a709f7ad761a5bab14bda9ac24d963a6a8"        
+        raised = False
+        try:
+            RequestVerifier.verify_request_signature(request_body, request_header, signing_secret, tolerance)
+        except:
+            raised = True
+        self.assertFalse(raised, 'Exception has been raised')
+    
+    
+
+if __name__ == '__main__':
+    unittest.main()