From 81262443986e3735c54bc540133a9a1a0b879783 Mon Sep 17 00:00:00 2001
From: Michele Balistreri <michele@bitgamma.com>
Date: Tue, 8 Jan 2019 15:21:16 +0300
Subject: [PATCH] PIN verification/change

---
 source/api/java-sdk.md | 32 +++++++++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/source/api/java-sdk.md b/source/api/java-sdk.md
index 7eb012f3..6eca0006 100644
--- a/source/api/java-sdk.md
+++ b/source/api/java-sdk.md
@@ -256,7 +256,21 @@ handled accordingly in the application. PIN verification is done with a single s
 
 ```java
 // pin is the user PIN as a string of 6 digits
-cmdSet.verifyPIN(pin).checkOK();
+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. The maximum number of retries for the PUK is 5. 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.
+
+```java
+cmdSet.unblockPIN(puk, newPIN).checkAuthOK();
 ```
 
 ## Creating a wallet
@@ -444,3 +458,19 @@ BIP32KeyPair keypair = BIP32KeyPair.fromTLV(cmdSet.exportKey("m/43'/60'/1581'/0'
 // At this point, the current active path would still be "m/44'/0'/0'/0/0"
 ```
 
+### Changing credentials
+
+All credentials of the Keycard can be changed (PIN, PUK, pairing password). Changing the pairing password does not
+invalidate existing pairings, but applies to the ones which can be created in the future. Changing credentials,
+requires user authentication.
+
+```java
+// Changes the user PIN
+cmdSet.changePIN("123456").checkOK();
+
+// Changes the PUK
+cmdSet.changePUK("123456123456").checkOK();
+
+// Changes the pairing password
+cmdSet.changePairingPassword("my pairing password").checkOK();
+```
\ No newline at end of file