README.md (5070B)
1 # up8-ticket 2 3 [](http://travis-ci.org/urbit/up8-ticket) 4 [](https://opensource.org/licenses/MIT) 5 [](https://www.npmjs.com/package/up8-ticket) 6 7 Securely generate [UP8][up8p]-compatible, `@q`-encoded master tickets. Split 8 and combine tickets via a k/n Shamir's Secret Sharing scheme. 9 10 If you plan on generating a master ticket for a galaxy wallet, for example, you 11 might want to use `gen_ticket_drbg(384)` to generate the ticket, and then 12 `shard(.., 5, 3)` to split it into five shares (any three of which can be used 13 to recover it). 14 15 ## Install 16 17 Grab it from npm like so: 18 19 ``` 20 npm install up8-ticket 21 ``` 22 23 To include in your node project, use: 24 25 ``` javascript 26 const up8 = require('up8-ticket') 27 ``` 28 29 To use in the browser, you can use e.g. [rollup][roll] and the 30 [rollup-plugin-node-resolve][rpnr] plugin, and specify the following in your 31 `rollup.config.js` or similar: 32 33 ``` javascript 34 plugins: [ 35 .., 36 resolve({ 37 browser: true, 38 }), 39 .. 40 ] 41 ``` 42 43 ## Examples 44 45 Boot a node repl with async/await support and require the library like so: 46 47 ``` 48 $ node --experimental-repl-await 49 Welcome to Node.js v12.18.3. 50 Type ".help" for more information. 51 > const up8 = require('up8-ticket') 52 ``` 53 54 ### gen\_ticket\_simple 55 56 Generate a 256-bit master ticket via a simple CSPRNG (`crypto` or 57 `window.crypto`): 58 59 ``` 60 > up8.gen_ticket_simple(256) 61 '~mactug-digbyn-malnyr-tobset-solfyr-dozner-dolpen-barsum-locfur-pagduc-danseb-timlug-savwyn-latmug-disdyr-laddeg' 62 ``` 63 64 You can add your own entropy (generated elsewhere) by passing it in the second 65 argument as a Buffer. It will simply be XOR'd with the random bytes produced 66 internally: 67 68 ``` 69 > up8.gen_ticket_simple(256, Buffer.from("a very random string")) 70 '~donryd-mallur-wanrex-fidrex-nidwyt-dildul-padryd-talfen-panneb-nocbep-norwep-mispel-ralryc-fiddun-tomsup-toltex' 71 ``` 72 73 ### gen\_ticket\_more 74 75 Do the same thing, but also use [more-entropy][ment] to produce additional 76 entropy when generating the ticket. Note that it returns a Promise (and takes 77 a little longer): 78 79 ``` 80 > await up8.gen_ticket_more(256) 81 '~morten-davnys-ronpes-hidtyd-pittev-donsug-fonpel-sornet-wacmeb-harbyl-monduc-linmur-racled-namdec-tildul-palmyn' 82 ``` 83 84 You can similarly pass your own entropy in as an additional Buffer here: 85 86 ``` 87 > let ticket = await up8.gen_ticket_more(256, Buffer.from('muh entropy')) 88 '~rivmer-ticnyd-mirfet-rolbyt-tarlus-ricrun-fitmec-losrul-barhep-misfet-pidfen-foshep-ronrem-natlyx-tarlet-sipdeb' 89 ``` 90 91 ### gen\_ticket\_drbg 92 93 Do the same thing, but use a HMAC-DRBG function to combine the entropy produced 94 by the underlying CSPRNG and more-entropy. Like `gen_ticket_more`, it returns 95 a Promise, and takes longer. 96 97 Note that you must use at least 192 bits of entropy for this method. 98 99 ``` 100 > await up8.gen_ticket_drbg(256) 101 '~morten-davnys-ronpes-hidtyd-pittev-donsug-fonpel-sornet-wacmeb-harbyl-monduc-linmur-racled-namdec-tildul-palmyn' 102 ``` 103 104 As with the other functions, you can pass your own entropy in as an additional 105 Buffer: 106 107 ``` 108 > let ticket = await up8.gen_ticket_drbg(384, Buffer.from('a personalization string')) 109 '~siller-hopryc-ripfyn-laglec-linpur-mogpun-poldux-bicmul-radnum-dapnup-monnub-dilwex-pacrym-samrup-ragryc-samdyt-timdys-hartul-lonrun-posmev-molrum-miclur-doznus-fasnut' 110 ``` 111 112 ### shard 113 114 Split a ticket into 'shards' using a k/n Shamir's Secret Sharing scheme. 115 Specify the number of shards to create and the number of shards required to 116 reassemble the original ticket, along with the ticket itself: 117 118 ``` 119 > let ticket = await up8.gen_ticket_drbg(384) 120 > let shards = up8.shard(ticket, 3, 2) 121 > shards 122 [ 123 '~fidnec-topmud-pansul-lacbex-pinlet-finset-sonnyl-dovlud-sibdys-firtyd-walbep-ronlex-harmul-ligmeg-firryg-pidruc-masnup-havlud-tiplup-filrys-walsul-wicrum-narsem-mopdux-hilnev-raglun-doztep-picwes-dotten-micnyr-difwyt-donlys-lorref', 124 '~fidbud-rabtel-hapwyn-sander-napwyl-hosnys-savrud-hobsyl-silmev-lonfen-darlup-sopper-mitled-radpeg-diswen-laslun-toglud-sonsun-fopfex-docwyd-botneb-tilfur-rovhes-nollep-hatwer-nimpun-ladmel-borpun-bollep-finluc-noprun-hopmun-dovnul', 125 '~fidwes-witdur-nilbet-dolmug-pitpen-bacpyx-talrut-hanren-soltul-micdev-havneb-mildef-dilnec-bosdes-todsud-dopnex-rittyc-taplur-labrux-mogmun-togpeg-lagnel-tonweb-pidtyd-sablyn-sibsyx-linfex-lapteg-nolber-dovwel-nibteg-molsyd-macpec' 126 ] 127 ``` 128 129 ### combine 130 131 Combine shards created via `shard`. Pass in at least the required number of 132 shards as an array, with elements in any order: 133 134 ``` 135 > up8.combine(shards.slice(0, 2)) === ticket 136 true 137 > up8.combine(shards.slice(1, 3)) === ticket 138 true 139 > up8.combine([shards[0], shards[2]]) === ticket 140 true 141 > up8.combine(shards) === ticket 142 true 143 ``` 144 145 [wgen]: https://github.com/urbit/urbit-wallet-generator 146 [up8p]: https://github.com/urbit/proposals/blob/master/008-urbit-hd-wallet.md 147 [roll]: https://rollupjs.org/guide/en 148 [rpnr]: https://github.com/rollup/rollup-plugin-node-resolve 149 [ment]: https://www.npmjs.com/package/more-entropy