SecureSign — Testing Setup Guide (Another PC)

Everything needed to set up a fresh Windows PC to test the SecureSign USB CCID smart-card dongle (STM32F417 prototype), from a blank machine to running the Level 1–3 test cases in SecureSign_Testing_Guide.html. No firmware rebuild required — this is for testing an already-flashed device.

Why this isn't just "install OpenSC": the stock OpenSC installer's generic card driver never registers a signing mechanism for unrecognized cards (a real gap in OpenSC itself, not this device) and one PKCS#11-layer function is too strict about which mechanisms it accepts. Two small OpenSC-side source patches fix this — the patched DLLs are provided as a ready-to-use download in Step 2, so you don't need a build toolchain unless you specifically want to rebuild them yourself (see the Appendix).

Quick setup (recommended): Setup-SecureSign.ps1 automates Steps 1–7 below — installs OpenSC if missing, deploys the patched module, optionally registers the friendly device name, installs jSignPdf, checks Python/Flask, and downloads the web app. Safe to re-run (skips anything already done). Download and run in an elevated PowerShell:

iwr https://securesigndongle.rioncore.com/downloads/Setup-SecureSign.ps1 -OutFile Setup-SecureSign.ps1
.\Setup-SecureSign.ps1

It self-elevates (UAC prompt) if not already running as Administrator. See Get-Help .\Setup-SecureSign.ps1 -Full for parameters (custom install path, skipping individual steps). Prefer doing it by hand, or want to understand each step first? Continue reading below.

1. Hardware & OS requirements

