feat: add native scrypt password hashing

2026-07-13 19:35:38 +00:00
parent a288b539c6
commit 4414972079
11 changed files with 196 additions and 3 deletions
@@ -32,7 +32,7 @@ On Debian/Ubuntu-like systems, install the distro packages first:

 ```bash
 apt update
-apt install -y clang build-essential libpcre2-dev mariadb-client libmariadb-dev curl rsync ca-certificates
+apt install -y clang build-essential libpcre2-dev libssl-dev mariadb-client libmariadb-dev curl rsync ca-certificates
 ```

 UCE also requires two non-vendored dependencies. WASI SDK is load-bearing at runtime because UCE compiles units on demand during requests and during proactive startup scans. The `curl` binary is also a pinned runtime package dependency: `http_request()` and `http_request_async()` execute it directly with an explicit argument vector for TLS-capable outbound HTTP.
@@ -621,6 +621,22 @@ sock.close()
 PY
 ```

+## Password hashing
+
+Use the native password API for application credentials:
+
+```cpp
+String encoded = password_hash(password);
+if(encoded == "")
+	// fail the write; native hashing did not complete
+
+bool valid = password_verify(candidate, encoded);
+if(valid && password_needs_rehash(encoded))
+	encoded = password_hash(candidate);
+```
+
+`password_hash()` returns a self-contained `$uce$scrypt$...` encoding with a random 16-byte salt and the bounded scrypt parameters `N=65536`, `r=8`, `p=1`. `password_verify()` accepts only structurally valid encodings with bounded cost parameters and compares the derived key in constant time. `password_needs_rehash()` reports malformed, legacy, or non-current parameters so applications can upgrade a credential after a successful legacy verification. Treat an empty hash as an operational failure and never store it. Application-level password length policy, rate limiting, and legacy-format verification remain the application's responsibility.
+
 ## Operational footguns

 - Keep the FastCGI socket path consistent: `FCGI_SOCKET_PATH` and the web-server `fastcgi_pass` must match exactly. The reference config uses `/run/uce/fastcgi.sock`; if you choose `/run/uce.sock`, use it in both places.