tracker

32.8 KB

1. // hl:crypto plugin — native shared library (libcrypto.so under plugins/crypto/,
2. // dlopen'd by the runtime; NOT to be confused with the system libcrypto this file
3. // itself dlopens — the loader opens ours by absolute path with RTLD_LOCAL, and no
4. // RPATH points the plugin's own dlopen at this directory).
5. //
6. // The FIRST surface of this plugin is passwords, done the way a password should be
7. // stored: a memory-hard KDF, a random per-password salt, and a self-describing PHC
8. // string that carries the algorithm and its parameters so the stored value can be
9. // read back years later without the code remembering how it was made.
10. //
11. // hl_crypto_hash(password, opts?) → "$argon2id$v=19$m=…,t=…,p=…$salt$hash"
12. // → "$scrypt$ln=…,r=…,p=…$salt$hash"
13. // hl_crypto_verify(password, stored) → bool, CONSTANT-TIME comparison
14. // hl_crypto_parse(stored) → the PHC string as an object (or null)
15. // hl_crypto_kdf() → which KDF *this* engine hashes with
16. // hl_crypto_sha256(data) → lowercase hex, 64 chars
17. // hl_crypto_random_bytes(n, enc?) → n random bytes as hex (default) or base64
18. // hl_crypto_base64_encode(text) → base64 of a String's bytes (ticket #90)
19. // hl_crypto_base64_encode_hex(hex) → base64 of a Bytes, which crosses as its hex
20. // hl_crypto_base64_decode(text) → the decoded bytes as a raw String, or null
21. //
22. // WHICH KDF. argon2id is the first choice and scrypt is the fallback; the decision
23. // is made ONCE, at load, by asking the system's libcrypto for the ARGON2ID KDF
24. // (OpenSSL ≥ 3.2 ships it in the default provider; 3.0/3.1 and 1.1 do not). Nothing
25. // in the stored string depends on that probe going one way or the other — the PHC
26. // string names its own algorithm, so `verify` reads BOTH regardless of which one
27. // `hash` would produce today, and a machine that later gains argon2id keeps reading
28. // every scrypt string it wrote before.
29. //
30. // THE LIBRARY IS RESOLVED AT RUNTIME, the same way `plugins/http/tls_common.zig`
31. // resolves it (same candidate list, same dlopen flags, same dlsym-into-optionals
32. // shape). This is that PATTERN reused, not a second loader: tls_common's job is an
33. // SSL_CTX and it opens libssl beside libcrypto for it, which a password hash has no
34. // use for. A host with no libcrypto at all gets a loud error from `hash`/`verify`
35. // rather than a silent weaker hash.
36. //
37. // NEVER LOGGED: no function here writes a password, a salt, a derived key or a
38. // stored string to any stream. The only messages this file can emit are about the
39. // LIBRARY (missing .so, missing symbol), and they are emitted once.
41. const std = @import("std");
42. const api = @import("plugin_api");
44. const HlValue = api.HlValue;
45. const HlObject = api.HlObject;
46. const HlField = api.HlField;
47. const HlString = api.HlString;
49. const c_dlfcn = @cImport({
50. @cInclude("dlfcn.h");
51. });
53. const linux = std.os.linux;
55. // stack_trace_frames = 0 (mission 068): plugin code runs on interpreter FIBER
56. // stacks; Debug trace capture unwinds off them and segfaults.
57. var gpa = std.heap.DebugAllocator(.{ .stack_trace_frames = 0 }){};
58. const allocator = gpa.allocator();
60. // Direct syscall for stderr — std.debug.print pulls in std.Progress, whose global
61. // state is ABI-incompatible when a .so is loaded into a differently-built binary.
62. fn logMsg(msg: []const u8) void {
63. _ = linux.write(2, msg.ptr, msg.len);
64. }
66. // =========================================================================
67. // Cost — ONE number, the same meaning on both KDFs
68. //
69. // `cost` is the base-2 logarithm of the working memory in KiB. cost 15 is 32 MiB
70. // on argon2id (memcost = 32768 KiB) and 32 MiB on scrypt (N = 2^15, r = 8, p = 1,
71. // which is 128 · N · r bytes). That is at or above the usual baseline for an
72. // interactive login on both, and it is one knob rather than two sets of three.
73. //
74. // The option is CAPPED at both ends, and the cap is observable: the PHC string
75. // records the parameters that were actually used, so `parse(hash(pw, {cost=99}))`
76. // reports the cap rather than 99.
77. // =========================================================================
79. const COST_DEFAULT: u32 = 15; // 32 MiB
80. const COST_MIN: u32 = 10; // 1 MiB — below this a KDF stops being memory-hard
81. const COST_MAX: u32 = 17; // 128 MiB — the strongest cost anyone recommends for an
82. // interactive login; past it a burst of sign-ins is a
83. // denial of service against the machine serving them.
85. // Fixed shape of everything else. These are recorded in the PHC string too, so
86. // changing them later does not strand a single stored password.
87. const SALT_LEN: usize = 16;
88. const HASH_LEN: usize = 32;
89. /// The floor a stored string must clear to be READ at all — see `decodePhc`.
90. /// Not the same numbers as above: those are what this plugin writes today, these
91. /// are what any string has to carry for a comparison against it to mean anything.
92. const MIN_SALT_LEN: usize = 8;
93. const MIN_HASH_LEN: usize = 16;
94. const ARGON2_TIME: u32 = 2; // t — the OWASP pairing for a memory-heavy argon2id
95. const ARGON2_LANES: u32 = 1; // p — one lane needs no libctx thread pool
96. const SCRYPT_R: u32 = 8; // the RFC 7914 block size everyone uses
97. const SCRYPT_P: u32 = 1;
99. /// scrypt's memory bound is a SAFETY VALVE inside OpenSSL, not a tuning knob:
100. /// EVP_PBE_scrypt refuses a request above `maxmem` and its default is 32 MiB,
101. /// which the default cost sits exactly on. Raised past the cost cap's own ceiling
102. /// so `cost` is the only limit that decides anything.
103. const SCRYPT_MAXMEM: u64 = 2 * 1024 * 1024 * 1024;
105. const Kdf = enum {
106. argon2id,
107. scrypt,
109. fn name(self: Kdf) []const u8 {
110. return switch (self) {
111. .argon2id => "argon2id",
112. .scrypt => "scrypt",
113. };
114. }
116. fn parse(text: []const u8) ?Kdf {
117. if (std.mem.eql(u8, text, "argon2id")) return .argon2id;
118. if (std.mem.eql(u8, text, "scrypt")) return .scrypt;
119. return null;
120. }
121. };
123. // =========================================================================
124. // libcrypto, resolved at runtime (the tls_common pattern)
125. // =========================================================================
127. const EVP_KDF = opaque {};
128. const EVP_KDF_CTX = opaque {};
130. /// openssl/core.h. Built by hand rather than through OSSL_PARAM_construct_*,
131. /// which return this struct BY VALUE across the C ABI — the field layout is
132. /// public and stable, the by-value return convention is not worth the risk.
133. const OSSL_PARAM = extern struct {
134. key: ?[*:0]const u8,
135. data_type: c_uint,
136. data: ?*anyopaque,
137. data_size: usize,
138. return_size: usize,
139. };
141. const OSSL_PARAM_UNSIGNED_INTEGER: c_uint = 2;
142. const OSSL_PARAM_OCTET_STRING: c_uint = 5;
143. /// OSSL_PARAM_UNMODIFIED — what the construct helpers put in `return_size` for a
144. /// parameter being passed IN.
145. const PARAM_UNMODIFIED: usize = std.math.maxInt(usize);
147. fn paramEnd() OSSL_PARAM {
148. return .{ .key = null, .data_type = 0, .data = null, .data_size = 0, .return_size = 0 };
149. }
151. fn paramUint(key: [*:0]const u8, value: *u32) OSSL_PARAM {
152. return .{
153. .key = key,
154. .data_type = OSSL_PARAM_UNSIGNED_INTEGER,
155. .data = @ptrCast(value),
156. .data_size = @sizeOf(u32),
157. .return_size = PARAM_UNMODIFIED,
158. };
159. }
161. fn paramOctets(key: [*:0]const u8, bytes: []const u8) OSSL_PARAM {
162. return .{
163. .key = key,
164. .data_type = OSSL_PARAM_OCTET_STRING,
165. .data = @constCast(@ptrCast(bytes.ptr)),
166. .data_size = bytes.len,
167. .return_size = PARAM_UNMODIFIED,
168. };
169. }
171. const EVP_PBE_scrypt_fn = *const fn ([*]const u8, usize, [*]const u8, usize, u64, u64, u64, u64, [*]u8, usize) callconv(.c) c_int;
172. const EVP_KDF_fetch_fn = *const fn (?*anyopaque, [*:0]const u8, ?[*:0]const u8) callconv(.c) ?*EVP_KDF;
173. const EVP_KDF_free_fn = *const fn (?*EVP_KDF) callconv(.c) void;
174. const EVP_KDF_CTX_new_fn = *const fn (?*EVP_KDF) callconv(.c) ?*EVP_KDF_CTX;
175. const EVP_KDF_CTX_free_fn = *const fn (?*EVP_KDF_CTX) callconv(.c) void;
176. const EVP_KDF_derive_fn = *const fn (?*EVP_KDF_CTX, [*]u8, usize, ?[*]const OSSL_PARAM) callconv(.c) c_int;
178. const Backend = struct {
179. lib: ?*anyopaque = null,
180. /// The KDF `hash()` produces. argon2id when the probe found it, scrypt otherwise.
181. preferred: Kdf = .scrypt,
182. has_argon2id: bool = false,
183. has_scrypt: bool = false,
185. fn_scrypt: ?EVP_PBE_scrypt_fn = null,
186. fn_kdf_fetch: ?EVP_KDF_fetch_fn = null,
187. fn_kdf_free: ?EVP_KDF_free_fn = null,
188. fn_kdf_ctx_new: ?EVP_KDF_CTX_new_fn = null,
189. fn_kdf_ctx_free: ?EVP_KDF_CTX_free_fn = null,
190. fn_kdf_derive: ?EVP_KDF_derive_fn = null,
191. };
193. var backend: Backend = .{};
194. /// A plain bool, not an atomic: `__native` calls are made from INTERPRETER code,
195. /// which runs as fibers on one thread. Plugins that own their own threads (the
196. /// HTTP servers) never call in here, so there is no second writer to guard
197. /// against — the same reasoning `hl:math`'s lazily-seeded PRNG state relies on.
198. var backend_ready: bool = false;
200. fn loadSym(lib: ?*anyopaque, comptime T: type, name: [*:0]const u8) ?T {
201. const sym = c_dlfcn.dlsym(lib, name) orelse return null;
202. return @ptrCast(sym);
203. }
205. /// Resolve libcrypto and decide the KDF, once. Returns null when the host has no
206. /// usable libcrypto — every entry point that needs one then fails LOUDLY.
207. fn ensureBackend() ?*const Backend {
208. if (backend_ready) {
209. return if (backend.lib == null) null else &backend;
210. }
211. backend_ready = true;
213. // Same candidate list and flags as plugins/http/tls_common.zig. No bare-name
214. // ambiguity with our OWN libcrypto.so: this plugin sets no RPATH, so the
215. // dynamic loader never searches plugins/crypto/ for these.
216. const crypto_paths = [_][*:0]const u8{ "libcrypto.so.3", "libcrypto.so.1.1", "libcrypto.so" };
217. for (crypto_paths) |path| {
218. backend.lib = c_dlfcn.dlopen(path, c_dlfcn.RTLD_NOW | c_dlfcn.RTLD_LOCAL);
219. if (backend.lib != null) break;
220. }
221. if (backend.lib == null) {
222. logMsg("hl:crypto: no libcrypto.so on this host — password hashing is unavailable\n");
223. return null;
224. }
226. backend.fn_scrypt = loadSym(backend.lib, EVP_PBE_scrypt_fn, "EVP_PBE_scrypt");
227. backend.has_scrypt = backend.fn_scrypt != null;
229. backend.fn_kdf_fetch = loadSym(backend.lib, EVP_KDF_fetch_fn, "EVP_KDF_fetch");
230. backend.fn_kdf_free = loadSym(backend.lib, EVP_KDF_free_fn, "EVP_KDF_free");
231. backend.fn_kdf_ctx_new = loadSym(backend.lib, EVP_KDF_CTX_new_fn, "EVP_KDF_CTX_new");
232. backend.fn_kdf_ctx_free = loadSym(backend.lib, EVP_KDF_CTX_free_fn, "EVP_KDF_CTX_free");
233. backend.fn_kdf_derive = loadSym(backend.lib, EVP_KDF_derive_fn, "EVP_KDF_derive");
235. // THE PROBE. The symbols exist from OpenSSL 3.0; the ARGON2ID *algorithm*
236. // only from 3.2, and only a successful fetch proves the provider has it.
237. if (backend.fn_kdf_fetch != null and backend.fn_kdf_free != null and
238. backend.fn_kdf_ctx_new != null and backend.fn_kdf_ctx_free != null and
239. backend.fn_kdf_derive != null)
240. {
241. if (backend.fn_kdf_fetch.?(null, "ARGON2ID", null)) |kdf| {
242. backend.fn_kdf_free.?(kdf);
243. backend.has_argon2id = true;
244. }
245. }
247. backend.preferred = if (backend.has_argon2id) .argon2id else .scrypt;
248. if (!backend.has_argon2id and !backend.has_scrypt) {
249. logMsg("hl:crypto: libcrypto has neither ARGON2ID nor EVP_PBE_scrypt\n");
250. }
251. return &backend;
252. }
254. // =========================================================================
255. // Derivation
256. // =========================================================================
258. fn deriveArgon2id(b: *const Backend, password: []const u8, salt: []const u8, memcost_kib: u32, out: []u8) bool {
259. if (!b.has_argon2id) return false;
260. const kdf = b.fn_kdf_fetch.?(null, "ARGON2ID", null) orelse return false;
261. defer b.fn_kdf_free.?(kdf);
262. const ctx = b.fn_kdf_ctx_new.?(kdf) orelse return false;
263. defer b.fn_kdf_ctx_free.?(ctx);
265. var m: u32 = memcost_kib;
266. var t: u32 = ARGON2_TIME;
267. var lanes: u32 = ARGON2_LANES;
268. var threads: u32 = 1;
269. var size: u32 = @intCast(out.len);
271. // `lanes`/`threads` are both 1 on purpose: argon2id with more than one thread
272. // needs a thread pool installed on the OSSL_LIB_CTX, and a plugin has no
273. // business installing one into the process's default library context.
274. var params = [_]OSSL_PARAM{
275. paramOctets("pass", password),
276. paramOctets("salt", salt),
277. paramUint("memcost", &m),
278. paramUint("iter", &t),
279. paramUint("lanes", &lanes),
280. paramUint("threads", &threads),
281. paramUint("size", &size),
282. paramEnd(),
283. };
285. return b.fn_kdf_derive.?(ctx, out.ptr, out.len, &params) == 1;
286. }
288. fn deriveScrypt(b: *const Backend, password: []const u8, salt: []const u8, ln: u32, r: u32, p: u32, out: []u8) bool {
289. const f = b.fn_scrypt orelse return false;
290. if (ln >= 64) return false;
291. const n: u64 = @as(u64, 1) << @intCast(ln);
292. return f(
293. password.ptr,
294. password.len,
295. salt.ptr,
296. salt.len,
297. n,
298. r,
299. p,
300. SCRYPT_MAXMEM,
301. out.ptr,
302. out.len,
303. ) == 1;
304. }
306. // =========================================================================
307. // The PHC string
308. //
309. // $argon2id$v=19$m=32768,t=2,p=1$<salt>$<hash>
310. // $scrypt$ln=15,r=8,p=1$<salt>$<hash>
311. //
312. // salt and hash are base64 with the standard alphabet and NO padding, which is
313. // what the PHC string format specifies. Nothing here is secret — the whole point
314. // of the format is that the stored value describes itself.
315. // =========================================================================
317. const B64 = std.base64.standard_no_pad;
319. const Phc = struct {
320. kdf: Kdf,
321. /// argon2 only; 19 (0x13) is the only version OpenSSL's ARGON2ID speaks.
322. version: u32 = 19,
323. /// argon2: memory in KiB. scrypt: unused.
324. m: u32 = 0,
325. /// argon2: iterations. scrypt: unused.
326. t: u32 = 0,
327. /// scrypt: log2(N). argon2: unused.
328. ln: u32 = 0,
329. /// scrypt: block size. argon2: unused.
330. r: u32 = 0,
331. /// lanes (argon2) / parallelism (scrypt).
332. p: u32 = 0,
333. salt: [64]u8 = undefined,
334. salt_len: usize = 0,
335. hash: [64]u8 = undefined,
336. hash_len: usize = 0,
337. };
339. fn encodePhc(phc: *const Phc) ?[]u8 {
340. var salt_b64: [128]u8 = undefined;
341. var hash_b64: [128]u8 = undefined;
342. const s = B64.Encoder.encode(&salt_b64, phc.salt[0..phc.salt_len]);
343. const h = B64.Encoder.encode(&hash_b64, phc.hash[0..phc.hash_len]);
344. return switch (phc.kdf) {
345. .argon2id => std.fmt.allocPrint(allocator, "$argon2id$v={d}$m={d},t={d},p={d}${s}${s}", .{
346. phc.version, phc.m, phc.t, phc.p, s, h,
347. }) catch null,
348. .scrypt => std.fmt.allocPrint(allocator, "$scrypt$ln={d},r={d},p={d}${s}${s}", .{
349. phc.ln, phc.r, phc.p, s, h,
350. }) catch null,
351. };
352. }
354. /// One `key=value` out of a comma-separated parameter field. Absent or unparsable
355. /// is null, and every caller treats null as "this is not a PHC string I can read".
356. fn paramValue(field: []const u8, key: []const u8) ?u32 {
357. var it = std.mem.splitScalar(u8, field, ',');
358. while (it.next()) |pair| {
359. const eq = std.mem.indexOfScalar(u8, pair, '=') orelse continue;
360. if (!std.mem.eql(u8, pair[0..eq], key)) continue;
361. return std.fmt.parseInt(u32, pair[eq + 1 ..], 10) catch null;
362. }
363. return null;
364. }
366. fn decodeB64Into(text: []const u8, buf: []u8) ?usize {
367. const n = B64.Decoder.calcSizeForSlice(text) catch return null;
368. if (n == 0 or n > buf.len) return null;
369. B64.Decoder.decode(buf[0..n], text) catch return null;
370. return n;
371. }
373. /// Strictly parse a stored string. ANY deviation — a wrong field count, a missing
374. /// parameter, a base64 body that does not decode — is null, and `verify` turns
375. /// null into `false`. That is what makes a tampered string fail rather than
376. /// half-parse into something with a comparable hash.
377. fn decodePhc(stored: []const u8) ?Phc {
378. if (stored.len < 2 or stored[0] != '$') return null;
380. var parts: [8][]const u8 = undefined;
381. var count: usize = 0;
382. var it = std.mem.splitScalar(u8, stored[1..], '$');
383. while (it.next()) |part| {
384. if (count == parts.len) return null;
385. parts[count] = part;
386. count += 1;
387. }
389. var phc = Phc{ .kdf = .scrypt };
390. const kdf = Kdf.parse(parts[0]) orelse return null;
391. phc.kdf = kdf;
393. const salt_field: []const u8, const hash_field: []const u8 = switch (kdf) {
394. .argon2id => blk: {
395. // $argon2id$v=19$m=..,t=..,p=..$salt$hash
396. if (count != 5) return null;
397. if (!std.mem.startsWith(u8, parts[1], "v=")) return null;
398. phc.version = std.fmt.parseInt(u32, parts[1][2..], 10) catch return null;
399. phc.m = paramValue(parts[2], "m") orelse return null;
400. phc.t = paramValue(parts[2], "t") orelse return null;
401. phc.p = paramValue(parts[2], "p") orelse return null;
402. break :blk .{ parts[3], parts[4] };
403. },
404. .scrypt => blk: {
405. // $scrypt$ln=..,r=..,p=..$salt$hash
406. if (count != 4) return null;
407. phc.version = 0;
408. phc.ln = paramValue(parts[1], "ln") orelse return null;
409. phc.r = paramValue(parts[1], "r") orelse return null;
410. phc.p = paramValue(parts[1], "p") orelse return null;
411. break :blk .{ parts[2], parts[3] };
412. },
413. };
415. phc.salt_len = decodeB64Into(salt_field, &phc.salt) orelse return null;
416. phc.hash_len = decodeB64Into(hash_field, &phc.hash) orelse return null;
418. // MINIMUM LENGTHS, and they are load-bearing rather than tidiness. A KDF
419. // derives as many bytes as it is asked for, so `verify` on a stored string
420. // whose hash field had been CUT DOWN to eight base64 characters used to
421. // derive six bytes and compare six bytes — and six bytes of a correct
422. // derivation match. Truncating the stored value was therefore a way to make
423. // a wrong password verify, until this line. (Found by the tamper gate on the
424. // first run of tests/pass/plugins/005; the JS twin had it too.)
425. if (phc.salt_len < MIN_SALT_LEN or phc.hash_len < MIN_HASH_LEN) return null;
426. return phc;
427. }
429. // =========================================================================
430. // Constant-time comparison
431. //
432. // The lengths are NOT secret (they are in the stored string, in the clear), so
433. // comparing them up front leaks nothing. The bytes are: the loop below always
434. // touches every one of them and branches on nothing.
435. // =========================================================================
437. /// Bytes straight off the kernel CSPRNG. `getrandom(2)` rather than any
438. /// userspace generator: a salt and a token are the two things in this file that
439. /// must not be predictable, and the http plugins reach for the same syscall.
440. fn fillRandom(buf: []u8) bool {
441. return linux.getrandom(buf.ptr, buf.len, 0) == buf.len;
442. }
444. fn constantTimeEql(a: []const u8, b: []const u8) bool {
445. if (a.len != b.len) return false;
446. var diff: u8 = 0;
447. for (a, b) |x, y| diff |= x ^ y;
448. return diff == 0;
449. }
451. // =========================================================================
452. // Value helpers
453. // =========================================================================
455. fn hlStr(s: []const u8) HlString {
456. return .{ .ptr = s.ptr, .len = s.len };
457. }
459. fn allocStringDeinit(val: *HlValue) callconv(.c) void {
460. if (val.type != .hl_string) return;
461. const s = val.data.string;
462. if (s.len == 0) return;
463. allocator.free(@constCast(s.ptr[0..s.len]));
464. }
466. /// Hand an owned string to the runtime. The loader copies the bytes into its own
467. /// tracker and then calls this value's deinit_fn, so the plugin's copy is freed
468. /// on the same call it was made.
469. fn ownedString(s: []u8) HlValue {
470. var result = api.makeString(s);
471. result.deinit_fn = &allocStringDeinit;
472. return result;
473. }
475. fn objDeinit(obj: *HlObject) callconv(.c) void {
476. allocator.free(obj.fields[0..obj.field_count]);
477. allocator.destroy(obj);
478. }
480. fn makeObj(fields: []HlField) HlValue {
481. const owned = allocator.dupe(HlField, fields) catch return api.makeNull();
482. const obj = allocator.create(HlObject) catch {
483. allocator.free(owned);
484. return api.makeNull();
485. };
486. obj.* = .{ .fields = owned.ptr, .field_count = owned.len, .deinit_fn = &objDeinit };
487. return api.makeObject(obj);
488. }
490. fn argString(argc: u32, argv: [*]const HlValue, idx: u32) ?[]const u8 {
491. if (idx >= argc) return null;
492. if (argv[idx].type != .hl_string) return null;
493. return argv[idx].data.string.ptr[0..argv[idx].data.string.len];
494. }
496. fn argNumber(argc: u32, argv: [*]const HlValue, idx: u32) ?f64 {
497. if (idx >= argc) return null;
498. if (argv[idx].type != .hl_number) return null;
499. return argv[idx].data.number;
500. }
502. /// One field out of an options hybrid. Absent object, absent key and a key of the
503. /// wrong type all read as "not given".
504. fn optField(argc: u32, argv: [*]const HlValue, idx: u32, key: []const u8) ?HlValue {
505. if (idx >= argc) return null;
506. if (argv[idx].type != .hl_object) return null;
507. const obj = argv[idx].data.object;
508. for (obj.fields[0..obj.field_count]) |f| {
509. if (std.mem.eql(u8, f.key.ptr[0..f.key.len], key)) return f.value;
510. }
511. return null;
512. }
514. // =========================================================================
515. // Exports
516. // =========================================================================
518. /// hash(password, opts?) → PHC string.
519. /// opts: { cost = <clamped to COST_MIN..COST_MAX>, kdf = "argon2id" | "scrypt" }
520. export fn hl_crypto_hash(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
521. const password = argString(argc, argv, 0) orelse
522. return api.makeError("hl:crypto hash() expects a string password");
524. const b = ensureBackend() orelse
525. return api.makeError("hl:crypto hash(): no libcrypto.so on this host");
527. var cost: u32 = COST_DEFAULT;
528. if (optField(argc, argv, 1, "cost")) |v| {
529. if (v.type == .hl_number) {
530. const n = v.data.number;
531. if (!std.math.isNan(n)) {
532. // Clamp, do not refuse: `cost` is a capped knob and the PHC string
533. // it produces reports the value that was actually used.
534. const clamped = @max(@as(f64, @floatFromInt(COST_MIN)), @min(@as(f64, @floatFromInt(COST_MAX)), n));
535. cost = @intFromFloat(@trunc(clamped));
536. }
537. }
538. }
540. var kdf = b.preferred;
541. if (optField(argc, argv, 1, "kdf")) |v| {
542. if (v.type == .hl_string) {
543. const want = v.data.string.ptr[0..v.data.string.len];
544. kdf = Kdf.parse(want) orelse
545. return api.makeError("hl:crypto hash(): unknown kdf — expected \"argon2id\" or \"scrypt\"");
546. }
547. }
549. var phc = Phc{ .kdf = kdf, .salt_len = SALT_LEN, .hash_len = HASH_LEN };
550. if (!fillRandom(phc.salt[0..SALT_LEN])) {
551. return api.makeError("hl:crypto hash(): the kernel CSPRNG refused a salt");
552. }
554. const ok = switch (kdf) {
555. .argon2id => blk: {
556. phc.m = @as(u32, 1) << @intCast(cost);
557. phc.t = ARGON2_TIME;
558. phc.p = ARGON2_LANES;
559. break :blk deriveArgon2id(b, password, phc.salt[0..SALT_LEN], phc.m, phc.hash[0..HASH_LEN]);
560. },
561. .scrypt => blk: {
562. phc.ln = cost;
563. phc.r = SCRYPT_R;
564. phc.p = SCRYPT_P;
565. break :blk deriveScrypt(b, password, phc.salt[0..SALT_LEN], phc.ln, phc.r, phc.p, phc.hash[0..HASH_LEN]);
566. },
567. };
568. if (!ok) {
569. return api.makeError(switch (kdf) {
570. .argon2id => "hl:crypto hash(): this libcrypto has no ARGON2ID (needs OpenSSL >= 3.2)",
571. .scrypt => "hl:crypto hash(): this libcrypto has no EVP_PBE_scrypt",
572. });
573. }
575. const out = encodePhc(&phc) orelse
576. return api.makeError("hl:crypto hash(): could not encode the PHC string");
577. return ownedString(out);
578. }
580. /// verify(password, stored) → bool. Malformed, tampered and non-matching are all
581. /// `false`; a stored string whose ALGORITHM this engine cannot compute is a loud
582. /// error, because answering `false` there would read as "wrong password".
583. export fn hl_crypto_verify(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
584. const password = argString(argc, argv, 0) orelse return api.makeBool(false);
585. const stored = argString(argc, argv, 1) orelse return api.makeBool(false);
587. const phc = decodePhc(stored) orelse return api.makeBool(false);
588. if (phc.hash_len == 0 or phc.hash_len > 64) return api.makeBool(false);
590. const b = ensureBackend() orelse
591. return api.makeError("hl:crypto verify(): no libcrypto.so on this host");
593. var computed: [64]u8 = undefined;
594. const ok = switch (phc.kdf) {
595. .argon2id => blk: {
596. if (!b.has_argon2id) {
597. return api.makeError("hl:crypto verify(): stored password is argon2id and this libcrypto has none (needs OpenSSL >= 3.2)");
598. }
599. if (phc.version != 19 or phc.p != 1) break :blk false;
600. break :blk deriveArgon2id(b, password, phc.salt[0..phc.salt_len], phc.m, computed[0..phc.hash_len]);
601. },
602. .scrypt => blk: {
603. if (!b.has_scrypt) {
604. return api.makeError("hl:crypto verify(): stored password is scrypt and this libcrypto has no EVP_PBE_scrypt");
605. }
606. if (phc.ln == 0 or phc.ln > 30 or phc.r == 0 or phc.p == 0) break :blk false;
607. break :blk deriveScrypt(b, password, phc.salt[0..phc.salt_len], phc.ln, phc.r, phc.p, computed[0..phc.hash_len]);
608. },
609. };
610. if (!ok) return api.makeBool(false);
612. return api.makeBool(constantTimeEql(computed[0..phc.hash_len], phc.hash[0..phc.hash_len]));
613. }
615. /// parsePhc(stored) → { kdf, version, params, saltLen, hashLen } or null.
616. /// Reads a stored string WITHOUT the password — what it is for is looking at what
617. /// you have stored (which algorithm, at which cost), not for checking anything.
618. export fn hl_crypto_parse(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
619. const stored = argString(argc, argv, 0) orelse return api.makeNull();
620. const phc = decodePhc(stored) orelse return api.makeNull();
622. var params: HlValue = undefined;
623. switch (phc.kdf) {
624. .argon2id => {
625. var pf = [_]HlField{
626. .{ .key = hlStr("m"), .value = api.makeNumber(@floatFromInt(phc.m)) },
627. .{ .key = hlStr("t"), .value = api.makeNumber(@floatFromInt(phc.t)) },
628. .{ .key = hlStr("p"), .value = api.makeNumber(@floatFromInt(phc.p)) },
629. };
630. params = makeObj(&pf);
631. },
632. .scrypt => {
633. var pf = [_]HlField{
634. .{ .key = hlStr("ln"), .value = api.makeNumber(@floatFromInt(phc.ln)) },
635. .{ .key = hlStr("r"), .value = api.makeNumber(@floatFromInt(phc.r)) },
636. .{ .key = hlStr("p"), .value = api.makeNumber(@floatFromInt(phc.p)) },
637. };
638. params = makeObj(&pf);
639. },
640. }
642. var fields = [_]HlField{
643. .{ .key = hlStr("kdf"), .value = api.makeString(phc.kdf.name()) },
644. .{ .key = hlStr("version"), .value = if (phc.kdf == .argon2id)
645. api.makeNumber(@floatFromInt(phc.version))
646. else
647. api.makeNull() },
648. .{ .key = hlStr("params"), .value = params },
649. .{ .key = hlStr("saltLen"), .value = api.makeNumber(@floatFromInt(phc.salt_len)) },
650. .{ .key = hlStr("hashLen"), .value = api.makeNumber(@floatFromInt(phc.hash_len)) },
651. };
652. return makeObj(&fields);
653. }
655. /// kdf() → the algorithm THIS engine writes with ("argon2id" or "scrypt").
656. /// Reporting only: nothing needs to ask, because every stored string says so itself.
657. export fn hl_crypto_kdf(_: u32, _: [*]const HlValue) callconv(.c) HlValue {
658. const b = ensureBackend() orelse return api.makeNull();
659. return api.makeString(b.preferred.name());
660. }
662. /// sha256(data) → 64 lowercase hex characters.
663. /// CONTENT hashing, not password hashing — it is deliberately fast, which is
664. /// exactly why `hash()` above does not use it.
665. export fn hl_crypto_sha256(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
666. const data = argString(argc, argv, 0) orelse
667. return api.makeError("hl:crypto sha256() expects a string");
668. var digest: [32]u8 = undefined;
669. std.crypto.hash.sha2.Sha256.hash(data, &digest, .{});
670. const out = std.fmt.allocPrint(allocator, "{x}", .{&digest}) catch
671. return api.makeError("hl:crypto sha256(): out of memory");
672. return ownedString(out);
673. }
675. const RANDOM_MAX: usize = 1024;
677. /// randomBytes(n, encoding?) → n bytes from the kernel CSPRNG, "hex" (default) or
678. /// "base64" (standard alphabet, padded — this is a token, not a PHC field).
679. export fn hl_crypto_random_bytes(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
680. const n_f = argNumber(argc, argv, 0) orelse
681. return api.makeError("hl:crypto randomBytes() expects a byte count");
682. if (!(n_f >= 1) or n_f > @as(f64, @floatFromInt(RANDOM_MAX))) {
683. return api.makeError("hl:crypto randomBytes(): count must be between 1 and 1024");
684. }
685. const n: usize = @intFromFloat(@trunc(n_f));
687. var buf: [RANDOM_MAX]u8 = undefined;
688. if (!fillRandom(buf[0..n])) {
689. return api.makeError("hl:crypto randomBytes(): the kernel CSPRNG refused");
690. }
692. const enc = argString(argc, argv, 1) orelse "hex";
693. if (std.mem.eql(u8, enc, "hex")) {
694. const out = std.fmt.allocPrint(allocator, "{x}", .{buf[0..n]}) catch
695. return api.makeError("hl:crypto randomBytes(): out of memory");
696. return ownedString(out);
697. }
698. if (std.mem.eql(u8, enc, "base64")) {
699. const std64 = std.base64.standard;
700. const out = allocator.alloc(u8, std64.Encoder.calcSize(n)) catch
701. return api.makeError("hl:crypto randomBytes(): out of memory");
702. _ = std64.Encoder.encode(out, buf[0..n]);
703. return ownedString(out);
704. }
705. return api.makeError("hl:crypto randomBytes(): encoding must be \"hex\" or \"base64\"");
706. }
708. // ── base64 (ticket #90) ─────────────────────────────────────────────────────
709. // The standard alphabet (RFC 4648 §4), what an `Authorization: Basic` header
710. // and most of the web speak. Encoding pads; decoding takes the padded and the
711. // unpadded form alike and answers null for anything else — a stray character,
712. // a length no encoder writes, or non-zero bits in the last character's unused
713. // tail (a string that is not what encoding its own result would give). The
714. // JavaScript twin applies the same test, so both engines refuse the same text.
716. fn base64Encode(raw: []const u8, comptime what: []const u8) HlValue {
717. const enc = std.base64.standard.Encoder;
718. const out = allocator.alloc(u8, enc.calcSize(raw.len)) catch
719. return api.makeError("hl:crypto " ++ what ++ "(): out of memory");
720. _ = enc.encode(out, raw);
721. return ownedString(out);
722. }
724. /// toBase64(String) — the String's bytes, as they are.
725. export fn hl_crypto_base64_encode(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
726. const data = argString(argc, argv, 0) orelse
727. return api.makeError("hl:crypto toBase64() expects a String or a Bytes");
728. return base64Encode(data, "toBase64");
729. }
731. /// toBase64(Bytes) — the ABI has no Bytes: it crosses as its hex text.
732. export fn hl_crypto_base64_encode_hex(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
733. const hex = argString(argc, argv, 0) orelse
734. return api.makeError("hl:crypto toBase64() expects a String or a Bytes");
735. const raw = allocator.alloc(u8, hex.len / 2) catch
736. return api.makeError("hl:crypto toBase64(): out of memory");
737. defer allocator.free(raw);
738. _ = std.fmt.hexToBytes(raw, hex) catch return api.makeError("hl:crypto toBase64(): not a Bytes");
739. return base64Encode(raw, "toBase64");
740. }
742. /// fromBase64(text) → the bytes as a raw String (server.hl makes it a Bytes),
743. /// or null when `text` is not base64.
744. export fn hl_crypto_base64_decode(argc: u32, argv: [*]const HlValue) callconv(.c) HlValue {
745. const text = argString(argc, argv, 0) orelse
746. return api.makeError("hl:crypto fromBase64() expects a String");
747. // the padding goes, when the length says it is padding
748. var core = text;
749. if (core.len % 4 == 0) {
750. var pad: usize = 0;
751. while (pad < 2 and core.len > 0 and core[core.len - 1] == '=') : (pad += 1) core = core[0 .. core.len - 1];
752. }
753. if (core.len % 4 == 1) return api.makeNull();
754. const dec = std.base64.standard_no_pad.Decoder;
755. const n = dec.calcSizeForSlice(core) catch return api.makeNull();
756. const out = allocator.alloc(u8, n) catch
757. return api.makeError("hl:crypto fromBase64(): out of memory");
758. dec.decode(out, core) catch {
759. allocator.free(out);
760. return api.makeNull();
761. };
762. // canonical: encoding the result must give `core` back (the unused bits are zero)
763. const enc = std.base64.standard_no_pad.Encoder;
764. var chk: [4]u8 = undefined;
765. const tail = out.len % 3;
766. if (tail != 0) {
767. const again = enc.encode(&chk, out[out.len - tail ..]);
768. if (!std.mem.eql(u8, again, core[core.len - again.len ..])) {
769. allocator.free(out);
770. return api.makeNull();
771. }
772. }
773. return ownedString(out);
774. }