pkcs11/_pkcs11.pyx: use PROTECTED_AUTH sentinel vlaue; pkcs11/types.py: add PROTECTED_AUTH sentinel value and update doc string

Author: Grant Sowards

pkcs11/_pkcs11.pyx

@@ -32,6 +32,7 @@ from .types import (
     _CK_UTF8CHAR_to_str,
     _CK_VERSION_to_tuple,
     _CK_MECHANISM_TYPE_to_enum,
+    PROTECTED_AUTH,
 )
 
 
@@ -225,7 +226,7 @@ class Slot(types.Slot):
 class Token(types.Token):
     """Extend Token with implementation."""
 
-    def open(self, rw=False, user_pin=None, so_pin=None, use_protected_auth=False):
+    def open(self, rw=False, user_pin=None, so_pin=None):
         cdef CK_SESSION_HANDLE handle
         cdef CK_FLAGS flags = CKF_SERIAL_SESSION
         cdef CK_USER_TYPE user_type
@@ -235,13 +236,12 @@ class Token(types.Token):
 
         if user_pin is not None and so_pin is not None:
             raise ArgumentsBad("Set either `user_pin` or `so_pin`")
-        elif user_pin is not None and use_protected_auth:
-            raise ArgumentsBad("Set either `user_pin` or `use_protected_auth`")
-        elif so_pin is not None and use_protected_auth:
-            raise ArgumentsBad("Set either `so_pin` or `use_protected_auth`")
-        elif use_protected_auth:
+        elif user_pin is PROTECTED_AUTH:
             pin = None
             user_type = CKU_USER
+        elif so_pin is PROTECTED_AUTH:
+            pin = None
+            user_type = CKU_SO
         elif user_pin is not None:
             pin = user_pin.encode('utf-8')
             user_type = CKU_USER
@@ -254,7 +254,7 @@ class Token(types.Token):
 
         assertRV(_funclist.C_OpenSession(self.slot.slot_id, flags, NULL, NULL, &handle))
 
-        if use_protected_auth:
+        if so_pin is PROTECTED_AUTH or user_pin is PROTECTED_AUTH:
             if self.flags & TokenFlag.PROTECTED_AUTHENTICATION_PATH:
                 assertRV(_funclist.C_Login(handle, user_type, NULL, <CK_ULONG> 0))
             else:

pkcs11/types.py

@@ -27,6 +27,8 @@
     SignatureLenRange,
 )
 
+PROTECTED_AUTH = object()
+"""Indicate the pin should be supplied via an external mechanism (e.g. pin pad)"""
 
 def _CK_UTF8CHAR_to_str(data):
     """Convert CK_UTF8CHAR to string."""
@@ -200,10 +202,11 @@ def __init__(self, slot,
     def __eq__(self, other):
         return self.slot == other.slot
 
-    def open(self, rw=False, user_pin=None, so_pin=None, use_protected_auth=False):
+    def open(self, rw=False, user_pin=None, so_pin=None):
         """
         Open a session on the token and optionally log in as a user or
-        security officer (pass one of `user_pin` or `so_pin`).
+        security officer (pass one of `user_pin` or `so_pin`). Pass PROTECTED_AUTH to
+        indicate the pin should be supplied via an external mechanism (e.g. pin pad).
 
         Can be used as a context manager or close with :meth:`Session.close`.
 
@@ -217,7 +220,6 @@ def open(self, rw=False, user_pin=None, so_pin=None, use_protected_auth=False):
         :param bytes user_pin: Authenticate to this session as a user.
         :param bytes so_pin: Authenticate to this session as a
             security officer.
-        :param use_protected_auth: True to use protected authentication on a token
 
         :rtype: Session
         """