Set Pin Auth
The Set Pin Authentication method allows you to manage the card’s authentication methods by enabling or disabling PIN-based authentication. This command provides flexibility in how the card verifies user identity during cryptographic operations.
For instance, you can disable set pin authentication and rely solely on alternative methods, such as registered public keys, for user verification. This is particularly useful when integrating the card with external secure key storage solutions like iOS Secure Enclave or PC TPM modules, allowing for set pin authentication without the need for a Set Pin Authentication.
By configuring the card’s authentication settings through the Set Pin Auth command, you can tailor the security and convenience of the card to your specific requirements.
PIN and user auth
The PIN set during initialization must be entered after each EC signature since a signature resets PIN validity. PIN verification follows a standard process but is done through the secure channel (see VERIFY PIN command for details). The PIN must be 4 to 9 digits long and can be entered incorrectly up to three times before requiring a card disconnection. After three more failed attempts, the PIN is locked and must be unlocked using the PUK.
Users also have their own PairingKey, which can be public and shared. Another authentication method involves an EC256r1 or RSA key pair, where a random challenge is signed to function like a PIN. The public key is stored on the card, and blockchain-related EC signatures can be authorized if the hash to be signed is also signed with the user key. This allows the Basic wallet card to work with secure key storage solutions like iOS Secure Enclave (Touch ID) or a PC TPM instead of using a PIN. For details, see the ADD USER KEY and CHECK USER KEY commands.
PIN verification and user authentication are reset after any Elliptic Curve (EC) signature of an authorized hash. Authentication via ECDSA can also be performed using an external FIDO authenticator (see ADD/CHECK USER KEY commands for more details). A user key can be uploaded to a slot only once; if one already exists, it must be deleted before adding a new key. The SetPinAuth command enables disabling PIN authentication, allowing access only through registered public keys.
Command Specifications
Verify Pin Command
You can use this command to authenticate a user by verifying their PIN. If the correct PIN is entered, the card allows further operations requiring authentication, such as cryptographic signatures. If the PIN is incorrect, the retry counter decreases, and after multiple failed attempts, the card may require a power cycle or even block the PIN entirely. The PIN remains valid for the session until the card is reset, powered off, or a cryptographic signature is performed. If the PIN becomes blocked, it must be unblocked using the UNBLOCK PIN command.
Application Protocol Data Unit (APDU) Components
The following table outlines the components of the Application Protocol Data Unit (APDU).
Field | Description | Value |
CLA | This field specifies the class of the instruction. | 0x80 |
INS | This field specifies the particular command or operation that the smart card or secure element should execute. | 0x20 |
P1 | First parameter of the instruction that specifies the details about the operation being requested. | 0x00 |
P2 | First parameter of the instruction that specifies additional details about the operation being requested. | 0x00 |
Data | Key data |
|
📘 Prerequisites
- The secure channel must be open.
Response
The following table outlines the possible responses that you will receive:
Response Code | Description |
0x9000 | Success |
0x6700 | Incorrect data length. |
0x63CX | Failure Note: X is the number of remaining attempts. |
0x6986 |
|
📘 Note
- If no data is provided, the command returns a single byte indicating the number of PIN retries left.
- When data is provided, the command must return a value between 4 and 9.
Command-specific Additional Information
What happens next?
If the entered pin is:
- Correct: The card responds with 0x9000, and the retry counter resets. Once verified, the PIN remains valid for the session unless a signature operation is performed, the application is closed, or the card is removed/reset.
- Incorrect: the number of remaining attempts decreases. The card returns 0x63CX, where X shows how many attempts are left.
Failed attempts
- 3 Failed Attempts: If there are 3 failed attempts, the card will require a power cycle (turning it off and on) before allowing further PIN attempts. If another attempt is made before a power cycle, or if the retry count is checked, the card responds with 0x63C0.
- All failed attempts: If the user fails all attempts (2, 1, and after a power cycle), the PIN gets blocked. When blocked, the card always returns 0x63C0, even if the correct PIN is entered.
Post-Power cycle
If the card still returns 0x63C0 after a power cycle, the PIN is permanently blocked, and the
UNBLOCK PIN command is required to reset it.
Pin verification reset
After successfully using the signature command, PIN verification resets, meaning the user must
verify the PIN again before performing secure operations.
Pin validity
PIN verification stays valid until the card is powered off or a signature operation is performed.
Set Pin Auth Command
The Set Pin Authentication method allows you to manage the card’s authentication methods by
enabling or disabling PIN-based authentication. This command provides flexibility in how the card
verifies user identity during cryptographic operations.
The following code snippet outlines the Python object for this command:
def set_pin_auth(status: bool, puk: str):
card.set_pin_authentication(status, puk)
For example, set_pin_auth(True, “puk_code”).
Application Protocol Data Unit (APDU) Components
The following table outlines the components of the Application Protocol Data Unit (APDU).
Field | Description | Value |
CLA | This field specifies the class of the instruction. | 0x80 |
INS | This field specifies the particular command or operation that the smart card or secure element should execute. | 0xC3P1 |
P1 | First parameter of the instruction that specifies the details about the operation being requested. | 0x00P2 |
P2 | First parameter of the instruction that specifies additional details about the operation being requested. | 0x00 |
Data | Key data |
|
📘 Prerequisites
- The secure channel must be open.
Response
The following table outlines the possible responses that you will receive:
Response Code | Description |
0x9000 | Success |
0x63Cx | PUK not validated. |
0x6A80 | The data’s length is not one unit larger than that of PUK’s length. |
0x6986 | Set (no pin) requested but no user public key loaded. |
Command-specific Additional Information
This command enables “user key authentication” only by disabling the use of the PIN for authentication. It allows switching between PIN-based and key-based authentication.
If the first data byte is greater than 0, PIN authentication is disabled, provided that the PUK is valid and at least one user public key is registered. When disabling PIN authentication, the system ensures that at least one public key is available.
To re-enable PIN authentication, the command must be called with the first data byte set to 0x00. PUK verification is still required to disable this feature.