Item	Requirement
PC	Windows 10 or 11, 64-bit
Device	SecureSign USB CCID dongle (STM32F417 prototype), already flashed with firmware
Cable	USB cable matching the board's connector (no drivers needed — it enumerates as a driverless composite CDC + CCID device)
Admin rights	Required for installing OpenSC and replacing files under `C:\Program Files\`

2. Install and patch OpenSC (required for all levels)

1Download and install the official OpenSC Windows build (0.27.x, 64-bit MSI) from github.com/OpenSC/OpenSC/releases. Accept all defaults — it installs to C:\Program Files\OpenSC Project\OpenSC\.
2Plug in the SecureSign dongle. Windows should enumerate it with no driver prompt — check Device Manager: a COM port under "Ports (COM & LPT)" and a reader under "Smart card readers" (it may show as "Unknown Smart Card" until Step 4's optional registry entry is added — that's cosmetic only).
3Download the patched OpenSC module package: securesigndongle.rioncore.com/downloads/opensc_patch_package.zip (~7 MB). It contains two folders, tools\ and pkcs11\, mirroring the install layout.
4Close any running OpenSC processes (Task Manager → check for opensc-notify.exe or similar; end it if present — it can lock the DLL).
5Copy the files over the installed ones, in an elevated PowerShell/cmd:
```
copy /Y "<extracted>\tools\*"   "C:\Program Files\OpenSC Project\OpenSC\tools\"
copy /Y "<extracted>\pkcs11\*"  "C:\Program Files\OpenSC Project\OpenSC\pkcs11\"
```
This replaces opensc.dll, opensc-pkcs11.dll, and their libcrypto-3-x64.dll / zlib1.dll runtime dependencies in both directories with the patched build. It does not touch onepin-opensc-pkcs11.dll or any of the other card-specific tools — those are unaffected/unused by this device.

6Verify the patch took effect:

cd "C:\Program Files\OpenSC Project\OpenSC\tools"
.\opensc-tool.exe --list-readers
.\opensc-tool.exe --atr

Should list the SecureSign reader and return a 19-byte ATR with no error.

PIN: the demo PIN is 1234 for every test below. It's a fixed demo value baked into this prototype's firmware, not something you set up.

3. (Optional) Friendly device name in Windows

Without this, Device Manager and the Windows Certificates snap-in may show "Unknown Smart Card" instead of "SEQUENTIA SecureSign Dongle". Purely cosmetic — every test below works either way.

1Get the device's ATR: opensc-tool --atr (from Step 2.6 above).

2In an elevated PowerShell, create the registry key (replace the ATR bytes with what your device actually returned):

New-Item -Path "HKLM:\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards\SEQUENTIA SecureSign Dongle" -Force
Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards\SEQUENTIA SecureSign Dongle" `
  -Name "ATR" -Value ([byte[]](0x3B,0x9F,0x11, ...rest of your device's ATR bytes...))
Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards\SEQUENTIA SecureSign Dongle" `
  -Name "ATRMask" -Value ([byte[]](0xFF,0xFF,0xFF, ...same length, all 0xFF...))

Unplug and replug the device afterward for Windows to pick it up.

4. Level 1 — Device / Raw APDU testing

No extra install needed beyond Step 2. From C:\Program Files\OpenSC Project\OpenSC\tools\:

.\opensc-tool.exe --list-readers
.\opensc-tool.exe --atr
.\opensc-tool.exe --send-apdu 00A4000C023F00
.\opensc-tool.exe --send-apdu 002000010431323334        REM VERIFY PIN 1234

Full command list and expected results: SecureSign_Testing_Guide.html, Level 1 table (TC 1.1–1.12).

5. Level 2 — PKCS#15 / PKCS#11 tooling

Same directory, no extra install:

.\pkcs15-tool.exe --dump
.\pkcs15-tool.exe --list-certificates
.\pkcs11-tool.exe --module "C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll" --list-objects
.\pkcs11-tool.exe --module "C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll" --login --pin 1234 --test
.\pkcs11-tool.exe --module "C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll" ^
  --sign --mechanism ECDSA --login --pin 1234 -i data.bin -o data.sig

Full command list and expected results: SecureSign_Testing_Guide.html, Level 2 table (TC 2.1–2.5).

6. Level 3 — Real application testing

6a. PDF signing via jSignPdf (free, no license needed)

1Download jsignpdf-3.1.0-windows-x64.zip from SourceForge (~130 MB — it bundles its own Java runtime, so no separate JDK/JRE install is required). Extract it, e.g. to C:\jsignpdf\.

2Create a folder for its config, e.g. C:\jsignpdf\config\, and inside it a file named pkcs11.cfg:

name=SecureSign
library=C:/Program Files/OpenSC Project/OpenSC/pkcs11/opensc-pkcs11.dll
slotListIndex=0

3In PowerShell, set the config directory and list the available signing key (confirms the token is recognized — TC 3.1):
```
$env:JSIGNPDF_CONFIG_DIR = "C:\jsignpdf\config"
& "C:\jsignpdf\JSignPdf\JSignPdfC.exe" -kst PKCS11 -ksp 1234 -lk
```
Should print SecureSignCert as an available key alias.

4Sign a PDF (TC 3.2):

& "C:\jsignpdf\JSignPdf\JSignPdfC.exe" -kst PKCS11 -ksp 1234 -ka SecureSignCert `
  -r "Test signature" -l "Test Bench" --overwrite -d "C:\jsignpdf" "C:\path\to\your.pdf"

Produces your_signed.pdf with a real embedded PAdES/CMS signature from the device.

6b. Programmatic sign/verify via PyKCS11 (Python)

1Install Python 3.10+ from python.org (check "Add to PATH" during install).
2pip install PyKCS11 (prebuilt wheel, no compiler needed).

3Run:

import PyKCS11

pkcs11 = PyKCS11.PyKCS11Lib()
pkcs11.load(r"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll")
slots = pkcs11.getSlotList(tokenPresent=True)
session = pkcs11.openSession(slots[0], PyKCS11.CKF_SERIAL_SESSION | PyKCS11.CKF_RW_SESSION)
session.login("1234")
priv = session.findObjects([(PyKCS11.CKA_CLASS, PyKCS11.CKO_PRIVATE_KEY)])[0]
sig = session.sign(priv, b"\x00" * 32, PyKCS11.Mechanism(PyKCS11.CKM_ECDSA, None))
print("signature:", bytes(sig).hex())
session.logout()
session.closeSession()

7. Troubleshooting

Symptom	Cause / Fix
Device shows in Device Manager but `opensc-tool --list-readers` lists nothing	Windows Smart Card service isn't running: `Start-Service SCardSvr` (elevated PowerShell)
`CKR_MECHANISM_INVALID` on `pkcs11-tool --sign`	The patched DLLs from Step 2 weren't actually deployed — verify with `Get-FileHash "C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"` and compare against the downloaded package's hash. If it doesn't match, another process may be re-locking/reverting the file — close all OpenSC-related processes and retry the copy.
Copy to `Program Files` fails with "file in use"	`Get-Process \| Where-Object {$_.ProcessName -match "opensc\|pkcs11\|pkcs15\|scardsvr"}`, stop any match, retry
jSignPdf: `PKCS11 KeyStore not available` / `KeyStoreException`	`$env:JSIGNPDF_CONFIG_DIR` isn't set, or `pkcs11.cfg` isn't in that exact folder — the provider is registered automatically only from that specific location
jSignPdf: `CKR_SLOT_ID_INVALID` / `slotListIndex is 0 but token only has 0 slots`	Device not detected right now — check `opensc-tool --list-readers` works first; replug the device if needed
PyKCS11: `PyKCS11Error: Load (...)` / `LoadLibrary() failed with error 127`	Add the pkcs11 directory to `PATH` before loading: `os.environ["PATH"] = r"C:\Program Files\OpenSC Project\OpenSC\pkcs11" + os.pathsep + os.environ["PATH"]` (must be set in Python, before `import PyKCS11` triggers the load) — PyKCS11's native loader doesn't search the DLL's own directory for its `libcrypto`/`zlib` dependencies the way `ctypes` does.

8. Running the "Sign a PDF" web app (`127.0.0.1:5001`)

The site's Sign a PDF tab (and the standalone securesign_webapp/ app) needs a small local service running on your own PC — the dongle can't be reached from a remote server, so any hosted page is only the UI; the actual signing happens locally. To get it working, someone needs all of the following on their own PC:

1Windows 10/11 PC with admin rights.
2A physical SecureSign dongle, plugged into that PC via USB — this is the hard requirement; there's no way around needing the actual hardware.
3OpenSC installed + patched (Step 2 above).
4jSignPdf installed (Step 6a above).
5Python 3.10+ installed, then pip install flask.
6Download and extract the signing app: securesigndongle.rioncore.com/downloads/securesign_webapp.zip
7Run python app.py from that folder — this starts the local service on port 5001.
8Then open either http://127.0.0.1:5001 directly, or securesigndongle.rioncore.com's Sign a PDF tab — both work identically, since the hosted tab just calls back to 127.0.0.1:5001 on that same machine.

Without step 7 (app.py actually running) and step 2 (the real dongle plugged in), nothing on that tab will work — it'll just show "local signing service not reachable."

Appendix: Rebuilding the patched OpenSC module from source

Only needed if you don't have access to the prebuilt package in Step 2, or want to modify the patches yourself. This is a from-scratch MinGW build — expect this to take a while to set up the first time.

A1. Toolchain

MinGW-w64 GCC (winlibs UCRT build recommended) — provides gcc, windres, dlltool
OpenSSL 3.x development files (headers + libcrypto.a/libcrypto.dll.a import lib) — build from source or take from an MSYS2 mingw-w64-x86_64-openssl package
zlib development files (same source options)
Git, to clone the OpenSC source: git clone --depth 1 https://github.com/OpenSC/OpenSC.git (this build used the version matching release 0.27.1)

A2. Source patches

Two files need changing, both under src/libopensc/ and src/pkcs11/:

1src/libopensc/card-default.c, in default_init(): the generic/unrecognized-card driver never registers any algorithm capability, which is why OpenSC's PKCS#11 layer never exposes a signing mechanism for this device at all. Add:

struct sc_object_id prime256v1_oid = {{1, 2, 840, 10045, 3, 1, 7, -1}};
unsigned long flags = SC_ALGORITHM_ECDSA_RAW | SC_ALGORITHM_ECDSA_HASH_NONE;
unsigned long ext_flags = SC_ALGORITHM_EXT_EC_NAMEDCURVE | SC_ALGORITHM_EXT_EC_UNCOMPRESES
                         | SC_ALGORITHM_EXT_EC_F_P;
_sc_card_add_ec_alg(card, 256, flags, ext_flags, &prime256v1_oid);

Deliberately no SC_ALGORITHM_ONBOARD_KEY_GEN — this device can't generate keys on-board.

2src/pkcs11/framework-pkcs15.c, in pkcs15_prkey_can_do(): change the final LOG_FUNC_RETURN(context, CKR_MECHANISM_INVALID); to LOG_FUNC_RETURN(context, CKR_FUNCTION_NOT_SUPPORTED);. Without this, a mechanism not explicitly declared in on-card TokenInfo.supportedAlgorithms (e.g. the combined CKM_ECDSA_SHA256 that Java's SunPKCS11 provider requests directly) aborts immediately instead of falling through to OpenSC's own software sign-and-hash wrapper mechanism, which is already registered and would otherwise work correctly.

A3. Windows-specific build fixes needed

Provide an empty config.h on the include path (several files #include "config.h" unconditionally) and pass -include winconfig.h instead of -DHAVE_CONFIG_H
Add missing version/package macros: -DPACKAGE_VERSION="0.27.1" -DVERSION="0.27.1" -DPACKAGE="OpenSC" -DPACKAGE_NAME="OpenSC" -DOPENSC_VS_FF_COMPANY_NAME="OpenSC Project" -DOPENSC_VS_FF_PRODUCT_NAME="OpenSC PKCS11 module" -DOPENSC_VERSION_MAJOR=0 -DOPENSC_VERSION_MINOR=27
Exclude the 6 regional card drivers that need OpenPACE/sm-eac.c (dtrust, sc-hsm, cedulauy, srbeid, eoi, npa) — irrelevant to this device — and provide stub implementations for their driver-getter functions (returning NULL, the documented "driver not available" case) plus stubs for their sc_pkcs15emu_*_init_ex functions
Compile src/libopensc/*.c, src/scconf/*.c, src/common/*.c, src/ui/*.c, and src/sm/sm-iso.c into opensc.dll
Compile src/pkcs11/pkcs11-global.c pkcs11-session.c pkcs11-object.c misc.c slot.c mechanism.c openssl.c debug.c pkcs11-display.c framework-pkcs15.c together with the same libopensc objects into opensc-pkcs11.dll (statically linking libopensc in, not depending on opensc.dll at runtime)
Link both DLLs dynamically against libcrypto and zlib (static linking hit a MSVCRT/UCRT symbol mismatch in prebuilt import archives), and distribute libcrypto-3-x64.dll / zlib1.dll alongside each output DLL
opensc-pkcs11.dll additionally needs -lwinscard -lshlwapi -lws2_32 -lcomctl32 and a hand-written .def export file (derived from OpenSC's own opensc.exports / pkcs11.exports, with sc_pkcs15init_*/eac_* symbols stripped since the pkcs15init subsystem isn't built)

After rebuilding: deploy exactly as in Step 2.5 — copy the new opensc.dll + runtime deps into tools\, and the new opensc-pkcs11.dll + runtime deps into pkcs11\.