Add exportKeyWithPath() fn

Before this commit `Keycard.generateAndLoadKey` and
`Keyacrd.getKeys` methods returned wallet root key address and public
key in "address" and "public-key" fields correspondingly. This caused
discrepancy in the way how keys were used for on-device and keycard
accounts in Status app. For on-device accounts master key address
was used as account's deterministic id, when keycard accounts used
wallet root key address for this purpose.

README.md

@@ -1,5 +1,8 @@
 
-# react-native-status-keycard
+# React Native Status Keycard [![npm version](https://badge.fury.io/js/react-native-status-keycard.svg)](https://badge.fury.io/js/react-native-status-keycard)
+
+React Native library to interact with [Keycard](https://keycard.status.im/) using [Java SDK](https://github.com/status-im/status-keycard-java)
+
 
 ## Getting started
 
@@ -11,18 +14,12 @@
 
 ### Manual installation
 
-
-#### iOS
-
-1. In XCode, in the project navigator, right click `Libraries` ➜ `Add Files to [your project's name]`
-2. Go to `node_modules` ➜ `react-native-status-keycard` and add `RNStatusKeycard.xcodeproj`
-3. In XCode, in the project navigator, select your project. Add `libRNStatusKeycard.a` to your project's `Build Phases` ➜ `Link Binary With Libraries`
-4. Run your project (`Cmd+R`)<
+Android is the only platform supported by now.
 
 #### Android
 
-1. Open up `android/app/src/main/java/[...]/MainActivity.java`
-  - Add `import com.reactlibrary.RNStatusKeycardPackage;` to the imports at the top of the file
+1. Open up `android/app/src/main/java/[...]/MainApplication.java`
+  - Add `import im.status.ethereum.keycard.RNStatusKeycardPackage;` to the imports at the top of the file
   - Add `new RNStatusKeycardPackage()` to the list returned by the `getPackages()` method
 2. Append the following lines to `android/settings.gradle`:
   	```
@@ -33,21 +30,15 @@
   	```
       compile project(':react-native-status-keycard')
   	```
+4. Add `<uses-permission android:name="android.permission.NFC"/>` to `android/app/src/main/AndroidManifest.xml` to enable NFC permission.
 
-#### Windows
-[Read it! :D](https://github.com/ReactWindows/react-native)
-
-1. In Visual Studio add the `RNStatusKeycard.sln` in `node_modules/react-native-status-keycard/windows/RNStatusKeycard.sln` folder to their solution, reference from their app.
-2. Open up your `MainPage.cs` app
-  - Add `using Status.Keycard.RNStatusKeycard;` to the usings at the top of the file
-  - Add `new RNStatusKeycardPackage()` to the `List<IReactPackage>` returned by the `Packages` method
-
+5. Make sure `minSdkVersion` is 18 in `android/build.gradle`.
 
 ## Usage
-```javascript
-import RNStatusKeycard from 'react-native-status-keycard';
 
-// TODO: What to do with the module?
-RNStatusKeycard;
-```
+Take a look into [docs](./docs/usage.md)
+
+For more usage examples, please refer to https://github.com/status-im/status-react (assuming you can read Clojure)
+
+For Keycard API documention, please look into https://status.im/keycard_api/
   

android/build.gradle

@@ -40,5 +40,6 @@ repositories {
 dependencies {
     implementation 'com.facebook.react:react-native:+'
     implementation 'org.bouncycastle:bcprov-jdk15on:1.60'
-    implementation 'com.github.status-im.status-keycard-java:android:2.1.0'
+    implementation 'org.apache.commons:commons-lang3:3.9'
+    implementation 'com.github.status-im.status-keycard-java:android:2.2.1'
 }

android/src/main/java/im/status/ethereum/keycard/RNStatusKeycardModule.java

@@ -23,7 +23,7 @@ import im.status.keycard.io.APDUException;
 
 public class RNStatusKeycardModule extends ReactContextBaseJavaModule implements LifecycleEventListener {
     private static final String TAG = "StatusKeycard";
-    private static final String CAP_FILENAME = "keycard_v2.1.cap";
+    private static final String CAP_FILENAME = "keycard_v2.2.1.cap";
     private SmartCard smartCard;
     private final ReactApplicationContext reactContext;
 
@@ -148,13 +148,17 @@ public class RNStatusKeycardModule extends ReactContextBaseJavaModule implements
 
     @ReactMethod
     public void saveMnemonic(final String mnemonic, final String pairing, final String pin, final Promise promise) {
-        try {
-            smartCard.saveMnemonic(mnemonic, pairing, pin);
-            promise.resolve(true);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.saveMnemonic(mnemonic, pairing, pin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
@@ -173,25 +177,48 @@ public class RNStatusKeycardModule extends ReactContextBaseJavaModule implements
 
     @ReactMethod
     public void deriveKey(final String path, final String pairing, final String pin, final Promise promise) {
-        try {
-            smartCard.deriveKey(path, pairing, pin);
-            promise.resolve(path);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.deriveKey(path, pairing, pin);
+                    promise.resolve(path);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
     public void exportKey(final String pairing, final String pin, final Promise promise) {
-        try {
-            promise.resolve(smartCard.exportKey(pairing, pin));
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    promise.resolve(smartCard.exportKey(pairing, pin));
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
+    @ReactMethod
+    public void exportKeyWithPath(final String pairing, final String pin, final String path, final Promise promise) {
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    promise.resolve(smartCard.exportKeyWithPath(pairing, pin, path));
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
+    }
+
+
     @ReactMethod
     public void getKeys(final String pairing, final String pin, final Promise promise) {
         new Thread(new Runnable() {
@@ -220,6 +247,20 @@ public class RNStatusKeycardModule extends ReactContextBaseJavaModule implements
         }).start();
     }
 
+    @ReactMethod
+    public void signPinless(final String hash, final Promise promise) {
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    promise.resolve(smartCard.signPinless(hash));
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
+    }
+
     @ReactMethod
     public void installApplet(final Promise promise) {
         final ReactContext ctx = this.reactContext;
@@ -254,74 +295,127 @@ public class RNStatusKeycardModule extends ReactContextBaseJavaModule implements
                     Log.d(TAG, e.getMessage());
                     promise.reject(e);
                 }
-
             }
         }).start();
     }
 
     @ReactMethod
     public void verifyPin(final String pairing, final String pin, final Promise promise) {
-        try {
-            promise.resolve(smartCard.verifyPin(pairing, pin));
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    promise.resolve(smartCard.verifyPin(pairing, pin));
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
     public void changePin(final String pairing, final String currentPin, final String newPin, final Promise promise) {
-        try {
-            smartCard.changePin(pairing, currentPin, newPin);
-            promise.resolve(true);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.changePin(pairing, currentPin, newPin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
     public void unblockPin(final String pairing, final String puk, final String newPin, final Promise promise) {
-        try {
-            smartCard.unblockPin(pairing, puk, newPin);
-            promise.resolve(true);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.unblockPin(pairing, puk, newPin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
     public void unpair(final String pairing, final String pin, final Promise promise) {
-        try {
-            smartCard.unpair(pairing, pin);
-            promise.resolve(true);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.unpair(pairing, pin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
     public void delete(final Promise promise) {
-        try {
-            smartCard.delete();
-            promise.resolve(true);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.delete();
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
+    }
+
+    @ReactMethod
+    public void removeKey(final String pairing, final String pin, final Promise promise) {
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.removeKey(pairing, pin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
+    }
+
+    @ReactMethod
+    public void removeKeyWithUnpair(final String pairing, final String pin, final Promise promise) {
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.removeKeyWithUnpair(pairing, pin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
     @ReactMethod
     public void unpairAndDelete(final String pairing, final String pin, final Promise promise) {
-        try {
-            smartCard.unpairAndDelete(pairing, pin);
-            promise.resolve(true);
-        } catch (IOException | APDUException e) {
-            Log.d(TAG, e.getMessage());
-            promise.reject(e);
-        }
+        new Thread(new Runnable() {
+            public void run() {
+                try {
+                    smartCard.unpairAndDelete(pairing, pin);
+                    promise.resolve(true);
+                } catch (IOException | APDUException e) {
+                    Log.d(TAG, e.getMessage());
+                    promise.reject(e);
+                }
+            }
+        }).start();
     }
 
-}
+}

android/src/main/java/im/status/ethereum/keycard/SmartCard.java

@@ -31,6 +31,7 @@ import im.status.keycard.android.NFCCardManager;
 import im.status.keycard.applet.ApplicationStatus;
 import im.status.keycard.applet.BIP32KeyPair;
 import im.status.keycard.applet.Mnemonic;
+import im.status.keycard.applet.CashCommandSet;
 import im.status.keycard.applet.KeycardCommandSet;
 import im.status.keycard.applet.Pairing;
 import im.status.keycard.applet.ApplicationInfo;
@@ -48,6 +49,8 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
     private static final String TAG = "SmartCard";
     private Boolean started = false;
 
+    private static final String MASTER_PATH = "m";
+    private static final String ROOT_PATH = "m/44'/60'/0'/0";
     private static final String WALLET_PATH = "m/44'/60'/0'/0/0";
     private static final String WHISPER_PATH = "m/43'/60'/1581'/0'/0";
     private static final String ENCRYPTION_PATH = "m/43'/60'/1581'/1'/0";
@@ -151,6 +154,7 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         // First thing to do is selecting the applet on the card.
         ApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData());
         Log.i(TAG, "Instance UID: " + Hex.toHexString(info.getInstanceUID()));
+        Log.i(TAG, "Key UID: " + Hex.toHexString(info.getKeyUID()));
         Log.i(TAG, "Secure channel public key: " + Hex.toHexString(info.getSecureChannelPubKey()));
         Log.i(TAG, "Application version: " + info.getAppVersionString());
         Log.i(TAG, "Free pairing slots: " + info.getFreePairingSlots());
@@ -217,16 +221,11 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
 
         if (info.isInitializedCard()) {
             Log.i(TAG, "Instance UID: " + Hex.toHexString(info.getInstanceUID()));
+            Log.i(TAG, "Key UID: " + Hex.toHexString(info.getKeyUID()));
             Log.i(TAG, "Secure channel public key: " + Hex.toHexString(info.getSecureChannelPubKey()));
             Log.i(TAG, "Application version: " + info.getAppVersionString());
             Log.i(TAG, "Free pairing slots: " + info.getFreePairingSlots());
 
-            if (info.hasMasterKey()) {
-                Log.i(TAG, "Key UID: " + Hex.toHexString(info.getKeyUID()));
-            } else {
-                Log.i(TAG, "The card has no master key");
-            }
-
             Boolean isPaired = false;
 
             if (pairingBase64.length() > 0) {
@@ -253,6 +252,7 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
             cardInfo.putBoolean("has-master-key?", info.hasMasterKey());
             cardInfo.putBoolean("paired?", isPaired);
             cardInfo.putString("instance-uid", Hex.toHexString(info.getInstanceUID()));
+            cardInfo.putString("key-uid", Hex.toHexString(info.getKeyUID()));
             cardInfo.putString("secure-channel-pub-key", Hex.toHexString(info.getSecureChannelPubKey()));
             cardInfo.putString("app-version", info.getAppVersionString());
             cardInfo.putInt("free-pairing-slots", info.getFreePairingSlots());
@@ -299,6 +299,24 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         return Hex.toHexString(key);
     }
 
+    public String exportKeyWithPath(final String pairingBase64, final String pin, final String path) throws IOException, APDUException {
+        KeycardCommandSet cmdSet = new KeycardCommandSet(this.cardChannel);
+        cmdSet.select().checkOK();
+
+        Pairing pairing = new Pairing(pairingBase64);
+        cmdSet.setPairing(pairing);
+
+        cmdSet.autoOpenSecureChannel();
+        Log.i(TAG, "secure channel opened");
+
+        cmdSet.verifyPIN(pin).checkOK();
+        Log.i(TAG, "pin verified");
+
+        byte[] key = BIP32KeyPair.fromTLV(cmdSet.exportKey(path, false, true).checkOK().getData()).getPublicKey();
+
+        return Hex.toHexString(key);
+    }
+
     public WritableMap getKeys(final String pairingBase64, final String pin) throws IOException, APDUException {
         KeycardCommandSet cmdSet = new KeycardCommandSet(this.cardChannel);
         cmdSet.select().checkOK();
@@ -312,6 +330,12 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         cmdSet.verifyPIN(pin).checkOK();
         Log.i(TAG, "pin verified");
 
+        byte[] tlvMaster = cmdSet.exportKey(MASTER_PATH, true, true).checkOK().getData();
+        BIP32KeyPair masterPair = BIP32KeyPair.fromTLV(tlvMaster);
+
+        byte[] tlvRoot = cmdSet.exportKey(ROOT_PATH, true, true).checkOK().getData();
+        BIP32KeyPair keyPair = BIP32KeyPair.fromTLV(tlvRoot);
+
         byte[] tlv = cmdSet.exportKey(WALLET_PATH, true, true).checkOK().getData();
         BIP32KeyPair walletKeyPair = BIP32KeyPair.fromTLV(tlv);
 
@@ -321,11 +345,21 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         byte[] tlv3 = cmdSet.exportKey(ENCRYPTION_PATH, false, false).checkOK().getData();
         BIP32KeyPair encryptionKeyPair = BIP32KeyPair.fromTLV(tlv3);
 
+        ApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData());
+
         WritableMap data = Arguments.createMap();
+        data.putString("address", Hex.toHexString(masterPair.toEthereumAddress()));
+        data.putString("public-key", Hex.toHexString(masterPair.getPublicKey()));
+        data.putString("wallet-root-address", Hex.toHexString(keyPair.toEthereumAddress()));
+        data.putString("wallet-root-public-key", Hex.toHexString(keyPair.getPublicKey()));
         data.putString("wallet-address", Hex.toHexString(walletKeyPair.toEthereumAddress()));
+        data.putString("wallet-public-key", Hex.toHexString(walletKeyPair.getPublicKey()));
+        data.putString("whisper-address", Hex.toHexString(whisperKeyPair.toEthereumAddress()));
         data.putString("whisper-public-key", Hex.toHexString(whisperKeyPair.getPublicKey()));
         data.putString("whisper-private-key", Hex.toHexString(whisperKeyPair.getPrivateKey()));
         data.putString("encryption-public-key", Hex.toHexString(encryptionKeyPair.getPublicKey()));
+        data.putString("instance-uid", Hex.toHexString(info.getInstanceUID()));
+        data.putString("key-uid", Hex.toHexString(info.getKeyUID()));
 
         return data;
     }
@@ -349,6 +383,12 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         cmdSet.loadKey(keyPair);
         log("keypair loaded to card");
 
+        cmdSet.deriveKey(ROOT_PATH).checkOK();
+        Log.i(TAG, "Derived " + ROOT_PATH);
+
+        byte[] tlvRoot = cmdSet.exportCurrentKey(true).checkOK().getData();
+        BIP32KeyPair rootKeyPair = BIP32KeyPair.fromTLV(tlvRoot);
+
         cmdSet.deriveKey(WALLET_PATH).checkOK();
         Log.i(TAG, "Derived " + WALLET_PATH);
 
@@ -370,12 +410,18 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         ApplicationInfo info = new ApplicationInfo(cmdSet.select().checkOK().getData());
 
         WritableMap data = Arguments.createMap();
+        data.putString("address", Hex.toHexString(keyPair.toEthereumAddress()));
+        data.putString("public-key", Hex.toHexString(keyPair.getPublicKey()));
+        data.putString("wallet-root-address", Hex.toHexString(rootKeyPair.toEthereumAddress()));
+        data.putString("wallet-root-public-key", Hex.toHexString(rootKeyPair.getPublicKey()));
         data.putString("wallet-address", Hex.toHexString(walletKeyPair.toEthereumAddress()));
+        data.putString("wallet-public-key", Hex.toHexString(walletKeyPair.getPublicKey()));
         data.putString("whisper-address", Hex.toHexString(whisperKeyPair.toEthereumAddress()));
         data.putString("whisper-public-key", Hex.toHexString(whisperKeyPair.getPublicKey()));
         data.putString("whisper-private-key", Hex.toHexString(whisperKeyPair.getPrivateKey()));
         data.putString("encryption-public-key", Hex.toHexString(encryptionKeyPair.getPublicKey()));
         data.putString("instance-uid", Hex.toHexString(info.getInstanceUID()));
+        data.putString("key-uid", Hex.toHexString(info.getKeyUID()));
 
         return data;
     }
@@ -469,6 +515,28 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         Log.i(TAG, "instance and package deleted");
     }
 
+    public void removeKey(final String pairingBase64, final String pin) throws IOException, APDUException {
+        KeycardCommandSet cmdSet = new KeycardCommandSet(this.cardChannel);
+        cmdSet.select().checkOK();
+
+        Pairing pairing = new Pairing(pairingBase64);
+        cmdSet.setPairing(pairing);
+
+        cmdSet.autoOpenSecureChannel();
+        Log.i(TAG, "secure channel opened");
+
+        cmdSet.verifyPIN(pin).checkOK();
+        Log.i(TAG, "pin verified");
+
+        cmdSet.removeKey();
+        Log.i(TAG, "key removed");
+    }
+
+    public void removeKeyWithUnpair(final String pairingBase64, final String pin) throws IOException, APDUException {
+        removeKey(pairingBase64, pin);
+        unpair(pairingBase64, pin);
+    }
+
     public void unpairAndDelete(final String pairingBase64, final String pin) throws IOException, APDUException {
         unpair(pairingBase64, pin);
         delete();
@@ -507,4 +575,27 @@ public class SmartCard extends BroadcastReceiver implements CardListener {
         return sig;
     }
 
+    public String signPinless(final String message) throws IOException, APDUException {
+        CashCommandSet cmdSet = new CashCommandSet(this.cardChannel);
+        cmdSet.select().checkOK();
+
+        byte[] hash = Hex.decode(message);
+        RecoverableSignature signature = new RecoverableSignature(hash, cmdSet.sign(hash).checkOK().getData());
+
+        Log.i(TAG, "Signed hash: " + Hex.toHexString(hash));
+        Log.i(TAG, "Recovery ID: " + signature.getRecId());
+        Log.i(TAG, "R: " + Hex.toHexString(signature.getR()));
+        Log.i(TAG, "S: " + Hex.toHexString(signature.getS()));
+
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+
+        out.write(signature.getR());
+        out.write(signature.getS());
+        out.write(signature.getRecId());
+
+        String sig = Hex.toHexString(out.toByteArray());
+        Log.i(TAG, "Signature: " + sig);
+
+        return sig;
+    }
 }

android/src/main/java/im/status/ethereum/keycard/SmartCardSecrets.java

@@ -2,6 +2,9 @@ package im.status.ethereum.keycard;
 
 import android.support.annotation.NonNull;
 import android.util.Base64;
+
+import org.apache.commons.lang3.RandomStringUtils;
+
 import static android.util.Base64.NO_PADDING;
 import static android.util.Base64.NO_WRAP;
 
@@ -30,7 +33,7 @@ public class SmartCardSecrets {
 
     @NonNull
     public static SmartCardSecrets generate(final String userPin) throws NoSuchAlgorithmException, InvalidKeySpecException {
-        String pairingPassword = randomToken(12);
+        String pairingPassword = randomToken(16);
         long pinNumber = randomLong(PIN_BOUND);
         long pukNumber = randomLong(PUK_BOUND);
 
@@ -64,7 +67,9 @@ public class SmartCardSecrets {
     }
 
     public static String randomToken(int length) {
-        return Base64.encodeToString(randomBytes(length), (NO_PADDING | NO_WRAP));
+        char[] possibleCharacters = "23456789ABCDEFGHJKLMNPRSTUVWXYZabcdefghijkmnopqrstuvwxyz".toCharArray();
+        String randomStr = RandomStringUtils.random(length, 0, possibleCharacters.length-1, false, false, possibleCharacters, new SecureRandom());
+        return randomStr;
     }
 
     public static byte[] randomBytes(int length) {

docs/usage.md

@@ -0,0 +1,286 @@
+# Usage
+
+You need to import Keycard object to interact with the card:
+
+```javascript
+import Keycard from "react-native-status-keycard";
+```
+
+### Listen to keycard connect/disconnect events
+
+```javascript
+import { DeviceEventEmitter } from 'react-native';
+
+// Listen to connect/disconnect events
+componentDidMount () {
+  DeviceEventEmitter.addListener("keyCardOnConnected", () => console.log("keycard connected"));
+  DeviceEventEmitter.addListener("keyCardOnDisconnected", () => console.log("keycard disconnected"));
+}
+```
+
+### Errors
+
+Library uses Promises for method calls, use `.catch` to get the error object.
+
+Example:
+```javascript
+Keycard.init("123456").then(info => console.log(info)).catch(error => console.log(error))
+```
+
+Error object example:
+```javascript
+{"code": "EUNSPECIFIED",
+"error": "Tag was lost."}
+```
+
+### Check NFC support on device
+```javascript
+// Check if NFC is supported by device
+Keycard.nfcIsSupported().then(isSupported => isSupported ? console.log("NFC is supported") : console.log("NFC is not supported"));
+
+// Check if NFC is enabled on device
+Keycard.nfcIsEnabled().then(isEnabled => isEnabled ? console.log("NFC is enabled") : console.log("NFC is not enabled"));
+
+// Open device NFC settings
+Keycard.openNfcSettings();
+```
+
+### Get keycard information
+```javascript
+// If keycard was not paired before, use empty string as pairing
+Keycard.getApplicationInfo("").then(info => console.log(info));
+
+// If keycard is paired, use pairing key
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+Keycard.getApplicationInfo(pairing).then(info => console.log(info));
+
+```
+
+Returns object like this:
+```javascript
+{"free-pairing-slots": 2,
+"app-version": "2.1",
+"secure-channel-pub-key": "042bd559a6eb5843491f79150ccba6bcc04c5b6691079f7c7a0e2eea659960db1df67079b27fdf5df56a1092029a157c0dce7000af4d7c4c1131421623c0150d1c",
+"instance-uid": "21c0ce19aa9a26efc02fd32078c08527",
+"key-uid": "a88d46499e5690c6ad637e243e83cf51be3e2c67e48324b2b2def3e6a0492576",
+"has-master-key?": false,
+"paired?": false,
+"initialized?": true}
+```
+
+`instance-uid` The instance UID of the applet. This ID never changes for the lifetime of the applet.
+
+`key-uid` The UID of the master key on this card. Changes every time a different master key is stored. It has zero length if no key is on the card.
+
+## Setup keycard
+
+### Initialize the card
+```javascript
+const pin = "123456";
+Keycard.init(pin).then(secrets => console.log(secrets));
+```
+
+`secrets` object contains PIN, PUK and Pairing password. You will need password to pair the card to device.
+```javascript
+{"pin": "123456",
+"puk": "123456123456",
+"password": "/xzPt+rEWVN3sMc5"}
+```
+
+### Pair 
+Pairs keycard to device.
+
+Use password you get after keycard initialization (using `init`):
+
+```javascript
+const password = "/xzPt+rEWVN3sMc5";
+Keycard.pair(password).then(pairing => console.log(pairing));
+```
+
+`pairing` object contains pairing key as base64 string. 
+You will need pairing key to open secure channel for most keycard operations. More info on pairing https://status.im/keycard_api/sdk_securechannel.html
+
+### Generate mnemonic phrase
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo"; 
+const words = "abandon\nability\nable\nabout\n..." // bip 39 words separated by new line
+Keycard.generateMnemonic(pairing, words).then(mnemonic => console.log(mnemonic));
+```
+`mnemonic` is a string of 12 words separated by space:
+```javascript
+"sure more foil soon pretty guilt run rail biology fine obey outside"
+```
+
+BIP39 words can be found here: https://raw.githubusercontent.com/bitcoin/bips/master/bip-0039/english.txt
+
+### Generate and load master key
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+const mnemonic = "sure more foil soon pretty guilt run rail biology fine obey outside";
+
+Keycard.generateAndLoadKey(mnemonic, pairing, pin).then(data => console.log(data));
+```
+
+`data` object returned:
+```javascript
+{"address": "a89a57f4d3241e6a123ea332241d6f03790075b4",
+"public-key": "04cccc3998d0e0b8d56b64fad4d1f025914b8cb72558810c74dd34454fcd6907f6f7429a0726dceec9b93c9060103ff8b2e7daa1cb9a4dd62b7ae1ba2232709555",
+"wallet-root-address": "b19a57f4d3241e6a123ea332241d6f03790075b4",
+"wallet-root-public-key": "0427cc3998d0e0b8d56b64fad4d1f025914b8cb72558810c74dd34454fcd6907f6f7429a0726dceec9b93c9060103ff8b2e7daa1cb9a4dd62b7ae1ba2232709555",
+"wallet-address": "9726cbc67d170307dd80af6416ebe844e7b8eb1c",
+"wallet-public-key": "04065670509d295cb8330e02a688eafe83dbbb317486062482725ba1036dba396d635e91afd9a9e7087c0dfeaccf30d2004d092ed250d62b5c75f8bb4c9326d409",
+"whisper-address": "438e576b638bff08b2872dd708cf0240811d79af",
+"whisper-public-key": "04add221cb97dde8afbf3be27b0bfb3b6842071cb1052abfc3c34d45eba944dc10dcba5d4823fe69148ae17b12ed459237124365c2f46c2b46be9537ce6efa93c8",
+"whisper-private-key": "073d77b952b3b92ba66947df53d03b23bc4cc8cf10cbba1060fe25a569c8ee6b",
+"encryption-public-key": "04d36d64bea374b917bc097646cb4e81061c7b0ab0872207480b886e66fb52d53774e303e2aa07a1107776f312b94663566765a8a75cf0a92b0851017b28b356a1",
+"instance-uid": "21c0ce19aa9a26efc02fd32078c08527",
+"key-uid":"a88d46499e5690c6ad637e243e83cf51be3e2c67e48324b2b2def3e6a0492576"}
+```
+
+`address` is an address of master key `m`
+
+`public-key` is a public key of master key `m`
+
+`wallet-root-address` is an address of root key `m/44'/60'/0'/0`
+
+`wallet-root-public-key` is public key of root key `m/44'/60'/0'/0`
+
+`wallet-address` is ethereum address of key with derivation path `m/44'/60'/0'/0/0`
+
+`whisper-address` is ethereum address of key with derivation path `m/43'/60'/1581'/0'/0`
+
+`encryption-public-key` is public key with derivation path `m/43'/60'/1581'/1'/0`
+
+More info about key derivation: https://status.im/keycard_api/sdk_derivation_sign.html
+
+### Get keys from keycard
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+
+Keycard.getKeys(pairing, pin).then(data => console.log(data));
+```
+
+`data` object contains:
+```javascript
+{"address": "a89a57f4d3241e6a123ea332241d6f03790075b4",
+"public-key": "04cccc3998d0e0b8d56b64fad4d1f025914b8cb72558810c74dd34454fcd6907f6f7429a0726dceec9b93c9060103ff8b2e7daa1cb9a4dd62b7ae1ba2232709555",
+"wallet-root-address": "b19a57f4d3241e6a123ea332241d6f03790075b4",
+"wallet-root-public-key": "0427cc3998d0e0b8d56b64fad4d1f025914b8cb72558810c74dd34454fcd6907f6f7429a0726dceec9b93c9060103ff8b2e7daa1cb9a4dd62b7ae1ba2232709555",
+"wallet-address": "9726cbc67d170307dd80af6416ebe844e7b8eb1c",
+"wallet-public-key": "04065670509d295cb8330e02a688eafe83dbbb317486062482725ba1036dba396d635e91afd9a9e7087c0dfeaccf30d2004d092ed250d62b5c75f8bb4c9326d409",
+"whisper-address": "438e576b638bff08b2872dd708cf0240811d79af",
+"whisper-public-key": "04add221cb97dde8afbf3be27b0bfb3b6842071cb1052abfc3c34d45eba944dc10dcba5d4823fe69148ae17b12ed459237124365c2f46c2b46be9537ce6efa93c8",
+"whisper-private-key": "073d77b952b3b92ba66947df53d03b23bc4cc8cf10cbba1060fe25a569c8ee6b",
+"encryption-public-key": "04d36d64bea374b917bc097646cb4e81061c7b0ab0872207480b886e66fb52d53774e303e2aa07a1107776f312b94663566765a8a75cf0a92b0851017b28b356a1",
+"instance-uid": "21c0ce19aa9a26efc02fd32078c08527",
+"key-uid":"a88d46499e5690c6ad637e243e83cf51be3e2c67e48324b2b2def3e6a0492576"}
+```
+
+Response is identical to `generateAndLoadKey`.
+Please refer to `generateAndLoadKey` response for detailed description.
+
+### Sign
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+const hash = "d81bbffb92157b72ceae3da72eb8224976ba42a49621822789edb0735a0e0395";
+
+Keycard.sign(pairing, pin, hash).then(sig => console.log(sig));
+```
+
+Signature string returned. Example: ` d684afb4ec9ce59f2d112a9c9400bd04f5a5b2518b251dba4ad135448f2e75367c2ea6412893d8001ed9c9efeb7c7d37bc11f7dfcf27c4818cf0861da199de1900`
+
+Signature consists of R, S and Recovery ID values concatenated (R+S+V). 
+For example:
+
+R: `79ef184db3150519a9719a38a7939fae39bbea088758745482cabe40127c7efb`
+
+S: `674932db2a7a5ae4b1d9d228b3542dba83ac9ac62524a45dd984e9650ceaa736`
+
+Recovery ID: `0`
+
+Would produce signature: `d684afb4ec9ce59f2d112a9c9400bd04f5a5b2518b251dba4ad135448f2e75367c2ea6412893d8001ed9c9efeb7c7d37bc11f7dfcf27c4818cf0861da199de1900`
+
+More info about signing: https://status.im/keycard_api/sdk_derivation_sign.html
+
+### Derive key
+Changes derivation path:
+```javascript
+const path = "m/44'/60'/0'/0/0"
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+
+Keycard.deriveKey(path, pairing, pin).then(path => console.log("path changed to " + path));
+```
+More information on key derivation: https://status.im/keycard_api/sdk_derivation_sign.html
+
+### Remove key
+Removes master key from keycard:
+
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+
+Keycard.removeKey(pairing, pin).then(() => console.log("key removed"));
+```
+
+### Unpair
+
+Unpairs keycard from current device:
+
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+
+Keycard.unpair(pairing, pin).then(() => console.log("keycard unpaired"));
+```
+
+### Change PIN
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const currentPin = "123456";
+const newPin = "111111";
+
+Keycard.removeKey(pairing, currentPin, newPin).then(() => console.log("pin changed"));
+```
+
+### Unblock PIN
+When wrong PIN is entered 3 times keycard becomes blocked. You can unblock it with PUK code:
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const puk = "123456123456";
+const newPin = "111111";
+
+Keycard.removeKey(pairing, puk, newPin).then(() => console.log("pin unblocked"));
+```
+
+### Verify PIN
+Verifies PIN is valid:
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const pin = "123456";
+
+Keycard.removeKey(pairing, pin).then(() => console.log("pin is valid"));
+```
+
+### Delete keycard
+Deletes everything from keycard including key and the applet. Dangerous operation for advanced users only. You will need to install applet again to interact with keycard.
+
+```javascript
+const pairing = "AFFdkP01GywuaJRQkGDq+OyPHBE9nECEDDCfXhpfaxlo";
+const puk = "123456123456";
+const newPin = "111111";
+
+Keycard.removeKey(pairing, puk, newPin).then(() => console.log("pin unblocked"));
+```
+
+### Install applet
+Keycard usually comes with installed applet. But if you have empty keycard without the applet, you can install applet with:
+```javascript
+Keycard.installApplet().then(() => console.log("applet installed"));
+```
+
+### Keycard CLI
+You can also interact with keycard (installing and removing applet, getting card info, etc) using [keycard cli](https://github.com/status-im/keycard-cli). You'll need a USB reader for that.

package.json

@@ -1,7 +1,7 @@
-
 {
   "name": "react-native-status-keycard",
-  "version": "2.5.0",
+  "homepage": "https://keycard.status.im/",
+  "version": "2.5.16",
   "description": "React Native library to interact with Status Keycard using NFC connection (Android only)",
   "main": "index.js",
   "scripts": {