3 files changed, 271 insertions, 24 deletions

diff --git a/otp2289/__init__.py b/otp2289/__init__.py
index 44c39bb..2fba4ea 100644
--- a/otp2289/__init__.py
+++ b/otp2289/__init__.py
@@ -29,6 +29,7 @@ from .generator import (OTP_ALGO_MD5,
                         OTPChallengeException,
                         OTPGenerator,
                         OTPGeneratorException)
+from .server import OTPInvalidResponse, OTPState, OTPStateException
 
 
 __author__ = 'Simeon Simeonov'
@@ -50,4 +51,7 @@ __all__ = ['OTP_ALGO_MD5',
            'OTP_ALGO_SHA1',
            'OTPChallengeException',
            'OTPGenerator',
-           'OTPGeneratorException']
+           'OTPGeneratorException',
+           'OTPInvalidResponse',
+           'OTPState',
+           'OTPStateException']
diff --git a/otp2289/generator.py b/otp2289/generator.py
index 7001014..ac3bb3c 100644
--- a/otp2289/generator.py
+++ b/otp2289/generator.py
@@ -320,19 +320,19 @@ class OTPGenerator:
         :param hash_algo: The hash algo, defaults to OTP_ALGO_MD5
         :type hash_algo: int or str
 
-        :raises OTPGeneratorException: In case input does not validate
+        :raises OTPGeneratorException: In case the input does not validate
         """
         # enforce the rfc2289 constraints
+        self._seed = seed
+        if self._seed:  # the seed was set here. Validate it
+            self._seed = self.validate_seed(self._seed)
+        self._hash_algo = self.validate_hash_algo(hash_algo)
         if not isinstance(password, bytes):
             raise OTPGeneratorException('Password must be a byte-string')
         if len(password) < 10:
             raise OTPGeneratorException(
                 'Password must be longer than 10 bytes')
         self._password = password
-        self._seed = seed
-        if self._seed:  # the seed was set here. Validate it
-            self._seed = self.validate_seed(self._seed)
-        self._hash_algo = self.validate_hash_algo(hash_algo)
 
     @staticmethod
     def bit_pair_sum(bit_stream):
@@ -355,6 +355,31 @@ class OTPGenerator:
         return value
 
     @staticmethod
+    def bytes_to_tokens(hash_bytes):
+        """
+        Returns a 6 words token from bytes as specified by RFC-2289.
+
+        :param hash_bytes: The input bytes
+        :type hash_bytes: bytes
+
+        :return: 6 words tokens
+        :rtype: str
+        """
+        bit_stream = ''.join(
+            ['{0:0>8b}'.format(byte) for byte in hash_bytes])
+        bit_pair_sum = OTPGenerator.bit_pair_sum(bit_stream)
+        tokens = []
+        tokens.append(RFC1760_TOKENS[int(bit_stream[:11], 2)])
+        tokens.append(RFC1760_TOKENS[int(bit_stream[11:22], 2)])
+        tokens.append(RFC1760_TOKENS[int(bit_stream[22:33], 2)])
+        tokens.append(RFC1760_TOKENS[int(bit_stream[33:44], 2)])
+        tokens.append(RFC1760_TOKENS[int(bit_stream[44:55], 2)])
+        tokens.append(
+            RFC1760_TOKENS[int(
+                bit_stream[55:64] + '{0:0>8b}'.format(bit_pair_sum)[-2:], 2)])
+        return ' '.join(tokens)
+
+    @staticmethod
     def get_tokens_from_challenge(challenge):
         """
         Returns tokens (seed, hash_algo and step) from a challenge string.
@@ -453,6 +478,50 @@ class OTPGenerator:
         )
 
     @staticmethod
