Introduction

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 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 authentication without the need for a PIN.

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 reset after any EC signature of an authorized hash. User authentication via ECDSA can also be done using an external FIDO authenticator (see ADD/CHECK USER KEY commands for more details). A user key can only be uploaded to a slot once; if a key is already present, it must be deleted before a new one is added. The SetPinAuth command allows disabling PIN authentication so that only registered public keys are used for authentication.

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).

📘

Prerequisites:

• The secure channel must be open.

Response

The following table outlines the possible responses that you will receive:

📘

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).

📘

Prerequisites:

• The secure channel must be open.

Response

The following table outlines the possible responses that you will receive:

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. The PUK verification is still required to disable this feature..