components

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