Token PIN Lockout: Prevention and Recovery

This guide explains how to prevent hardware cryptographic token lockouts and outlines the exact recovery steps if your YubiKey, SafeNet, or ePass2003 device becomes blocked during PDF or code signing operations.

Understanding Token PIN and SO-PIN Behavior

OneSigner relies on certificates held on physical USB hardware tokens. Since June 2023, the CA/Browser Forum requires certified hardware for all code signing certificates, making hardware-backed keys mandatory for both OV and EV certificates. These hardware tokens enforce strict security policies to protect your private keys against brute-force attacks.

Every PKCS#11 or CryptoAPI-compatible token utilizes two distinct credentials:

• User PIN: The standard password entered during routine signing operations by the OneSigner service or GUI. Entering it incorrectly more times than the token's retry limit allows will lock the User PIN. The limit is set by the token: YubiKey PIV defaults to 3, while SafeNet and ePass2003 tokens use the limit chosen when the token was initialized.
• Security Officer PIN (SO-PIN / PUK): The administrative credential used to reset a locked User PIN. The SO-PIN/PUK has its own retry limit. Once that is exhausted too, the User PIN can no longer be reset; on most tokens the only way back is a full reset or re-initialization, which erases the private key, so the Certificate Authority must issue a new certificate.

Because OneSigner requires a dedicated Windows machine that stays powered on with the token physically plugged into a USB port, environmental factors such as automated script re-authentication loops or background service conflicts can inadvertently exhaust your retry attempts.

Preventing Accidental Lockouts

Proactive configuration prevents unexpected interruptions in your document workflows and automated CI/CD pipelines. Follow these operational guidelines to maintain token stability on your Windows host:

1. Store the PIN Once, Correctly: Enter the PIN once in the OneSigner config app, where it is saved on that machine and supplied automatically for every signature, rather than hardcoding it into batch scripts or typing it interactively where typos happen. When the token is accessed over PKCS#11, OneSigner does not retry a rejected PIN, so a single job never burns several attempts. Each new job does use the saved PIN again, though: if you change the token PIN, update it in OneSigner straight away, and if jobs start failing with a PIN error, stop the OneSigner service until the saved PIN is corrected.
2. Avoid Competing PIN Prompts: Do not uninstall the token middleware (for example SafeNet Authentication Client) — OneSigner needs the vendor driver to see the token. Instead, make sure no other script, tool or person is logging in to the same token with an old or guessed PIN while OneSigner is signing.
3. Monitor Windows Session State: Ensure the host machine does not drop into a power-saving sleep state that terminates the cryptographic service provider context mid-signature. If several systems need to sign, point them all at the one OneSigner host (for CI/CD, through the Azure Key Vault Proxy) instead of passing the token and its PIN between machines.
4. Verify Token Model Limits: Check your specific token documentation (YubiKey PIV, SafeNet eToken 5110, or Feitian ePass2003) for exact retry thresholds before attempting manual unlocks.

Recovering a Locked User PIN

If the User PIN has reached its maximum failed attempts but the SO-PIN remains intact, you can reset the User PIN using the manufacturer's management utility or command-line tools. You will need your administrative SO-PIN (PUK) established during token initialization.

For YubiKey tokens using the PIV applet, open an administrative command prompt and use the ykman utility to unblock the PIN with the PUK (it prompts for the PUK and a new PIN):

ykman piv access unblock-pin

For SafeNet and ePass2003 tokens, open the vendor management console:

1. Launch the appropriate token client software (e.g., SafeNet Authentication Client).
2. Select your connected token device from the reader list and open its advanced properties or token settings.
3. Choose the option to unlock the token or reset the user PIN (the exact label differs between vendor tools and versions).
4. Enter the Security Officer PIN (SO-PIN) when prompted.
5. Define and confirm a new User PIN, ensuring it complies with the device complexity requirements, then enter the new PIN in the signing profile in the OneSigner config app so the saved PIN matches.
6. Restart the OneSigner Windows service to refresh the cryptographic provider handles:

net stop OneSignerService
net start OneSignerService

Handling Permanent Token Bricking

If both the User PIN and the SO-PIN retry counters are exhausted, the hardware token enters a permanent lockout state for security reasons. Neither OneSigner nor the Certificate Authority can override this physical protection mechanism.

When permanent bricking occurs, you must:

• Reset the token if the vendor tool supports it, or procure a replacement. Either way the old private key is gone: it cannot be exported or recovered from the token.
• Contact your Certificate Authority or follow the re-issuance process via your certificate provider portal to request a new certificate instance loaded onto a fresh token.
• Review our recommendations for Choosing Your USB Token and CA to select hardware configurations that best match your organization's operational redundancy requirements.

To verify successful recovery, check that the certificate still appears in the Certificate dropdown of your signing profile in the OneSigner config app and execute a test signature via the local REST API or watched folder.