#User authentication

Most operations with the card (all involving operations with the wallet or credentials) require authenticating the user. After authentication, the user remains authenticated until the card is powered off or the application is re-selected.

Authentication is performed by verifying the user PIN. Note that this piece of information is sensitive and must be handled accordingly in the application. PIN verification is done with a single step

// pin is the user PIN as a string of 6 digits
try {
  cmdSet.verifyPIN(pin).checkAuthOK();
} catch(WrongPINException e) {
  System.out.println("Number of remaining attempts: " + e.getRetryAttempts());
}

if the PIN is wrong, you will receive an error SW in the format 0x63CX where X is the number of attempts remaining. When the number of remaining attempts is 0, the card is blocked. The user must then enter the PUK and a new PIN to restore access to the card. To simplify things, the APDUResponse.checkAuthOK() method can be used to verify if the authentication was correct, and if not throw a WrongPINException which contains the number of remaining attempts.

cmdSet.unblockPIN(puk, newPIN).checkAuthOK();

#The duress PIN

The duress PIN is verified through the same call. Both PINs are accepted and the response is identical either way — that is the point. What differs is the wallet the session sees: authenticating with the duress PIN switches the derivation chain, so the same BIP-32 paths yield a different set of keys. If your application caches addresses per path, it must not assume a session that authenticated with a duress PIN is looking at the same wallet.

#Changing credentials

// Changes the user PIN
cmdSet.changePIN("123456").checkOK();
 
// Changes the PUK
cmdSet.changePUK("123456123456").checkOK();

To change the duress PIN, authenticate with the duress PIN first and then call changePIN with the new value — the card replaces whichever PIN is currently authenticated.