Nitrokey HSM PIN / SO PIN format requirements

Hello. I work for a company that uses Nitrokey HSMs for PKI purposes. Today, the question came up what exactly the format requirements for User PIN and SO PIN are.

With the command “pkcs15-tool -D” I got the information that the User PIN has length “min_len:6, max_len:15, stored_len:0” and that the SO PIN has length “min_len:16, max_len:16, stored_len:0”. What does “stored_len” mean here and why is it always zero?

Also with pkcs15-tool, I found out that the type of the User PIN is “ascii-numeric” and the type of the SO PIN is “bcd”. I assume the former means all (printable?) ASCII characters are allowed and the latter is short for Binary Coded Decimal (i.e. only digits are allowed), correct?

Anyway, are the requirements for PIN and SO PIN for the Nitrokey HSM 2 documented somewhere? I could not find any documentation on your web site. Could you please point me to the documentation or add it somewhere?


It is a bit buried, I agree. Linking below:

Excerpt from OpenSC:

The SO-PIN must be composed of 16 hexadecimal characters. The value is internally converted into an 8 byte key value. The SO-PIN has a retry counter of 15 and can not be unblocked. Blocking the SO-PIN will prevent any further token initialization or PIN unblock.

About stored_len my guess is, that some smart cards are storing the PIN within their memory, hence it was added to general info. Looking at the user manual, Nitrokey HSM never stores the PIN in any way, but creates and uses its structures dynamically from it.

Edit: In case you would need the user manual for the Nitrokey HSM please write to

Internally (i.e. at the APDU interface) the User-PIN is between 6 and 16 byte, while the SO-PIN is always 8 byte.

Encoding is left to the crypto middleware, but typically the User-PIN is encoded ASCII, while the SO-PIN is encoded BCD.

The limitation to 15 is just a limitation in the middleware, as some class-3 PIN-PAD reader (most notably cyberjack) report an error if the PIN is 16 or more digits (It’s because they use a 26*2 character LCD).

User manuals and other documentation is available at the CardContact Developer Network.