Refactored ctap user verifiers

- Windows hello ctap user verifier is now based on winrt (vs winbio)
- Added flow images to readme.rst

Author: dany74q

.coveragerc

@@ -1,8 +1,7 @@
 [run]
 omit =
     .tox/*
-    ctap_keyring_device/touch_id_helpers.py
-    ctap_keyring_device/windows_hello_helpers.py
+    ctap_keyring_device/user_verifiers/*
 
 branch = True
 

README.rst

@@ -110,6 +110,25 @@ See examples in ``ctap-keyring-device/tests``.
 
 |
 
+CTAP Flow Diagrams
+==================
+
+Make Credential Flow
+********************
+
+.. image:: images/make-credential-flow.png
+  :alt: Make Credential Flow
+
+|
+
+Get Assertion Flow
+******************
+
+.. image:: images/get-assertion-flow.png
+   :alt: Get Assertion Flow
+
+|
+
 Security Considerations
 =======================
 

ctap_keyring_device/ctap_keyring_device.py

@@ -33,7 +33,9 @@
     Credential,
     CtapGetAssertionRequest,
 )
-from ctap_keyring_device.ctap_user_verifiers import CtapUserVerifier
+from ctap_keyring_device.user_verifiers.ctap_user_verifier_factory import (
+    CtapUserVerifierFactory,
+)
 
 
 class CtapKeyringDevice(ctap.CtapDevice):
@@ -92,7 +94,7 @@ def __init__(self):
         )
 
         self._next_assertions_ctx: Optional[CtapGetNextAssertionContext] = None
-        self._user_verifier = CtapUserVerifier.create()
+        self._user_verifier = CtapUserVerifierFactory.create()
 
     @classmethod
     def list_devices(cls):

ctap_keyring_device/ctap_user_verifiers.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+import abc
+
+# noinspection PyBroadException
+try:
+    from ctap_keyring_device.user_verifiers.windows_hello_ctap_user_verifier import (
+        WindowsHelloCtapUserVerifier,
+    )
+except Exception:
+    WindowsHelloCtapUserVerifier = None
+
+# noinspection PyBroadException
+try:
+    from ctap_keyring_device.user_verifiers.touch_id_ctap_user_verifier import (
+        TouchIdCtapUserVerifier,
+    )
+except Exception:
+    TouchIdCtapUserVerifier = None
+
+
+class CtapUserVerifier(metaclass=abc.ABCMeta):
+    """
+    Implementors of this interface supply a user verification and presence scheme.
+
+    This could be with biometrics, face-recognition, password prompt, or otherwise.
+    """
+
+    @abc.abstractmethod
+    def available(self) -> bool:
+        """ If set, this verifier is available on the current OS """
+        raise NotImplementedError()
+
+    @abc.abstractmethod
+    def verify_user(self, rp_id: str) -> bool:
+        """ Returns true if the user was successfully verified """
+        raise NotImplementedError()
+
+
+class CtapUserVerifierBase(CtapUserVerifier, metaclass=abc.ABCMeta):
+    """A base class for user verifiers - implemented methods may throw, in which case False is returned
+    in both available() and verify_user()"""
+
+    def available(self) -> bool:
+        # noinspection PyBroadException
+        try:
+            return self._available()
+        except Exception:
+            return False
+
+    @abc.abstractmethod
+    def _available(self) -> bool:
+        raise NotImplementedError()
+
+    def verify_user(self, rp_id: str) -> bool:
+        if not self.available():
+            return False
+
+        # noinspection PyBroadException
+        try:
+            return self._verify_user(rp_id)
+        except Exception:
+            return False
+
+    @abc.abstractmethod
+    def _verify_user(self, rp_id: str) -> bool:
+        raise NotImplementedError()

ctap_keyring_device/user_verifiers/__init__.py

@@ -0,0 +1,41 @@
+# -*- coding: utf-8 -*-
+import platform
+
+from ctap_keyring_device.user_verifiers.ctap_user_verifier import CtapUserVerifier
+from ctap_keyring_device.user_verifiers.noop_ctap_user_verifier import (
+    NoopCtapUserVerifier,
+)
+
+try:
+    from ctap_keyring_device.user_verifiers.touch_id_ctap_user_verifier import (
+        TouchIdCtapUserVerifier,
+    )
+except ImportError:
+    TouchIdCtapUserVerifier = None
+
+try:
+    from ctap_keyring_device.user_verifiers.windows_hello_ctap_user_verifier import (
+        WindowsHelloCtapUserVerifier,
+    )
+except ImportError:
+    WindowsHelloCtapUserVerifier = None
+
+
+class CtapUserVerifierFactory:
+    """Creates a concrete instance of a CtapUserVerifier implementation, depending on the platform and available
+    user presence detection mechanisms available"""
+
+    @staticmethod
+    def create() -> CtapUserVerifier:
+        system = platform.system()
+        if system == 'Darwin' and TouchIdCtapUserVerifier is not None:
+            touch_id_verifier = TouchIdCtapUserVerifier()
+            if touch_id_verifier.available():
+                return touch_id_verifier
+
+        if system == 'Windows' and WindowsHelloCtapUserVerifier is not None:
+            windows_hello_verifier = WindowsHelloCtapUserVerifier()
+            if windows_hello_verifier.available():
+                return windows_hello_verifier
+
+        return NoopCtapUserVerifier()

ctap_keyring_device/user_verifiers/ctap_user_verifier.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+from ctap_keyring_device.user_verifiers.ctap_user_verifier import CtapUserVerifierBase
+
+
+class NoopCtapUserVerifier(CtapUserVerifierBase):
+    """ Dummy verifier - always returns true """
+
+    def _available(self) -> bool:
+        return True
+
+    def _verify_user(self, rp_id: str) -> bool:
+        return True

ctap_keyring_device/user_verifiers/ctap_user_verifier_factory.py

@@ -3,24 +3,26 @@
 # Taken from and slightly modified:
 # https://raw.githubusercontent.com/lukaskollmer/python-touch-id/master/touchid.py (MIT License)
 
+from threading import Event
+
 # noinspection PyUnresolvedReferences
 from LocalAuthentication import LAContext, LAPolicyDeviceOwnerAuthentication
-from threading import Event
+
+from ctap_keyring_device.user_verifiers.ctap_user_verifier import CtapUserVerifierBase
 
 
-class TouchId:
+class TouchIdCtapUserVerifier(CtapUserVerifierBase):
+    """ A Touch ID based CTAP User Verifier - Prompts for the user's login password / fingerprint """
+
     LA_POLICY = LAPolicyDeviceOwnerAuthentication
 
     def __init__(self):
         self._context = LAContext.new()
 
-    def available(self) -> bool:
+    def _available(self) -> bool:
         return self._context.canEvaluatePolicy_error_(self.LA_POLICY, None)[0]
 
-    def verify(self, reason) -> bool:
-        if not self.available():
-            raise Exception("Touch ID isn't available on this machine")
-
+    def _verify_user(self, rp_id: str) -> bool:
         success, err, event = False, None, Event()
 
         def cb(_success, _error):
@@ -31,10 +33,9 @@ def cb(_success, _error):
 
             event.set()
 
-        self._context.evaluatePolicy_localizedReason_reply_(self.LA_POLICY, reason, cb)
+        self._context.evaluatePolicy_localizedReason_reply_(
+            self.LA_POLICY, 'verify ctap user identity of ' + rp_id, cb
+        )
 
         event.wait()
-        if err:
-            raise RuntimeError(err)
-
-        return success
+        return err is None and success

ctap_keyring_device/user_verifiers/noop_ctap_user_verifier.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+
+# noinspection PyUnresolvedReferences
+import winrt.windows.security.credentials.ui as ui
+import asyncio
+
+from ctap_keyring_device.user_verifiers.ctap_user_verifier import CtapUserVerifierBase
+
+
+class WindowsHelloCtapUserVerifier(CtapUserVerifierBase):
+    """ A Windows Hello based CTAP User verifier; Prompts for a PIN / fingerprint """
+
+    def __init__(self):
+        self._event_loop = asyncio.get_event_loop()
+
+    def _available(self) -> bool:
+        fut = ui.UserConsentVerifier.check_availability_async()
+        res = self._event_loop.run_until_complete(fut)
+
+        return res == ui.UserConsentVerifierAvailability.AVAILABLE
+
+    def _verify_user(self, rp_id: str) -> bool:
+        fut = ui.UserConsentVerifier.request_verification_async(
+            'verify ctap user identity of ' + rp_id
+        )
+        res = self._event_loop.run_until_complete(fut)
+
+        return res == ui.UserConsentVerificationResult.VERIFIED