Skip to content

README.md

Latest commit

 

History

History
111 lines (83 loc) · 4.21 KB

README.md

File metadata and controls

111 lines (83 loc) · 4.21 KB
Raw

CanoKey Mini Driver

Windows smart card minidriver for CanoKey, built on top of canokey-pkcs11.

Status: this project is still WIP, but the development loop is usable. Windows can load the DLL through a Calais smart card registry mapping without installing the generated INF. Current local testing can enumerate the CanoKey PIV certificates and run CSP/KSP signing, RSA decryption, and ECDH raw-secret derivation tests against the development card. Release packaging, INF installation, and broader PIV slot coverage are still in progress.

Current State

  • Debug loading works by copying canokey-minidriver.dll to C:\canokey-minidriver\ and registering that path under the CanoKey ATR.
  • Minidriver configuration is read from HKLM\SOFTWARE\Canokeys\ckmd. Logging is disabled unless LogPath is set there; LogLevel and LogSensitiveData control verbosity and APDU/hex dumps.
  • certutil -scinfo can see the card and current certificates.
  • scripts\crypto-test.ps1 exercises the minidriver through Windows CAPI/CNG APIs instead of parsing command output. The same checks can be run in focused groups with sign-test.ps1, decrypt-test.ps1, and derive-test.ps1.
  • The current development card has been tested with 9A RSA-2048 signing, 9C EC P-256 signing plus ECDH raw-secret derivation, and 9D RSA-2048 signing plus key exchange/decryption.

Known gaps:

  • Full YubiKey-style PIV slot mapping still needs broader card coverage.
  • ECDH currently supports raw secret derivation only (BCRYPT_KDF_RAW_SECRET / PKCS#11 CKD_NULL). Higher-level KDF parameter lists are not implemented yet.
  • INF installation is kept for later release validation.
  • The test matrix depends on which keys and certificates are provisioned on the attached CanoKey.

Build

Prerequisites

Install Visual Studio 2022 with:

  • Desktop development with C++
  • Clang Support
  • Windows Driver Kit (download from here)

Build with CMake

You can configure the project with CMake (or use Visual Studio GUI). You must use clang-cl as the frontend, or external/dbg.h will fail to compile.

After successful build, you will get canokey-minidriver.{inf,dll} in your build output directory.

The helper script uses the same defaults as the local debug workflow:

.\build.ps1 -Arch x64 -Config Debug

If the TF-PSA-Crypto generator needs a specific Python environment, pass it explicitly:

.\build.ps1 -Arch x64 -Config Debug -Python3Executable C:\Path\To\python.exe

Test

For development, you do not need to install the INF. Windows can load the minidriver through the Calais smart card registry mapping:

.\build.ps1 -Arch x64 -Config Debug
cmake --build out\build\x64-Clang-Debug --target canokey-minidriver-debug-install

This copies the DLL to C:\canokey-minidriver\ and creates C:\canokey-minidriver\logs\. Import the debug Calais mapping and optional HKLM\SOFTWARE\Canokeys\ckmd configuration described in docs/development.md, then unplug and reinsert your CanoKey or restart the calling application.

Useful local checks:

.\scripts\smoke-scinfo.ps1
.\scripts\crypto-test.ps1

smoke-scinfo.ps1 drives certutil -silent -pin ... -scinfo against the CanoKey reader. crypto-test.ps1 uses Windows cryptographic APIs directly to enumerate containers and run the full local matrix: signing, RSA decrypt, and ECDH raw-secret derivation against a software-generated peer key. For fast focused reruns, use sign-test.ps1, decrypt-test.ps1, or derive-test.ps1 with -SkipBuild -SkipInstall -SkipReset.

INF installation is still useful for release-style validation and final packaging. For that flow, enable test signing mode if needed, install the generated INF, and uninstall the old driver package before testing a new version.

Troubleshooting

If you encounter any strange problems, you may try to (in order):

  • Re-plug your CanoKey.
  • Restart the calling application.
  • Restart the CertPropSvc service (espcially when you cannot read or delete the log files).
  • Uninstall and reinstall the driver if you are testing the INF path.
  • Reboot your computer.