Commit 7219b17c00eaf1dd338937ec9a96d02d4dfe032e
better documentation
Dominic Tarr committed on 10/3/2016, 8:52:38 PMParent: ecdbcc61feda683e4cd558856223dd6d5c876b64
Files changed
| README.md | changed |
| README.md | ||
|---|---|---|
| @@ -1,55 +1,83 @@ | ||
| 1 | 1 … | # SSB-Keys |
| 2 | 2 … | |
| 3 | -A common module for secure-scuttlebutt projects, provides an API to create or load elliptic-curve keypairs and to execute related crypto operations. | |
| 3 … | +supplies key loading and other cryptographic functions needed in secure-scuttlebutt apps. | |
| 4 | 4 … | |
| 5 | 5 … | ```js |
| 6 | 6 … | var ssbkeys = require('ssb-keys') |
| 7 | 7 … | |
| 8 | -ssbkeys.create(path, function(err, k) { | |
| 9 | - console.log(k) /* => { | |
| 10 | - id: String, | |
| 11 | - public: String, | |
| 12 | - private: String | |
| 13 | - }*/ | |
| 14 | -}) | |
| 15 | - | |
| 16 | -ssbkeys.load(path, function(err, k) { | |
| 17 | - console.log(k) /* => { | |
| 18 | - id: String, | |
| 19 | - public: String, | |
| 20 | - private: String | |
| 21 | - }*/ | |
| 22 | -}) | |
| 23 | - | |
| 24 | -var k = ssbkeys.createSync(path) | |
| 25 | -console.log(k) /* => { | |
| 8 … | +//usually, load keys like this | |
| 9 … | +var keys = ssbkeys.createOrLoadSync(filename) | |
| 10 … | +/* => { | |
| 26 | 11 … | id: String, |
| 27 | 12 … | public: String, |
| 28 | 13 … | private: String |
| 29 | 14 … | }*/ |
| 30 | 15 … | |
| 31 | -var k = ssbkeys.loadSync(path) | |
| 32 | -console.log(k) /* => { | |
| 16 … | +//but for testing, .generate() is useful. | |
| 17 … | +var keys = ssbkeys.generate() | |
| 18 … | +/* => { | |
| 33 | 19 … | id: String, |
| 34 | 20 … | public: String, |
| 35 | 21 … | private: String |
| 36 | 22 … | }*/ |
| 37 | 23 … | |
| 38 | -var k = ssbkeys.generate() | |
| 39 | -console.log(k) /* => { | |
| 40 | - id: String, | |
| 41 | - public: String, | |
| 42 | - private: String | |
| 43 | -}*/ | |
| 44 | 24 … | |
| 45 | -var hash = ssbkeys.hash(new Buffer('deadbeef', 'hex')) | |
| 46 | -var sig = ssbkeys.sign(k, hash) | |
| 47 | -ssbkeys.verify(k.public, sig, hash) // => true | |
| 25 … | +//hmac_key is a fixed value that applies to _THIS_ signature use, see below. | |
| 48 | 26 … | |
| 49 | -var obj = ssbkeys.signObj(k, { foo: 'bar' }) | |
| 27 … | +var obj = ssbkeys.signObj(k, hmac_key, { foo: 'bar' }) | |
| 50 | 28 … | console.log(obj) /* => { |
| 51 | 29 … | foo: 'bar', |
| 52 | 30 … | signature: ... |
| 53 | 31 … | } */ |
| 54 | -ssbkeys.verifyObj(k, obj) // => true | |
| 32 … | +ssbkeys.verifyObj(k, hmac_key, obj) // => true | |
| 55 | 33 … | ``` |
| 34 … | + | |
| 35 … | +## api | |
| 36 … | + | |
| 37 … | +### loadOrCreateSync (filename) | |
| 38 … | + | |
| 39 … | +Load a file containing the your private key. the file will also | |
| 40 … | +contain a comment with a warning about keeping the file secret. | |
| 41 … | + | |
| 42 … | +Works in the browser, or stores the keys is localStorage in the browser. | |
| 43 … | +(web apps should be hosted a secure way, for example [web-bootloader](https://github.com/dominictarr/web-bootloader)) | |
| 44 … | + | |
| 45 … | +If the file does not exist it will be created. there is also | |
| 46 … | +variations and parts `loadOrCreate` (async), `load`, `create` | |
| 47 … | +`createSync` `loadSync`. But since you only need to load once, | |
| 48 … | +using the combined function is easiest. | |
| 49 … | + | |
| 50 … | +### generate(curve, seed) | |
| 51 … | + | |
| 52 … | +generate a key, with optional seed. | |
| 53 … | +curve defaults to `ed25519` (and no other type is currently supported) | |
| 54 … | +seed should be a 32 byte buffer. | |
| 55 … | + | |
| 56 … | +### signObj(keys, hmac_key?, obj) | |
| 57 … | + | |
| 58 … | +signs a javascript object, and then adds a signature property to it. | |
| 59 … | + | |
| 60 … | +If `hmac_key` is provided, the object is hmaced before signing, | |
| 61 … | +which means it cannot be verified without the correct `hmac_key`. | |
| 62 … | +If each way that signatures are used in your application use a different | |
| 63 … | +hmac key, it means that a signature intended for one use cannot be reused in another | |
| 64 … | +(chosen protocol attack) | |
| 65 … | + | |
| 66 … | +### verifyObj(keys, hmac_key?, obj) | |
| 67 … | + | |
| 68 … | +verify a signed object. `hmac_key` must be the same value as passed to `signObj`. | |
| 69 … | + | |
| 70 … | +### box(msg, recipients) | |
| 71 … | + | |
| 72 … | +encrypt a message to many recipients. msg will be JSON encoded, then encrypted | |
| 73 … | +with [private-box](https://github.com/auditdrivencrypto/private-box) | |
| 74 … | + | |
| 75 … | +### unbox (boxed, keys) | |
| 76 … | + | |
| 77 … | +decrypt a message encrypted with `box`. If the `boxed` successfully decrypted, | |
| 78 … | +the parsed JSON is returned, if not, `undefined` is returned. | |
| 79 … | + | |
| 80 … | +### LICENSE | |
| 81 … | + | |
| 82 … | +MIT | |
| 83 … | + | |
Built with git-ssb-web