1 TESID: Textualised Encrypted Sequential Identifiers
2 ===================================================
4 This is the main repository for TESID.
6 Documentation about TESID itself is in this root directory.
8 Implementations are in subdirectories corresponding to the language name
9 (currently Rust, Python and JavaScript).
11 See also <https://chrismorgan.info/tesid/>.
13 TESID is an algorithm that provides a solid way for you to store sequential identifiers in your database,
14 but expose cryptographically-secure pseudorandom but fairly short strings to users.
15 This is ideal for most situations where you have centralised ID allocation and don’t *actively want* sequential IDs,
16 stopping the often-important information leak of the ID sequence,
17 while still keeping IDs quite short and simple,
18 so that humans can still usefully interact with them.
19 In these circumstances, it’s most obviously a good alternative to UUIDs which are massive overkill and fairly inconvenient.
24 There are three steps to TESID:
26 - First, if desired, it does type discrimination and sparsification,
27 by multiplying by a sparsity factor and adding a discriminant.
28 (This allows you to avoid TESID reuse or confusion across types.)
30 - Secondly, it scrambles the number with a real cryptographic block cipher within certain ranges:
31 a
20-bit block size for values
0 to
2²⁰ −
1,
30-bit for values
2²⁰ to
2³⁰ −
1,
32 <i>&c.</i> through
40-bit,
50-bit,
60-bit,
70-bit,
80-bit,
90-bit and
100-bit.
34 - Thirdly, it converts the scrambled number to a string using base conversion with a base-
32 alphabet,
35 with leading padding as necessary to the appropriate length for its range:
36 4 characters for
20-bit values,
6 for
30-,
8 for
40-, <i>&c.</i> until
20 for
100-bit values.
38 The end result is that you get nice short IDs for as long as is possible,
39 but avoid exposing the numeric sequence.
40 (In the absence of sparsity and discrimination,
41 you’ll get about a million four-character TESIDs,
42 a billion six-, a trillion eight-, and so on.)
44 See <algorithms.txt> for a more detailed description.
49 Refer to the examples in the README of each subdirectory.
54 TESID uses a
128-bit key for its cryptography;
55 libraries take this as a
32-character big-endian lowercase hexadecimal string.
57 This key should be randomly generated.
58 Here are a few command-line techniques you can use:
60 - `openssl rand -hex 16`
61 - `python -c 'import secrets; print(secrets.token_hex(16))'`
62 - `</dev/random head -c 16 | hexdump -e '4 "%08x" "\n"'`
63 - `node -e 'console.log(crypto.getRandomValues(new Uint8Array(16)).reduce((str, byte) => str + byte.toString(16).padStart(2, "0"), ""))'`
68 - [More general information](https://chrismorgan.info/tesid/more/)
69 - [The algorithms](algorithms.txt)
70 - [Design rationale](design-rationale.txt)