+    def tokens_to_bytes(tokens_str):
+        """
+        Returns bytes from a 6 words token as specified by RFC-2289.
+
+        :param tokens_str: String representing 6 words tokens
+        :type tokens_str: str
+
+        :raises OTPGeneratorException: When the tokens_str is invalid
+
+        :return: 6 words tokens
+        :rtype: bytes
+        """
+        if not isinstance(tokens_str, str):
+            raise OTPGeneratorException('tokens must be a str')
+        tokens = tokens_str.split()
+        if len(tokens) != 6:
+            raise OTPGeneratorException(
+                'Tokens-string does not contain 6 tokens')
+        token_ints = []
+        try:
+            token_ints = [RFC1760_TOKENS.index(token.upper()) for token in
+                          tokens]
+        except ValueError:
+            raise OTPGeneratorException(
+                'One or more words not present in RFC1760')
+        # now we build a string of bits
+        bit_stream = format(token_ints[0], '011b')
+        bit_stream += format(token_ints[1], '011b')
+        bit_stream += format(token_ints[2], '011b')
+        bit_stream += format(token_ints[3], '011b')
+        bit_stream += format(token_ints[4], '011b')
+        bit_stream += format(token_ints[5], '011b')
+        # we have 66 bits: 64 digest + 2 bit pair sum (control number)
+        # RFC-2289: All OTP generators MUST calculate this checksum and all
+        # OTP servers MUST verify this checksum explicitly as part of the
+        # operation of decoding this representation of the one-time password.
+        if (
+                '{0:0>8b}'.format(OTPGenerator.bit_pair_sum(
+                    bit_stream[:64]))[-2:] != bit_stream[-2:]
+        ):
+            raise OTPGeneratorException('Invalid bit checksum')
+        return int(bit_stream[:64], 2).to_bytes(8, 'big')
+
+    @staticmethod
     def validate_hash_algo(hash_algo):
         """
         Validates the provided hash-algorithm.
@@ -503,6 +572,25 @@ class OTPGenerator:
                     'The seed MUST consist of purely alphanumeric characters')
         return seed
 
+    @staticmethod
+    def validate_step(step):
+        """
+        Validates the provided step as defined by RFC-2289.
+
+        :param seed: The step received from the challenge
+        :type seed: int
+
+        :raises OTPGeneratorException: In case step does not validate
+
+        :return: The validated (and very same) step
+        :rtype: int
+        """
+        if not isinstance(step, int):
+            raise OTPGeneratorException('Step value MUST be an int')
+        if step < 0:
+            raise OTPGeneratorException('Step value MUST be >= 0')
+        return step
+
     def generate_otp_hexdigest(self, step):
         """
         Generates the OTP hexdigest for the given step.
@@ -549,20 +637,7 @@ class OTPGenerator:
         :return: Six words (separated by single space) token for the given step
         :rtype: str
         """
-        digest = self._generate_otp_bytes(step)
-        bit_stream = ''.join(
-            ['{0:0>8b}'.format(byte) for byte in digest])
-        bit_pair_sum = self.bit_pair_sum(bit_stream)
-        tokens = list()
-        tokens.append(RFC1760_TOKENS[int(bit_stream[:11], 2)])
-        tokens.append(RFC1760_TOKENS[int(bit_stream[11:22], 2)])
-        tokens.append(RFC1760_TOKENS[int(bit_stream[22:33], 2)])
-        tokens.append(RFC1760_TOKENS[int(bit_stream[33:44], 2)])
-        tokens.append(RFC1760_TOKENS[int(bit_stream[44:55], 2)])
-        tokens.append(
-            RFC1760_TOKENS[int(
-                bit_stream[55:64] + '{0:0>8b}'.format(bit_pair_sum)[-2:], 2)])
-        return ' '.join(tokens)
+        return self.bytes_to_tokens(self._generate_otp_bytes(step))
 
     def generate_otp_words_from_challenge(self, challenge):
         """
@@ -641,10 +716,7 @@ class OTPGenerator:
         :return: The digest bytes for the given step
         :rtype: bytes
         """
-        if not isinstance(step, int):
-            raise OTPGeneratorException('Step value MUST be an int')
-        if step < 0:
-            raise OTPGeneratorException('Step value MUST be >= 0')
+        step = self.validate_step(step)
         digest = b''
         for _ in range(step + 1):
             hash_obj = hashlib.new(self._hash_algo)
diff --git a/otp2289/server.py b/otp2289/server.py
index 096ebd7..4151026 100644
--- a/otp2289/server.py
+++ b/otp2289/server.py
@@ -24,3 +24,174 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 """A pure Python implementation of the RFC-2289 OTP server"""
+import binascii
+import hashlib
+
+from .generator import (OTP_ALGO_MD5,
+                        OTPGenerator,
+                        OTPGeneratorException)
+
+
+class OTPStateException(Exception):
+    """OTPStateException class"""
+
+
+class OTPInvalidResponse(Exception):
+    """OTPInvalidResponse class"""
+
+
+class OTPState:
+    """
+    OTPState class
+
+    The OTPState class represents a single state on the server side that can:
+    - generate a challenge
+    - validate the corresponding generated response from the generator
+    """
+
+    def __init__(self, ot_hex, current_step, seed, hash_algo=OTP_ALGO_MD5):
+        """
+        Constructs an OTPState object with the given arguments.
+
+        Keyword Arguments:
+        :param ot_hex: The one-time hex from the last successful
+                       authentication or the first OTP of a newly
+                       initialized sequence
+        :type ot_hex: str
+
+        :param current_step: The current step that is sent with the challenge
+        :type current_step: int
+
+        :param seed: The seed that is sent with the challenge
+        :type seed: str
+
+        :param hash_algo: The hash algo, defaults to OTP_ALGO_MD5
+        :type hash_algo: int or str
+
+        :raises OTPStateException: In case the input does not validate
+        """
+        # enforce the rfc2289 constraints
+        try:
+            self._seed = OTPGenerator.validate_seed(seed)
+            self._hash_algo = OTPGenerator.validate_hash_algo(hash_algo)
+            self._step = OTPGenerator.validate_step(current_step)
+        except OTPGeneratorException as exp:
+            raise OTPStateException(exp.args[0])
+        self._current_digest = self.validate_hex(ot_hex)
+        self._new_digest_hex = None  # set upon a successful validation
+
+    def __str__(self):
+        """Duplicate the challenge string"""
+        return f'otp-{self._hash_algo} {self._step} {self._seed} '
+
+    @property
+    def challenge_string(self):
+        """challenge_string-property"""
+        # RFC-2289: "...the entire challenge string MUST be
+        # terminated with either a space or a new line."
+        return f'otp-{self._hash_algo} {self._step} {self._seed} '
+
+    @property
+    def validated(self):
+        """validated-property"""
+        return bool(self._new_digest_hex)
+
+    @staticmethod
+    def response_to_bytes(response):
+        """
+        A wrapper that handles/validates the response as specified by RFC-2289.
+
+        The method first checks if response is a token and tries to convert
+        it to bytes. If that fails, the method assumes that response is a hex.
+        If neither of those attempts succeeds OTPInvalidResponse is raised.
+        It is up to the caller to run another iteration and compare the result
+        to an existing digest in this state.
+
+        :param response: The response to this state (its challenge)
+        :type response: str
+
+        :raises OTPInvalidResponse: If the response is corrupt / illegal,
+                                    but not if it simply does not validate
+
+        :return: The bytes representation of response (if any)
+        :rtype: bytes
+        """
+        try:
+            return OTPGenerator.tokens_to_bytes(response)
+        except OTPGeneratorException:
+            # now assume hex...
+            try:
+                return OTPState.validate_hex(response)
+            except OTPStateException:
+                raise OTPInvalidResponse(
+                    'The response is neither a valid token or hex')
+
+    @staticmethod
+    def validate_hex(ot_hex):
+        """
+        Validates the provided hexidigest.
+
+        :param ot_hex: The one-time hex to validate
+        :type ot_hex: str
+
+        :raises OTPStateException: In case hex does not validate
+
+        :return: The validated hex (without leading 0x) converted to bytes
+        :rtype: bytes
+        """
+        if not isinstance(ot_hex, str):
+            raise OTPStateException('OT-hex must be a str')
+        if ot_hex.startswith('0x'):
+            ot_hex = ot_hex[2:]
+            ot_hex = ot_hex.strip().lower()
+        if len(ot_hex) != 16:
+            raise OTPStateException('The length of the hex should be 16 '
+                                    '(representing 64 bits digest)')
+        try:
+            return binascii.unhexlify(ot_hex)
+        except binascii.Error:
+            raise OTPStateException('Invalid OT-hex')
+
+    def response_validates(self, response, store_valid_response=True):
+        """
+        Validates the incoming response as specified by RFC-2289.
+
+        :param response: The response to this state (its challenge)
+        :type response: str
+
+        :param store_valid_response: Should a valid response be stored
+        :type store_valid_response: bool
+
+        :raises OTPInvalidResponse: If the response does not match this state
+
+        :return: Returns True if response validates, False otherwise
+        :rtype: bool
+        """
+        # self.response_to_bytes raises OTPInvalidResponse in case response
+        # is corrupt or in a wrong format
+        response_bytes = self.response_to_bytes(response)
+        if self._hash_algo == 'md5':
+            digest = hashlib.md5(response_bytes).digest()
+            if (
+                    OTPGenerator.strxor(digest[0:8], digest[8:]) ==
+                    self._current_digest
+            ):
+                if store_valid_response:
+                    self._new_digest_hex = binascii.hexlify(
+                        response_bytes).decode()
+                return True
+            return False
+        if self._hash_algo == 'sha1':
+            digest = hashlib.sha1(response_bytes).digest()
+            if (
+                    OTPGenerator.sha1_digest_folding(
+                        hashlib.sha1(
+                            response_bytes).digest()) == self._current_digest
+            ):
+                if store_valid_response:
+                    self._new_digest_hex = binascii.hexlify(
+                        response_bytes).decode()
+                return True
+            return False
+        # this should not happen since the hash_algo is validated by the caller
+        raise OTPInvalidResponse(f'Ivalid hash_algo: {self._hash_algo}')