Skip to content

Commit ddc9583

Browse files
dingoskydingosky
committed
Add convenience functions
1 parent fd2bba4 commit ddc9583

File tree

5 files changed

+258
-161
lines changed

5 files changed

+258
-161
lines changed

‎README.md

Lines changed: 101 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -34,84 +34,102 @@ Efficiently generate cryptographically strong random strings of specified entrop
3434

3535
### <a name="TLDR"></a>TL;DR
3636

37-
##### Example Usage
37+
##### Examples
38+
39+
Run any of the examples in the `examples` directory by:
40+
41+
```bash
42+
yarn examples
43+
node examples/dist/tldr_1.js
44+
```
45+
46+
##### Usage
47+
48+
Generate a potential of _1 million_ random strings with _1 in a billion_ chance of repeat:
3849

39-
OWASP session ID using base 32 characters:
4050
```js
41-
import {Random} from 'entropy-string'
51+
import {Random, Entropy} from 'entropy-string'
4252

43-
let random = new Random()
44-
let string = random.sessionID()
53+
const random = new Random()
54+
const bits = Entropy.bitsWithPowers(6, 9)
55+
56+
const string = random.string(bits)
4557
```
4658

47-
> QMdD37QNg2QmH3fHDRMhH2HpG4
59+
> pbbnBD4MQ3rbRN
4860
49-
OWASP session ID using [RFC 4648](https://tools.ietf.org/html/rfc4648#section-5) file system and URL safe characters:
61+
See [Real Need](#RealNeed) for description of what entropy bits represents.
62+
63+
`EntropyString` uses predefined `charset32` characters by default (see [Character Sets](#CharacterSets)). To get a random hexadecimal string with the same entropy `bits` as above:
64+
5065
```js
51-
import {Random, charSet64} from 'entropy-string'
66+
import {Random, Entropy} from 'entropy-string'
67+
68+
const random = new Random(charSet16)
69+
const bits = Entropy.bitsWithPowers(6, 9)
5270

53-
let random = new Random()
54-
let string = random.sessionID(charSet64)
71+
const string = random.string(bits)
5572
```
5673

57-
> HRU1M7VR5u-N6B0Xo4ZSjx
74+
> 878114ac513a538e22
5875
59-
60-
48-bit string using hex characters:
76+
Custom characters may be specified. Using uppercase hexadecimal characters:
6177

6278
```js
63-
import {Random, charSet16} from 'entropy-string'
79+
import {Random, Entropy} from 'entropy-string'
6480

65-
let random = new Random(charSet16)
66-
let string = random.string(48)
81+
const random = new Random('0123456789ABCDEF')
82+
const bits = Entropy.bitsWithPowers(6, 9)
83+
84+
const string = random.string(bits)
6785
```
6886

69-
> 7973b7cf643c
87+
> 16E26779479356B516
88+
89+
Convenience functions `smallID`, `mediumID`, `largeID`, `sessionID` and `token` provide random strings of various entropy bits.
7090

71-
96-bit string using uppercase hex characters:
91+
Small ID represents a potential of 30 strings with a 1 in a million chance of repeat:
7292

7393
```js
7494
import {Random} from 'entropy-string'
7595

76-
let random = new Random('0123456789ABCDEF')
77-
let string = random.string(95)
96+
const random = new Random()
97+
const string = random.smallID()
7898
```
7999

80-
> 134BBC6465B0DF101BFBC44B
81-
82-
Base 32 character string with a 1 in a million chance of a repeat in 30 strings:
100+
OWASP session ID using base 32 characters:
83101

84102
```js
85-
import {Random, Entropy} from 'entropy-string'
103+
import {Random} from 'entropy-string'
86104

87-
let random = new Random()
88-
let bits = Entropy.bits(30, 1000000)
89-
let string = random.string(bits)
105+
const random = new Random()
106+
const string = random.sessionID()
90107
```
91108

92-
> BqMhJM
109+
> nqqBt2P669nmjPQRqh4NtmTPn9
93110
94-
Base 64 character string with a 1 in a trillion chance of a repeat in 100 million strings:
95-
111+
OWASP session ID using [RFC 4648](https://tools.ietf.org/html/rfc4648#section-5) file system and URL safe characters:
96112
```js
97-
import {Random, Entropy, charSet64} from 'entropy-string'
98-
99-
let random = new Random(charSet64)
100-
let bits = Entropy.bitsWithPowers(7, 12)
101-
let string = random.string(bits)
113+
import {Random, charSet64} from 'entropy-string'
114+
115+
const random = new Random(charSet64)
116+
const string = random.sessionID()
102117
```
103118

104-
> emzRPXRudAjZnOme
119+
> HRU1M7VR5u-N6B0Xo4ZSjx
105120
106-
##### Examples
121+
Base 64 character 256 bits token
107122

108-
Run any of the examples in the `examples` directory by:
123+
```js
124+
import {Random, Entropy, charSet64} from 'entropy-string'
109125

110-
```bash
111-
yarn examples
112-
node examples/dist/tldr.js
126+
const random = new Random(charSet64)
127+
128+
const string = random.string(bits)
113129
```
114130

131+
> t-Z8b9FLvpc-roln2BZnGYLZAX_pn5U7uO_cbfldsIt
132+
115133
[TOC](#TOC)
116134

117135
### <a name="Overview"></a>Overview
@@ -175,11 +193,11 @@ Let's use `entropy-string` to help this developer generate 5 IDs:
175193
```js
176194
import {Random, Entropy, charSet16} from 'entropy-string'
177195

178-
let random = new Random(charSet16)
179-
let bits = Entropy.bits(10000, 1000000)
180-
let strings = Array()
196+
const random = new Random(charSet16)
197+
const bits = Entropy.bits(10000, 1000000)
198+
const strings = Array()
181199
for (let i = 0; i < 5; i++) {
182-
let string = random.string(bits)
200+
string = random.string(bits)
183201
strings.push(string)
184202
}
185203
```
@@ -189,22 +207,21 @@ Let's use `entropy-string` to help this developer generate 5 IDs:
189207
To generate the IDs, we first use
190208

191209
```js
192-
let bits = Entropy.bits(10000, 1000000)
210+
const bits = Entropy.bits(10000, 1000000)
193211
```
194212

195213
to determine how much entropy is needed to satisfy the probabilistic uniqueness of a **1 in a million** risk of repeat in a total of **10,000** strings. We didn't print the result, but if you did you'd see it's about **45.51** bits.
196214

197-
The following line creates a `Random` instance configured to generated strings using the default hexadecimal characters provided by `charSet16`:
215+
The following line creates a `Random` instance configured to generated strings using the predefined hexadecimal characters provided by `charSet16`:
198216

199217
```js
200-
let random = new Random(charSet16)
201-
218+
const random = new Random(charSet16)
202219
```
203220

204221
Then inside a loop we used
205222

206223
```js
207-
let string = random.string(bits)
224+
const string = random.string(bits)
208225
```
209226

210227
to actually generate a random string of the specified entropy. Looking at the IDs, we can see each is 12 characters long. Again, the string length is a by-product of the characters used to represent the entropy we needed. And it seems the developer didn't really need 16 characters after all.
@@ -217,33 +234,33 @@ Finally, given that the strings are 12 hexadecimals long, each string actually h
217234

218235
In [Real Need](#RealNeed) our developer used hexadecimal characters for the strings. Let's look at using other characters instead.
219236

220-
We'll start with using 32 characters. What 32 characters, you ask? The [Character Sets](#CharacterSets) section discusses the default characters available in `entropy-string` and the [Custom Characters](#CustomCharacters) section describes how you can use whatever characters you want. By default, `entropy-string` uses `charSet32` characters, so we don't need to pass that parameter into `new Random()`. We also use `bitsWithRiskPower` that allows passing the `risk` as a power of 10.
237+
We'll start with using 32 characters. What 32 characters, you ask? The [Character Sets](#CharacterSets) section discusses the predefined characters available in `entropy-string` and the [Custom Characters](#CustomCharacters) section describes how you can use whatever characters you want. By default, `entropy-string` uses `charSet32` characters, so we don't need to pass that parameter into `new Random()`. We also use `bitsWithRiskPower` that allows passing the `risk` as a power of 10.
221238

222239
```js
223240
import {Random, Entropy} from 'entropy-string'
224241

225-
let random = new Random()
226-
let bits = Entropy.bitsWithRiskPower(10000, 6)
227-
let string = random.string(bits)
242+
const random = new Random()
243+
const bits = Entropy.bitsWithRiskPower(10000, 6)
244+
const string = random.string(bits)
228245
```
229246

230247
> String: MD8r3BpTH3
231248
232249
We're using the same `Entropy.bits` calculation since we haven't changed the number of IDs or the accepted risk of probabilistic uniqueness. But this time we use 32 characters and our resulting ID only requires 10 characters (and can carry 50 bits of entropy).
233250

234-
As another example, let's assume we need to ensure the names of a handful of items are unique. Let's say 30 items. And suppose we decide we can live with a 1 in 100,000 probability of collision (we're just futzing with some coding ideas). Using the default provided hex characters:
251+
As another example, let's assume we need to ensure the names of a handful of items are unique. Let's say 30 items. And suppose we decide we can live with a 1 in 100,000 probability of collision (we're just futzing with some coding ideas). Using the predefined provided hex characters:
235252

236253
```js
237254
import {Random, Entropy, charSet16, charSet4} from 'entropy-string'
238255

239-
let random = new Random(charSet16)
240-
let bits = Entropy.bits(30, 100000)
241-
let string = random.string(bits)
256+
const random = new Random(charSet16)
257+
const bits = Entropy.bits(30, 100000)
258+
const string = random.string(bits)
242259
```
243260

244261
> String: dbf40a6
245262
246-
Using the same `Random` instance, we can switch to the default `charSet4` characters and generate a string of the same amount of entropy:
263+
Using the same `Random` instance, we can switch to the predefined `charSet4` characters and generate a string of the same amount of entropy:
247264

248265
```js
249266
random.use(charSet4)
@@ -259,9 +276,9 @@ Suppose we have a more extreme need. We want less than a 1 in a trillion chance
259276
```js
260277
import {Random, Entropy} from 'entropy-string'
261278

262-
let random = new Random()
263-
let bits = Entropy.bitsWithPowers(10, 12)
264-
let string = random.string(bits)
279+
const random = new Random()
280+
const bits = Entropy.bitsWithPowers(10, 12)
281+
const string = random.string(bits)
265282
```
266283

267284
> String: 4J86pbFG9BqdBjTLfD3rt6
@@ -271,8 +288,8 @@ Finally, let say we're generating session IDs. Since session IDs are ephemeral,
271288
```js
272289
import {Random} from 'entropy-string'
273290

274-
let random = new Random()
275-
let string = random.string(128)
291+
const random = new Random()
292+
const string = random.string(128)
276293
```
277294

278295
> String: Rm9gDFn6Q9DJ9rbrtrttBjR97r
@@ -282,8 +299,8 @@ Since session ID are such an important need, `entropy-string` provides a conveni
282299
```js
283300
import {Random, charSet64} from 'entropy-string'
284301

285-
let random = new Random(charSet64)
286-
let string = random.sessionID()
302+
const random = new Random(charSet64)
303+
const string = random.sessionID()
287304

288305
```
289306

@@ -295,16 +312,16 @@ In using 64 characters, note our string length is 22 characters. That's actually
295312

296313
### <a name="CharacterSets"></a>Character Sets
297314

298-
As we've seen in the previous sections, `entropy-string` provides default character sets. Let's see what's under the hood.
315+
As we've seen in the previous sections, `entropy-string` provides predefined character sets. Let's see what's under the hood.
299316

300317
```js
301318
import {charSet64} from 'entropy-string'
302-
let chars = charSet64.chars()
319+
const chars = charSet64.chars()
303320
```
304321

305322
> ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
306323
307-
The available `CharSet`s are *charSet64*, *charSet32*, *charSet16*, *charSet8*, *charSet4* and *charSet2*. The default characters for each were chosen as follows:
324+
The available `CharSet`s are *charSet64*, *charSet32*, *charSet16*, *charSet8*, *charSet4* and *charSet2*. The predefined characters for each were chosen as follows:
308325

309326
- CharSet 64: **ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_**
310327
* The file system and URL safe char set from [RFC 4648](https://tools.ietf.org/html/rfc4648#section-5).
@@ -335,7 +352,7 @@ Being able to easily generate random strings is great, but what if you want to s
335352
```js
336353
import {Random, charSet2} from 'entropy-string'
337354

338-
let random = new Random(charSet2)
355+
const random = new Random(charSet2)
339356
let flips = random.string(10)
340357
```
341358

@@ -350,13 +367,13 @@ The resulting string of __0__'s and __1__'s doesn't look quite right. Perhaps yo
350367

351368
> flips: THHTHTTHHT
352369
353-
As another example, we saw in [Character Sets](#CharacterSets) the default characters for `charSet16` are **0123456789abcdef**. Suppose you like uppercase hexadecimal letters instead.
370+
As another example, we saw in [Character Sets](#CharacterSets) the predefined characters for `charSet16` are **0123456789abcdef**. Suppose you like uppercase hexadecimal letters instead.
354371

355372
```js
356373
import {Random} from 'entropy-string'
357374

358-
let random = new Random('0123456789ABCDEF')
359-
let string = random.string(48)
375+
const random = new Random('0123456789ABCDEF')
376+
const string = random.string(48)
360377

361378
```
362379

@@ -365,15 +382,15 @@ As another example, we saw in [Character Sets](#CharacterSets) the default chara
365382
The `Random` constructor allows for three separate cases:
366383

367384
- No argument defauls to the `charSet32` characters.
368-
- One of six default `CharSet`s can be specified.
385+
- One of six predefined `CharSet`s can be specified.
369386
- A string representing the characters to use can be specified.
370387

371388
The 3rd option above will throw an `EntropyStringError` if the characters string isn't appropriate for creating a `CharSet`.
372389
```js
373390
import {Random} from 'entropy-string'
374391

375392
try {
376-
let random = new Random('123456')
393+
const random = new Random('123456')
377394
}
378395
catch(error) {
379396
console.log('Error: ' + error.message)
@@ -384,7 +401,7 @@ The 3rd option above will throw an `EntropyStringError` if the characters string
384401
385402
```js
386403
try {
387-
let random = new Random('01233210')
404+
const random = new Random('01233210')
388405
}
389406
catch(error) {
390407
console.log(error.message)
@@ -404,7 +421,7 @@ To generate the indices, `entropy-string` slices just enough bits from the array
404421
The `entropy-string` scheme is also efficient with regard to the amount of randomness used. Consider the following common JavaScript solution to generating random strings. To generate a character, an index into the available characters is create using `Math.random`. The code looks something like:
405422

406423
```js
407-
let chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
424+
const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
408425
let string = ""
409426
for(let i = 0; i < length; i++) {
410427
string += chars.charAt(Math.floor(Math.random() * chars.length));
@@ -420,7 +437,7 @@ Compare that to the `entropy-string` scheme. For the example above, slicing off
420437
```js
421438
import {Random} from 'entropy-string'
422439

423-
let random = new Random()
440+
const random = new Random()
424441
let string = random.string(80)
425442
```
426443

@@ -431,7 +448,7 @@ But there is an even bigger issue with the previous code from a security perspec
431448
However, if you don't need cryptographically strong random strings, you can request `entropy-string` use `Math.random` rather than the `crypto` library by using `random.stringRandom`:
432449

433450
```js
434-
let string = random.stringRandom(80)
451+
string = random.stringRandom(80)
435452
```
436453

437454
> fdRp9Q3rTMF7TdFN
@@ -451,8 +468,8 @@ Suppose we want a string capable of 30 bits of entropy using 32 characters. We p
451468
```js
452469
import {Random} from 'entropy-string'
453470

454-
let random = new Random()
455-
let bytes = Buffer.from([250, 200, 150, 100])
471+
const random = new Random()
472+
const bytes = Buffer.from([250, 200, 150, 100])
456473
let string = random.stringWithBytes(30, bytes)
457474
```
458475

@@ -494,9 +511,9 @@ Note the number of bytes needed is dependent on the number of characters in our
494511
```js
495512
import {Random, Entropy} from 'entropy-string'
496513

497-
let bits = Entropy.bitsWithPowers(6,9)
498-
let random = new Random()
499-
let string = random.string(bits)
514+
const random = new Random()
515+
const bits = Entropy.bitsWithPowers(6,9)
516+
const string = random.string(bits)
500517
```
501518

502519
> DdHrT2NdrHf8tM

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy