From 0187bb60cf4b5c8ae439f4b2d4cd6bc82945b3c2 Mon Sep 17 00:00:00 2001 From: udo Date: Mon, 13 Jul 2026 19:47:06 +0000 Subject: [PATCH] docs: publish password hashing APIs --- scripts/api_coverage_manifest.py | 4 +++- scripts/test_password_hashing.sh | 7 +++++-- site/doc/areas/noise.txt | 3 +++ site/doc/pages/password_hash.txt | 18 ++++++++++++++++++ site/doc/pages/password_needs_rehash.txt | 18 ++++++++++++++++++ site/doc/pages/password_verify.txt | 20 ++++++++++++++++++++ 6 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 site/doc/pages/password_hash.txt create mode 100644 site/doc/pages/password_needs_rehash.txt create mode 100644 site/doc/pages/password_verify.txt diff --git a/scripts/api_coverage_manifest.py b/scripts/api_coverage_manifest.py index 292df71..a4e73a1 100755 --- a/scripts/api_coverage_manifest.py +++ b/scripts/api_coverage_manifest.py @@ -37,7 +37,9 @@ PUBLIC_APIS = [ ("to_json", False, "public"), ("remove", False, "public"), ("clear", False, "public"), ("gen_sha1", True, "public"), ("sha256", True, "public"), ("sha256_hex", True, "public"), ("hmac_sha256", True, "public"), ("hmac_sha256_hex", True, "public"), ("random_bytes", True, "public"), - ("crypto_equal", True, "public"), ("gen_noise32", True, "public"), ("gen_noise64", True, "public"), + ("crypto_equal", True, "public"), ("password_hash", True, "public"), + ("password_verify", True, "public"), ("password_needs_rehash", True, "public"), + ("gen_noise32", True, "public"), ("gen_noise64", True, "public"), ("gen_noise01", True, "public"), ("gen_int", True, "public"), ("gen_float", True, "public"), ("draw_int", True, "public"), ("draw_float", True, "public"), ("encode_query", True, "public"), ("csrf_token", True, "public"), diff --git a/scripts/test_password_hashing.sh b/scripts/test_password_hashing.sh index 17bfc90..708bb9e 100755 --- a/scripts/test_password_hashing.sh +++ b/scripts/test_password_hashing.sh @@ -25,11 +25,14 @@ cache_dir="$bin_directory$(realpath "$source_dir")" printf '%s\n' \ 'CLI(Request& context) {' \ ' String encoded = password_hash("correct horse battery staple");' \ - ' print(encoded, "\n", password_verify("correct horse battery staple", encoded) ? "valid" : "invalid", "\n", password_verify("wrong password", encoded) ? "wrong-valid" : "wrong-rejected", "\n", password_needs_rehash(encoded) ? "rehash" : "current", "\n", password_verify("password", "$uce$scrypt$999999999$8$1$00$00") ? "malformed-valid" : "malformed-rejected");' \ + ' String second = password_hash("correct horse battery staple");' \ + ' String weaker = "$uce$scrypt$16384$8$1$00112233445566778899aabbccddeeff$29fdfb3d991961e926a19c1136a07e252afa5fdb8d3a0fb74cdcfa5016956f34";' \ + ' String excessive = "$uce$scrypt$131072$8$1$00112233445566778899aabbccddeeff$0000000000000000000000000000000000000000000000000000000000000000";' \ + ' print(encoded, "\n", encoded != second ? "randomized" : "reused", "\n", password_verify("correct horse battery staple", encoded) ? "valid" : "invalid", "\n", password_verify("wrong password", encoded) ? "wrong-valid" : "wrong-rejected", "\n", password_needs_rehash(encoded) ? "rehash" : "current", "\n", password_verify("legacy password", weaker) && password_needs_rehash(weaker) ? "legacy-valid-rehash" : "legacy-failed", "\n", !password_verify("password", excessive) && password_needs_rehash(excessive) ? "excessive-rejected" : "excessive-accepted", "\n", !password_verify("password", "$uce$scrypt$65536$8$1$zz$00") && password_needs_rehash("malformed") ? "malformed-rejected" : "malformed-valid");' \ '}' >"$source_dir/test.uce" output=$(scripts/uce-cli "/$test_name/test.uce") -if [[ "$output" != *'$uce$scrypt$65536$8$1$'* || "$output" != *$'\nvalid\nwrong-rejected\ncurrent\nmalformed-rejected'* ]]; then +if [[ "$output" != *'$uce$scrypt$65536$8$1$'* || "$output" != *$'\nrandomized\nvalid\nwrong-rejected\ncurrent\nlegacy-valid-rehash\nexcessive-rejected\nmalformed-rejected'* ]]; then echo "native password hashing failed: $output" >&2 exit 1 fi diff --git a/site/doc/areas/noise.txt b/site/doc/areas/noise.txt index 2d231d1..081448f 100644 --- a/site/doc/areas/noise.txt +++ b/site/doc/areas/noise.txt @@ -14,3 +14,6 @@ hmac_sha256 hmac_sha256_hex random_bytes crypto_equal +password_hash +password_verify +password_needs_rehash diff --git a/site/doc/pages/password_hash.txt b/site/doc/pages/password_hash.txt new file mode 100644 index 0000000..ffe2411 --- /dev/null +++ b/site/doc/pages/password_hash.txt @@ -0,0 +1,18 @@ +:sig +String password_hash(String password) + +:params +password : password bytes to hash +return value : self-contained scrypt encoding, or an empty string on failure + +:content +Creates a password credential with a cryptographically random salt and UCE's current bounded scrypt parameters. Store the returned encoding exactly as produced. An empty result means hashing failed; abort the credential write and report an operational error instead of storing it. + +:example +String encoded = password_hash("correct horse battery staple"); +print(encoded != "" && password_verify("correct horse battery staple", encoded) ? "valid" : "failed", "\n"); + +:see +>sys +password_verify +password_needs_rehash diff --git a/site/doc/pages/password_needs_rehash.txt b/site/doc/pages/password_needs_rehash.txt new file mode 100644 index 0000000..1072a7c --- /dev/null +++ b/site/doc/pages/password_needs_rehash.txt @@ -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 diff --git a/site/doc/pages/password_verify.txt b/site/doc/pages/password_verify.txt new file mode 100644 index 0000000..a0be837 --- /dev/null +++ b/site/doc/pages/password_verify.txt @@ -0,0 +1,20 @@ +:sig +bool password_verify(String password, String encoded) + +:params +password : candidate password bytes +encoded : self-contained `$uce$scrypt$...` credential +return value : true only when the password matches a structurally valid, bounded encoding + +:content +Derives the candidate with the parameters embedded in `encoded` and compares the result in constant time. Malformed encodings and parameters above UCE's accepted memory/work policy are rejected before derivation. Apply application-level password length limits and rate limiting around public authentication endpoints. + +:example +String encoded = password_hash("correct horse battery staple"); +print(password_verify("correct horse battery staple", encoded) ? "valid" : "invalid", " / "); +print(password_verify("wrong password", encoded) ? "valid" : "invalid", "\n"); + +:see +>sys +password_hash +password_needs_rehash