gitoria

3.3 KB

1. \* hl:crypto — passwords first. Native realm wrapper (see server.js for the JS twin).
3. The whole surface is six calls, and four 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
15. The realm is SERVER (plugin.json). A password never crosses to the client, so
16. importing this file is also a declaration about where the importing code runs. *\
18. \* Hash a password for storage. Returns a self-describing PHC string:
19. $argon2id$v=19$m=32768,t=2,p=1$<salt>$<hash>
20. $scrypt$ln=15,r=8,p=1$<salt>$<hash>
21. Every call salts freshly, so hashing the same password twice gives two
22. different strings and both verify.
24. `options` is optional: { cost = 15; kdf = "argon2id" }
25. cost base-2 log of the working memory in KiB — 15 is 32 MiB, the default.
26. CAPPED to 10..17 (1 MiB .. 128 MiB); the string records what was
27. actually used, so asking for 999 and reading the result back is how
28. you see the cap rather than being told about it.
29. kdf force an algorithm instead of taking the host's best one. Normally
30. unnecessary: `hash` picks argon2id when the system libcrypto has it
31. (OpenSSL >= 3.2) and scrypt otherwise, and `verify` reads both. *\
32. hash(password, options) {
33. return __native("crypto.hash", password, options)
34. }
36. \* Check a password against a stored PHC string. The comparison is constant-time
37. and the answer is a plain boolean: a wrong password, a truncated string, a
38. flipped character and a string that is not PHC at all are all `false`. A
39. stored string whose ALGORITHM this host cannot compute is a loud error
40. instead, because answering `false` to that would read as "wrong password". *\
41. verify(password, stored) {
42. return __native("crypto.verify", password, stored)
43. }
45. \* Read a stored string without the password:
46. { kdf = "argon2id"; version = 19; params = { m; t; p }; saltLen; hashLen }
47. { kdf = "scrypt"; version = null; params = { ln; r; p }; saltLen; hashLen }
48. `null` when the string is not a PHC string this plugin understands — which is
49. also the cheapest way to spot a store that was never migrated. *\
50. parsePhc(stored) {
51. return __native("crypto.parse", stored)
52. }
54. \* Which algorithm `hash()` writes with on this host. Reporting only — nothing
55. needs to branch on it, because every stored string names its own. *\
56. kdf() {
57. return __native("crypto.kdf")
58. }
60. \* SHA-256 of a string, as 64 lowercase hex characters. Content hashing: fast by
61. design, and therefore exactly the wrong tool for a password. *\
62. sha256(data) {
63. return __native("crypto.sha256", data)
64. }
66. \* n random bytes from the kernel CSPRNG, rendered as "hex" (the default) or
67. "base64". n is 1..1024. Suitable for session ids, one-time tokens and nonces. *\
68. randomBytes(n, encoding) {
69. return __native("crypto.random_bytes", n, encoding)
70. }