add usage docs

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,13 +14,7 @@
 
 ### 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
 
@@ -34,20 +31,10 @@
       compile project(':react-native-status-keycard')
   	```
 
-#### 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
-
-
 ## 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/
   

docs/usage.md

@@ -0,0 +1,241 @@
+# Usage
+
+You need to import Keycard object to interact with the card:
+
+```javascript
+import { RNStatusKeycard as Keycard} from "react-native-status-keycard";
+```
+
+### Listen to keycard connect/disconnect events
+
+```javascript
+import DeviceEventEmitter from "react-native";
+
+// Listen to connect/disconnect events
+DeviceEventEmitter.addListener("keyCardOnConnected", () => console.log("keycard connected"));
+DeviceEventEmitter.addListener("keyCardOnDisconnected", () => console.log("keycard disconnected"));
+```
+
+### Errors
+
+As library uses Promises for method calls, use `.catch` to get the error object.
+
+Example:
+```javascript
+Keycard.getApplicationInfo().
+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
+Keycard.getApplicationInfo().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",
+"has-master-key?": false,
+"paired?": false,
+"initialized?": true}
+```
+
+## 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:
+```javascript
+{"pin": "123456",
+"puk": "123456123456",
+"password": "/xzPt+rEWVN3sMc5"}
+```
+
+### Pair 
+Pairs keycard to device:
+```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. 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
+{"wallet-address": "9726cbc67d170307dd80af6416ebe844e7b8eb1c",
+"whisper-address": "438e576b638bff08b2872dd708cf0240811d79af",
+"whisper-public-key": "04add221cb97dde8afbf3be27b0bfb3b6842071cb1052abfc3c34d45eba944dc10dcba5d4823fe69148ae17b12ed459237124365c2f46c2b46be9537ce6efa93c8",
+"whisper-private-key": "073d77b952b3b92ba66947df53d03b23bc4cc8cf10cbba1060fe25a569c8ee6b",
+"encryption-public-key": "04d36d64bea374b917bc097646cb4e81061c7b0ab0872207480b886e66fb52d53774e303e2aa07a1107776f312b94663566765a8a75cf0a92b0851017b28b356a1",
+"instance-uid": "21c0ce19aa9a26efc02fd32078c08527"}
+```
+
+`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 keys:
+```javascript
+{"encryption-public-key""04d36d64bea374b917bc097646cb4e81061c7b0ab0872207480b886e66fb52d53774e303e2aa07a1107776f312b94663566765a8a75cf0a92b0851017b28b356a1",
+"whisper-public-key""04add221cb97dde8afbf3be27b0bfb3b6842071cb1052abfc3c34d45eba944dc10dcba5d4823fe69148ae17b12ed459237124365c2f46c2b46be9537ce6efa93c8",
+"whisper-private-key""073d77b952b3b92ba66947df53d03b23bc4cc8cf10cbba1060fe25a569c8ee6b",
+"wallet-address""9726cbc67d170307dd80af6416ebe844e7b8eb1c"}
+```
+
+### 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. It consists of R,S and Recovery ID 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.