docs: publish password hashing APIs

2026-07-13 19:47:06 +00:00
parent 4414972079
commit 0187bb60cf
6 changed files with 67 additions and 3 deletions
@@ -0,0 +1,18 @@
+:sig
+bool password_needs_rehash(String encoded)
+
+:params
+encoded : stored password credential
+return value : true when the encoding is malformed or does not use UCE's current parameters
+
+:content
+Checks whether a stored UCE password encoding should be replaced. Call it only after successful verification, then hash the known-correct password again and atomically replace the old credential. Non-UCE legacy formats are reported as needing rehash but must be verified by the application before upgrade.
+
+:example
+String old = "$uce$scrypt$16384$8$1$00112233445566778899aabbccddeeff$29fdfb3d991961e926a19c1136a07e252afa5fdb8d3a0fb74cdcfa5016956f34";
+print(password_verify("legacy password", old) && password_needs_rehash(old) ? "upgrade" : "keep", "\n");
+
+:see
+>sys
+password_hash
+password_verify