notes

4.5 KB

1. \* hl:crypto — passwords first. Native realm wrapper (see server.js for the JS twin).
3. The whole surface is eight calls, and six of them exist to serve the first two.
4. What this plugin is FOR is that an application never stores a password: it
5. stores the answer to "could this password have produced that", and the answer
6. carries its own algorithm and cost so it stays readable when both change.
8. hash(password, options) the stored value — a PHC string
9. verify(password, stored) true / false, in constant time
10. parsePhc(stored) what a stored value says about itself
11. kdf() which algorithm THIS host hashes with
12. sha256(data) content hashing (fast on purpose — not for passwords)
13. randomBytes(n, encoding) n bytes from the kernel CSPRNG
14. toBase64(data) a String's or a Bytes' bytes as base64 text
15. fromBase64(text) base64 text back to a Bytes (null if it is not base64)
17. The realm is SERVER (plugin.json). A password never crosses to the client, so
18. importing this file is also a declaration about where the importing code runs. *\
20. \* Hash a password for storage. Returns a self-describing PHC string:
21. $argon2id$v=19$m=32768,t=2,p=1$<salt>$<hash>
22. $scrypt$ln=15,r=8,p=1$<salt>$<hash>
23. Every call salts freshly, so hashing the same password twice gives two
24. different strings and both verify.
26. `options` is optional: { cost = 15; kdf = "argon2id" }
27. cost base-2 log of the working memory in KiB — 15 is 32 MiB, the default.
28. CAPPED to 10..17 (1 MiB .. 128 MiB); the string records what was
29. actually used, so asking for 999 and reading the result back is how
30. you see the cap rather than being told about it.
31. kdf force an algorithm instead of taking the host's best one. Normally
32. unnecessary: `hash` picks argon2id when the system libcrypto has it
33. (OpenSSL >= 3.2) and scrypt otherwise, and `verify` reads both. *\
34. hash(password, options) {
35. return __native("crypto.hash", password, options)
36. }
38. \* Check a password against a stored PHC string. The comparison is constant-time
39. and the answer is a plain boolean: a wrong password, a truncated string, a
40. flipped character and a string that is not PHC at all are all `false`. A
41. stored string whose ALGORITHM this host cannot compute is a loud error
42. instead, because answering `false` to that would read as "wrong password". *\
43. verify(password, stored) {
44. return __native("crypto.verify", password, stored)
45. }
47. \* Read a stored string without the password:
48. { kdf = "argon2id"; version = 19; params = { m; t; p }; saltLen; hashLen }
49. { kdf = "scrypt"; version = null; params = { ln; r; p }; saltLen; hashLen }
50. `null` when the string is not a PHC string this plugin understands — which is
51. also the cheapest way to spot a store that was never migrated. *\
52. parsePhc(stored) {
53. return __native("crypto.parse", stored)
54. }
56. \* Which algorithm `hash()` writes with on this host. Reporting only — nothing
57. needs to branch on it, because every stored string names its own. *\
58. kdf() {
59. return __native("crypto.kdf")
60. }
62. \* SHA-256 of a string, as 64 lowercase hex characters. Content hashing: fast by
63. design, and therefore exactly the wrong tool for a password. *\
64. sha256(data) {
65. return __native("crypto.sha256", data)
66. }
68. \* n random bytes from the kernel CSPRNG, rendered as "hex" (the default) or
69. "base64". n is 1..1024. Suitable for session ids, one-time tokens and nonces. *\
70. randomBytes(n, encoding) {
71. return __native("crypto.random_bytes", n, encoding)
72. }
74. \* Base64 (the standard alphabet, padded) of a String's bytes — its UTF-8 — or
75. of a Bytes, byte for byte:
77. toBase64('user:pa55') \\ "dXNlcjpwYTU1"
78. toBase64(req.bytes) \\ any bytes at all, NUL and 0xff included *\
79. toBase64(
80. data \\ a String or a Bytes
81. ) {
82. if (hlTypeName(data) == 'Bytes') {
83. return __native("crypto.base64_encode_hex", data.hex())
84. }
85. return __native("crypto.base64_encode", data)
86. }
88. \* Base64 text back to its bytes, as a Bytes; `.toString()` of it is the text
89. when the bytes are UTF-8. Padded and unpadded text both decode; anything
90. that is not base64 in the standard alphabet is null, not an error — a
91. malformed `Authorization: Basic` header is an answer, not a crash:
93. let b = fromBase64(req.headers.authorization.slice(6))
94. if (b != null) { let pair = b.toString() } \\ "user:pa55" *\
95. fromBase64(String text) {
96. let raw = __native("crypto.base64_decode", text)
97. if (raw == null) {
98. return null
99. }
100. return toBytes(raw)
101. }