diff options
Diffstat (limited to 'docs/CHAT-CRYPTO.txt')
| -rw-r--r-- | docs/CHAT-CRYPTO.txt | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/docs/CHAT-CRYPTO.txt b/docs/CHAT-CRYPTO.txt new file mode 100644 index 0000000..fa9fa1a --- /dev/null +++ b/docs/CHAT-CRYPTO.txt @@ -0,0 +1,170 @@ +Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai> + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. + +CHAT CRYPTOGRAPHY AND BUILDS + + Application formats, authentication, recovery and security limits: + CHAT-APPLICATION.txt. Static native packaging and deployment: + CHAT-PRODUCTION.txt. Functional compatibility is not a cryptographic, + side-channel or application security audit. + +FIXED ALGORITHMS AND BACKEND + + Sequoia OpenPGP 2.4.2, RFC 9980 ML-KEM-1024 + X448 encryption, + ML-DSA-87 + Ed448 signatures, OpenPGP v6 keys, AES-256 content encryption. + Only crypto-openssl is enabled; no algorithm substitution, experimental/ + variable-time backend opt-in, or ignored RustSec advisory. Native and browser + probes require the OpenSSL backend and expected key algorithms. + + The superseded Rust backend's required curve arithmetic depended on an + incompatible crypto-bigint generation affected by RUSTSEC-2026-0387. + OpenSSL avoids that dependency; the resolved graph has no cx448, + crypto-bigint or rsa crate. This does not prove absence of C defects or + browser side channels. See https://rustsec.org/advisories/RUSTSEC-2026-0387.html. + +SOURCE PROVENANCE + + Rust: rust-toolchain.toml. Sequoia: exact Cargo.toml requirement/Cargo.lock. + OpenSSL: 3.6.5. WASI SDK: 34.0 x86_64 Linux, bundled Clang/libclang + 23.1.0-wasi-sdk. Browser tooling: package.json/package-lock.json. + + WASI SDK archive: + https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-34/wasi-sdk-34.0-x86_64-linux.tar.gz + SHA-256 b761e3a0721dbae9c09a0059e5fdb2bf917d1b4a8a7b430fb3b5aafb0984b2c4 + + OpenSSL archive: + https://github.com/openssl/openssl/releases/download/openssl-3.6.5/openssl-3.6.5.tar.gz + SHA-256 a2157c2830efdec3788939b00c9b0638306d3f0bbb76dc4832ee503bb397df98 + + Build scripts verify these digests before extraction. Pinned hashes do not + independently verify upstream signatures or promise cross-host identical + binaries. Sources, SDK and static libraries stay under ignored .tools/; + Cargo output stays under target/. Native development uses the host library; + production static native builds use the verified source, CHAT-PRODUCTION.txt. + +WASI BUILD AND ENTROPY + + infra/chat/openssl-wasi.conf adds a BASE_unix target with little-endian, + 32-bit bignums. C uses -O2; no cryptographic routine or RNG patch is applied. + OpenSSL's --with-rand-seed=getrandom reaches WASI random_get through libc. + The browser bridge uses only crypto.getRandomValues, splitting requests + at 65536 bytes. Entropy failures reject; no fixed seed or success fallback. + The browser probe includes a failing-entropy negative control. + + Static WASI builds disable assembly, async operations, automatic config + loading, DSO/modules, POSIX I/O, secure-memory arenas, shared libraries, + sockets, C stdio, thread pools, threads and interactive console UI. + Ordinary WASM memory provides no locked-page, secure-erasure or delivered- + JavaScript protection. OpenSSL uses C/FFI; first-party Rust unsafe-code + prohibition does not make dependencies memory-safe. + + _WASI_EMULATED_GETPID and libwasi-emulated-getpid supply process-ID emulation. + getuid/geteuid/getgid/getegid map to getpagesize. These values provide neither + entropy nor identity credentials; there is no real OS user/privilege boundary. + This portability mapping does not emulate general POSIX security. + + Bindgen uses SDK libclang/sysroot, wasm32-wasip1 and -fvisibility=default + so declarations remain available. Rust's bundled WASI libc precedes SDK + libraries to resolve __wasi_init_tp; SDK libraries supply emulated-getpid. + Generated cryptographic bindings are not edited. The linker caps WASM linear + memory at 256 MiB; browser/host copies add overhead. + +BROWSER CAPABILITIES + + crates/chat-crypto/browser/wasi.ts supplies clocks, browser CSPRNG, empty + arguments/environment, in-memory request stdin and captured stdout/stderr. + Empty stdin runs the compatibility probe; application commands use JSON. + Requests exceeding 8388608 JavaScript string units are rejected; combined + stdout/stderr exceeding 1048576 string units abort execution. + + No real files, preopened directories, sockets or process launch are supplied. + Filesystem/network access is refused; unknown imports fail before + instantiation. The application runs crypto in one-shot + workers with a timeout; CHAT-APPLICATION.txt documents memory/state limits. + + Capability denials prevent accidental host storage/network access, not + malicious JavaScript from the same server. Memory, clocks, randomness and + bridge imports remain trusted. Browsers/OSes can retain memory, caches, + crash dumps, swap and restored state; no complete erasure is guaranteed. + +DEPENDENCY EXCEPTIONS + + deny.toml allows only exact older duplicate versions; advisory/license + checks still apply. No RustSec ignore. Wildcards, unknown Git/registry sources + and unreviewed duplicates remain rejected. Cargo.lock pins both API lines: + + block-buffer 0.10.4 vs 0.12.1 + crypto-common 0.1.7 vs 0.2.2 + digest 0.10.7 vs 0.11.3 + Sequoia's Argon2 0.5.3 -> BLAKE2 0.10 needs the older digest API; + root SHA-256 and parser-generator SHA3 use the newer API. + cpufeatures 0.2.17 vs 0.3.1 + Argon2 uses 0.2; root SHA-256/parser-generator SHA3 use 0.3. + generic-array 0.14.7 vs 1.4.5 + Argon2/BLAKE2 digest uses 0.14; SHA1 collision detection uses 1.x. + getrandom 0.2.17 vs 0.4.3 + Sequoia's unknown-unknown WASM dependencies declare 0.2; root + tempfile uses 0.4. Browser WASI uses OpenSSL/bridge entropy. + Audit the all-target graph rather than excluding this edge. + hashbrown 0.15.5 vs 0.17.1 + Parser-generator petgraph uses 0.15; its indexmap 2.14 uses 0.17. + itertools 0.13.0 vs 0.15.0 + shlex 1.3.0 vs 2.0.1 + Bindgen uses older APIs; lalrpop and cc require newer ones. + syn 2.0.119 vs 3.0.9 + Bindgen/prettyplease and Windows support use syn 2; root derives + and other dependencies use syn 3. Unification needs upstream API + migration or unrelated downgrades, not a lockfile update. + + Build dependencies remain audited. Clippy's name-only exceptions for + generic-array/getrandom/syn do not replace exact cargo-deny checks. + LINTING.txt documents the lint policy. + +EXTERNAL LIBRARIES AND LICENSES + + cargo-deny does not audit external OpenSSL C or the SDK. Review separately: + https://openssl-library.org/news/timeline/ + https://openssl-library.org/news/vulnerabilities-3.6/ + A Rust audit does not guarantee the pinned C version's future security. + Updates require upstream advisory review, every affected URL/hash, + native/WASI rebuilds, both browsers, cargo-deny, regenerated notices/sources + and release recovery. Never waive advisories to pass. + + libloading used by bindgen/clang has a package-scoped ISC allowance. + cargo-about covers workspace Rust licenses, not external C/SDK obligations. + Distributed OpenSSL/SDK artifacts retain their required licenses/sources; + OpenSSL LICENSE.txt is Apache-2.0. Rust notices alone are insufficient. + Corresponding sources include the unmodified OpenSSL archive; toolchain + declarations/download locations remain public. + +BUILD AND CHECK FROM THE STACK ROOT + + Native development: OpenSSL >=3.5 headers/library, libclang, pkg-config, + C compiler and pinned Rust. WASI cross-build: x86_64 GNU/Linux, Perl, make, + curl, tar, sha256sum. Browser tooling/install instructions: TYPESCRIPT.txt. + + cargo test --locked -p stack-chat-crypto + cargo run --locked -p stack-chat-crypto + sh infra/chat/build-openssl-wasi.sh + npm run build + PLAYWRIGHT_BROWSERS_PATH="$PWD/.tools/browsers" npm run test:crypto + cargo stack check + + The WASI script builds verified OpenSSL into .tools/openssl-wasi, links the + Rust WASI command and prints its SHA-256. Rust-only edits may reuse inputs + with sh infra/chat/build-browser.sh; source/version/configuration/flag changes + require an OpenSSL rebuild. Extracted sources can be reused; independent + verification needs a fresh ignored tools/build tree. Native and browser + probe results must explicitly identify the OpenSSL backend. |