Add PKCS11 token support with tests and documentation

Author: rajanarahul93

docs/devices/pkcs11.rst

@@ -23,13 +23,9 @@ On Windows, you'll need:
 2. OpenSSL development headers
    - Download from: https://slproweb.com/products/Win32OpenSSL.html
    - Choose the "Win64 OpenSSL" version
-   - During installation, select "Copy OpenSSL DLLs to Windows system directory"
-
-3. The PKCS#11 library for your HSM (usually a .dll file)
-   - Place the .dll file in a system path (e.g., C:\Windows\System32)
-   - Or specify its path using the PKCS11_LIB_PATH environment variable
-
-Installation Steps for Windows:
+   - Ensure the OpenSSL bin directory is on PATH (avoid copying DLLs into Windows system directories)3. The PKCS#11 library for your HSM (usually a .dll file)
+   - Prefer specifying its absolute path via PKCS11_LIB_PATH or placing it alongside the application.
+   - Avoid copying into C:\Windows\System32 to reduce DLL hijack and servicing risk.Installation Steps for Windows:
 
 1. Install the prerequisites in the order listed above
 
@@ -50,10 +46,11 @@ The following environment variables can be used to configure the PKCS#11 device:
 - ``PKCS11_TOKEN_LABEL``: Label of the token to use (default: "Bitcoin")
 
 Usage
------
-
-1. Set up your environment variables:
+- ``PKCS11_LIB_PATH``: Path to the PKCS#11 library (required)
+- ``PKCS11_TOKEN_LABEL``: Label of the token to use (default: "Bitcoin")
+- ``PKCS11_PIN``: User PIN for token login (optional; prefer interactive prompt over env for security)
 
+CLI flags, when provided, should take precedence over environment variables.
    .. code-block:: powershell
       # On Windows (PowerShell):
       $env:PKCS11_LIB_PATH = "C:\path\to\your\pkcs11\library.dll"

hwilib/commands.py

@@ -593,22 +593,37 @@ def install_udev_rules(source: str, location: str) -> Dict[str, bool]:
         return {"success": UDevInstaller.install(source, location)}
     raise NotImplementedError("udev rules are not needed on your platform")
 
+from .key import ExtendedKey
+from .errors import HWWError
+
 class PKCS11Client(HardwareWalletClient):
-    def __init__(self, path: str, password: Optional[str] = None, expert: bool = False, chain: Chain = Chain.MAIN) -> None:
+    def __init__(
+        self,
+        path: str,
+        password: Optional[str] = None,
+        expert: bool = False,
+        chain: Chain = Chain.MAIN,
+        token_label: str = "Bitcoin",
+        master_key_label: str = "MASTER_KEY"
+    ) -> None:
         super(PKCS11Client, self).__init__(path, password, expert, chain)
 
-        # Initialize PKCS11 library and token
-        self.lib = pkcs11.lib(path)  # path should point to the PKCS11 library
-        self.token = self.lib.get_token(token_label='YOUR_TOKEN_LABEL')
-        self.session = self.token.open(user_pin=password)
-
-        # Find the master key
-        self.master_key = self.session.get_key(
-            object_class=ObjectClass.PRIVATE_KEY,
-            key_type=KeyType.EC,
-            label='MASTER_KEY'
-        )
-
+        try:
+            # Initialize PKCS11 library and token
+            self.lib = pkcs11.lib(path)
+            self.token = self.lib.get_token(token_label=token_label)
+            self.session = self.token.open(user_pin=password)
+
+            # Find the master key
+            self.master_key = self.session.get_key(
+                object_class=ObjectClass.PRIVATE_KEY,
+                key_type=KeyType.EC,
+                label=master_key_label
+            )
+        except Exception as e:
+            if hasattr(self, 'session'):
+                self.session.close()
+            raise HWWError(f"Failed to initialize PKCS11 client: {e}")
     def get_pubkey_at_path(self, bip32_path: str) -> ExtendedKey:
         # Implement BIP32 path derivation and get public key
         # You'll need to implement BIP32 path derivation logic

test/run_tests.py

@@ -18,7 +18,12 @@
 from test_jade import jade_test_suite
 from test_bitbox02 import bitbox02_test_suite
 from test_udevrules import TestUdevRulesInstaller
-from test_pkcs11 import TestPKCS11Client
+try:
+    from test_pkcs11 import TestPKCS11Client
+    HAS_PKCS11_TESTS = True
+except ImportError:
+    TestPKCS11Client = None
+    HAS_PKCS11_TESTS = False
 
 parser = argparse.ArgumentParser(description='Setup the testing environment and run automated tests')
 trezor_group = parser.add_mutually_exclusive_group()
@@ -81,7 +86,11 @@
 success = True
 suite = unittest.TestSuite()
 if not args.device_only:
-    suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestDescriptor))
+    if args.pkcs11:
+        if HAS_PKCS11_TESTS:
+            suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestPKCS11Client))
+        else:
+            print("Skipping PKCS11 tests: test_pkcs11 or dependencies not available.", file=sys.stderr)
     suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestSegwitAddress))
     suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestPSBT))
     suite.addTests(unittest.defaultTestLoader.loadTestsFromTestCase(TestBase58))

test/test_pkcs11.py

@@ -53,18 +53,22 @@ def test_initialization(self, mock_pkcs11):
     def test_get_pubkey_at_path(self, mock_pkcs11):
         """Test getting public key at BIP32 path."""
         mock_pkcs11.lib.return_value = self.mock_lib
+        # Provide pkcs11.Attribute constants used by the client
+        mock_pkcs11.Attribute = MagicMock(EC_POINT='EC_POINT', EC_PARAMS='EC_PARAMS')
 
         # Mock key attributes
         self.mock_session.get_key.return_value = MagicMock(
-            get_attribute=lambda x: b'test_pubkey' if x == 'EC_POINT' else b'test_chaincode'
+            get_attribute=lambda attr: {
+                'EC_POINT': b'\x02' + b'\x11' * 32,      # compressed secp256k1 pubkey
+                'EC_PARAMS': b'\x06\x05\x2b\x81\x04\x00\x0a',  # secp256k1 OID
+            }.get(attr)
         )
 
         client = PKCS11Client(self.path, self.password, self.expert, self.chain)
         result = client.get_pubkey_at_path("m/44'/0'/0'/0/0")
 
         self.assertIsInstance(result, ExtendedKey)
-        self.assertEqual(result.key_data, b'test_pubkey')
-
+        self.assertEqual(result.key, b'\x02' + b'\x11' * 32)
     @patch('hwilib.devices.pkcs11.pkcs11')
     def test_sign_tx(self, mock_pkcs11):
         """Test transaction signing."""