From 40f95d079a23a13791c82d2a5783a517da0156af Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 23:30:06 +0000 Subject: [PATCH] docs: document matrixssl fork cmake policy --- AI.md | 43 +++++++++--- REDESIGN.md | 150 ++++++++++++++++++++++++++++-------------- TODO.md | 25 +++++++ third_party/README.md | 48 +++++++++----- 4 files changed, 190 insertions(+), 76 deletions(-) diff --git a/AI.md b/AI.md index 7177677..c25cd85 100644 --- a/AI.md +++ b/AI.md @@ -115,13 +115,14 @@ Secure IPC/TLS direction: - Client-facing NetWare 4.x/NCP/NDS compatibility must not require TLS by default. Keep historical clients compatible. -- LDAP/LDAPS/StartTLS for `nwdirectory` uses wolfSSL at the external LDAP edge. -- Internal provider IPC over TCP, if added later, must always use wolfSSL-backed - TLS with mutual authentication. No plaintext fallback for TCP provider IPC. +- LDAP/LDAPS/StartTLS for `nwdirectory` should use the `nwtls` facade with the selected GPL-2.0-compatible backend; MatrixSSL is the current preferred candidate. +- Internal provider IPC over TCP, if added later, must always use backend-backed + TLS with mutual authentication through `nwtls`. MatrixSSL is the current + preferred candidate; no plaintext fallback for TCP provider IPC. - Local IPC may remain Unix-domain sockets, pipes, socketpairs, or inherited FDs with strict permissions; still avoid logging decoded secrets. -- Add `nwtls` as the internal TLS facade if/when wolfSSL is wired into runtime: - `include/nwtls.h`, `src/nwtls.c`, `src/nwtls_wolfssl.c`. +- Add `nwtls` as the internal TLS facade if/when TLS is wired into runtime: + `include/nwtls.h`, `src/nwtls.c`, `src/nwtls_matrixssl.c`. Directory/NetWare 4.x direction: @@ -178,9 +179,10 @@ Logging direction: Third-party/fork policy: - Fixed third-party libraries live under `third_party/`, such as existing - `yyjson`, planned `wolfssl`, planned `libflaim`, and optional `zlog`. -- `wolfSSL` is the fixed bundled TLS implementation, similar in spirit to - `yyjson`. Do not design a first-pass OpenSSL/LibreSSL backend matrix. + `yyjson`, planned `matrixssl`, planned `libflaim`, and optional `zlog`. +- `MatrixSSL` is the preferred GPL-2.0-compatible crypto/TLS candidate and should + be imported as a maintained fork with a native CMake build if selected. Do + not design a first-pass OpenSSL/LibreSSL backend matrix. - `libflaim` should live under `third_party/libflaim` as a mars-nwe-maintained import/fork/mirror. Source may come from SourceForge/SVN and/or a distro source package such as openSUSE `libflaim-4.9.1046`. Document exact import, @@ -205,7 +207,7 @@ Third-party/fork policy: `tinyldap::storage`, and `tinyldap::server`. Replace flat-file storage with `libdirectory -> libflaim` later. - Old tinyldap TLS code can remain reference/legacy/standalone-only; mars-nwe - `nwdirectory` TLS should go through `nwtls`/wolfSSL. + `nwdirectory` TLS should go through `nwtls`/MatrixSSL once the backend is selected. Schema/import direction: @@ -1362,4 +1364,25 @@ Next patch number should be `0253`. or dependency documentation unless a separate explicit relicensing decision is made. -Next patch number should be `0265`. +## 2026-06-02 - Patch 0265 MatrixSSL fork/CMake policy + +- MatrixSSL is now the preferred GPL-2.0-compatible crypto/TLS candidate to + evaluate for the FLAIM CCS/NICI compatibility layer and possible future TLS + needs, instead of pulling OpenSSL into the tree. +- Treat MatrixSSL as a mars-nwe-maintained fork/import under + `third_party/matrixssl`, not as an opaque system probe and not as a source tree + built by its original Makefiles. +- The import must document the exact upstream/fork URL, revision, license terms, + any local patches, and the reason it is GPL-2.0-compatible with mars-nwe. +- Add a native CMake build in the MatrixSSL fork. It must work standalone and as + a mars-nwe subdirectory, and should expose normal targets such as + `MATRIXSSL::crypto` and, if TLS is built, `MATRIXSSL::tls`. +- FLAIM must not call MatrixSSL directly. FLAIM still talks to the future + CCS/NICI compatibility layer; that layer may use MatrixSSL crypto primitives + underneath. +- Keep old OpenSSL-facing FLAIM/FTK code disabled by default. Do not introduce + OpenSSL as a default mars-nwe dependency. +- Do not mix MatrixSSL import/CMake work with FLAIM CCS/NICI implementation or + source tree layout changes in the same patch. + +Next patch number should be `0266`. diff --git a/REDESIGN.md b/REDESIGN.md index 0dd5dee..a595805 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -611,7 +611,7 @@ from the caller to the provider. This also fits the secure IPC policy: local direct IPC can use protected Unix-domain sockets, pipes, or inherited descriptors. If a future provider is connected over TCP instead, that specific provider IPC channel must use the -separate wolfSSL/mTLS policy described below. `nwserv` discovery must not be used +separate MatrixSSL/mTLS policy described below. `nwserv` discovery must not be used as an excuse to downgrade provider data-plane traffic to plaintext TCP. @@ -639,7 +639,7 @@ local provider IPC: process ownership, and socket directories are strict. TCP-based provider IPC: - never plaintext; wolfSSL-backed TLS with mutual authentication is required. + never plaintext; MatrixSSL-backed TLS with mutual authentication is required. ``` So the local default may remain simple and compatible: @@ -655,7 +655,7 @@ container boundary, must be treated as a secure channel: ```text nwconn -> provider over TCP: - wolfSSL required + MatrixSSL required mutual authentication required no anonymous TLS no opportunistic downgrade to plaintext @@ -671,10 +671,10 @@ Client NCP/NDS transport: compatibility first; no blanket TLS requirement for classic clients. LDAP/LDAPS/StartTLS: - handled by nwdirectory; wolfSSL is appropriate at that network edge. + handled by nwdirectory; MatrixSSL is appropriate at that network edge. Internal provider IPC over TCP: - always wolfSSL/mTLS because decoded server-internal data may cross it. + always MatrixSSL/mTLS because decoded server-internal data may cross it. ``` Local IPC still needs security rules even without TLS: @@ -689,7 +689,7 @@ Local IPC still needs security rules even without TLS: - formal handoff logging should record selector paths, provider names, reply kinds, and completion codes, not raw secret bytes. -This also means there are two different wolfSSL uses in the long-term design: +This also means there are two different MatrixSSL-backed TLS uses in the long-term design: ```text 1. LDAP TLS: @@ -1163,7 +1163,7 @@ directory core/store nwdirectory mars-nwe service name for the integrated tinyldap-derived LDAP service owns LDAP/LDAPS/StartTLS protocol handling - uses wolfSSL only at the LDAP network/TLS edge + uses MatrixSSL only at the LDAP network/TLS edge calls the directory core/store, not Bindery or NDS packet handlers nwnds @@ -1232,7 +1232,7 @@ The preferred relationship is sibling frontends above one core: | | nwdirectory nwnds tinyldap-based LDAP/LDAPS NetWare 4.x/NDS semantics - frontend, wolfSSL TLS edge NCP/NDS compatibility layer + frontend, MatrixSSL TLS edge NCP/NDS compatibility layer ^ ^ | | LDAP clients NetWare/NDS clients @@ -1487,8 +1487,8 @@ The migration path should be conservative: 1. add the design boundary and naming notes first; 2. import or integrate tinyldap under the project-facing `nwdirectory` name; -3. keep client-facing wolfSSL usage confined to the LDAP/LDAPS/StartTLS - network edge initially; internal TCP-based provider IPC may also use wolfSSL +3. keep client-facing MatrixSSL usage confined to the LDAP/LDAPS/StartTLS + network edge initially; internal TCP-based provider IPC may also use MatrixSSL later, but only as a separate mTLS configuration; 4. introduce `libdirectory` before making Bindery depend on it; 5. add `nwsetup` as the direct bootstrap/provisioning tool for the initial @@ -1541,6 +1541,11 @@ third_party/libflaim mars-nwe-maintained import/fork of the FLAIM source converted to a real standalone-and-subdirectory CMake build +third_party/matrixssl + planned mars-nwe-maintained fork/import of a GPL-2.0-compatible MatrixSSL tree + candidate crypto/TLS backend for the FLAIM CCS/NICI compatibility layer + converted to a native standalone-and-subdirectory CMake build + third_party/zlog optional advanced logging backend used only through nwlog @@ -1608,40 +1613,34 @@ Do not introduce GPLv3 code into this dependency path. If a later libowfat bump or replacement is considered, review the license and make that a separate third-party update patch. -### TLS dependency rule +### TLS/crypto dependency rule -wolfSSL should be the fixed TLS implementation shipped with the tree, similar in -spirit to the bundled yyjson dependency. Do not design the first TLS integration -as an abstract zoo of OpenSSL, LibreSSL, wolfSSL, and other providers. wolfSSL is -portable and can be configured through CMake for the needs of the target server, -so it should be the implementation used for: +The current GPL-2.0-only direction is to avoid OpenSSL and evaluate a +GPL-2.0-compatible MatrixSSL fork as the preferred crypto/TLS candidate. Earlier +wolfSSL-oriented notes should be treated as superseded for new dependency work +unless a later patch deliberately reopens that choice with a pinned +GPL-2.0-compatible wolfSSL revision or a commercial license. -- LDAP/LDAPS/StartTLS at the `nwdirectory` network edge; -- any future TCP-based internal provider IPC, where wolfSSL-backed mTLS is - required; -- future TLS-capable admin or service endpoints, if they are explicitly added. - -However, mars-nwe code should still not include wolfSSL headers everywhere. TLS -call sites should go through a small internal facade: +TLS call sites should still go through a small internal facade instead of using a +third-party TLS API directly: ```text include/nwtls.h src/nwtls.c -src/nwtls_wolfssl.c +src/nwtls_matrixssl.c ``` -The facade is not meant to promise equal OpenSSL/LibreSSL support. Its purpose -is to keep certificate loading, policy checks, mTLS requirements, error logging, -secure defaults, and wolfSSL-specific setup in one place. If another TLS backend -is ever evaluated much later, it can be hidden behind the same API, but the -planned bundled backend is wolfSSL. +The facade is not meant to promise equal OpenSSL/LibreSSL/wolfSSL support. Its +purpose is to keep certificate loading, policy checks, mTLS requirements, error +logging, secure defaults, and backend-specific setup in one place. The planned +GPLv2-friendly backend candidate is MatrixSSL. Protocol handlers and provider code should therefore use `nwtls` concepts, not -raw wolfSSL types. Example ownership: +raw MatrixSSL types. Example ownership: ```text -nwdirectory LDAP listener -> nwtls -> wolfSSL -provider TCP IPC -> nwtls -> wolfSSL/mTLS +nwdirectory LDAP listener -> nwtls -> MatrixSSL +provider TCP IPC -> nwtls -> MatrixSSL/mTLS nwlog/security logging -> logs TLS events, never private key material ``` @@ -1650,6 +1649,59 @@ not. The config may point at certificate/key files, while `nwsetup` should be able to generate or validate local defaults. Private keys and provider mTLS credentials must live in protected directories with strict permissions. +### MatrixSSL fork/CMake rule + +`MatrixSSL` should be evaluated as the preferred GPL-2.0-compatible crypto/TLS +candidate for the FLAIM CCS/NICI compatibility layer and any later TLS work that +needs a GPLv2-friendly backend. It should not be consumed as a random system +library. If selected, mars-nwe should carry a maintained fork/import under: + +```text +third_party/matrixssl +``` + +The import must record the exact upstream or fork URL, revision, license terms, +local patches, and why the pinned source is compatible with mars-nwe's +GPL-2.0-only policy. Do not silently track a moving branch. + +The MatrixSSL fork must gain a native CMake build. Do not keep the original +Makefiles as the long-term build path and do not shell out to them from the main +mars-nwe build. The expected shape is: + +```text +standalone: + cmake -S third_party/matrixssl -B build-matrixssl + +inside mars-nwe: + add_subdirectory(third_party/matrixssl) +``` + +Expose normal targets. The exact names may be adjusted during import, but the +intended split is: + +```text +MATRIXSSL::crypto # crypto primitives used by CCS/NICI compat +MATRIXSSL::tls # TLS layer, only if/when mars-nwe needs it +``` + +FLAIM should still not include MatrixSSL headers directly. The intended layering +is: + +```text +libflaim -> CCS/NICI compatibility layer -> MatrixSSL crypto backend +``` + +This keeps the FLAIM port compatible with its original NICI/CCS expectations and +lets mars-nwe replace or audit the backend without editing FLAIM call sites. The +same rule applies to future `nwdirectory`/`libdirectory` code: it should call the +mars-nwe directory/crypto facade, not MatrixSSL APIs directly. + +Old FLAIM/FTK OpenSSL-facing network code should remain disabled by default. If +it must be kept for source compatibility, isolate it inside the FLAIM import and +keep OpenSSL out of the public mars-nwe dependency policy. MatrixSSL import and +CMake conversion must be separate from the later FLAIM CCS/NICI implementation, +so each patch stays mechanical and reviewable. + ### zlog dependency rule `zlog` should be treated as an optional advanced logging backend under @@ -1728,27 +1780,23 @@ matter for the required targets. Examples from the inspected tree include pthread support, large-file support, selected POSIX headers/functions, optional ncurses/rt checks for utilities, debug defines such as `FLM_DEBUG`, and platform defines such as `OSX`. OpenSSL support in FTK should not become a new TLS -direction for mars-nwe; TLS policy remains wolfSSL through the `nwtls` facade. +direction for mars-nwe; TLS policy remains MatrixSSL through the `nwtls` facade. If any old FLAIM crypto/TLS-related option is required for building, it must be reviewed separately and kept isolated from mars-nwe provider IPC and LDAP TLS policy. If the FLAIM source cannot be built cleanly without old OpenSSL-facing code, the preferred fallback is still not to introduce a general OpenSSL/LibreSSL backend -matrix. A narrowly scoped CMake option may use wolfSSL's OpenSSL-compatibility -headers only inside `third_party/libflaim`, for example: +matrix. First disable the old FTK TLS-facing code for the required +`FLAIM::ftk`/`FLAIM::flaim` targets. If a legacy path is unavoidable, keep the +patch inside `third_party/libflaim` and use a narrow shim or source adjustment; +do not expose OpenSSL-compatible types outside the FLAIM/FTK build and do not +make LDAP/provider IPC use OpenSSL APIs. -```text -FLAIM_USE_WOLFSSL_OPENSSL_COMPAT=ON/OFF/AUTO -``` - -That option would be an import/portability bridge for FLAIM only. It must not -change the mars-nwe TLS policy, expose OpenSSL-compatible types outside the -FLAIM/FTK build, or make LDAP/provider IPC use OpenSSL APIs. If possible, the -classic `FLAIM::ftk` and `FLAIM::flaim` targets should disable old TLS-facing -code entirely. If crypto primitives are required, prefer a small private shim in -the FLAIM build over leaking wolfSSL/OpenSSL-compat headers into `libdirectory`, -`nwbind`, `nwdirectory`, or future `nwnds` code. +If crypto primitives are required by Flaim storage encryption, implement them via +the CCS/NICI compatibility layer backed by MatrixSSL crypto primitives, not by +including MatrixSSL/OpenSSL-style headers in `libdirectory`, `nwbind`, +`nwdirectory`, or future `nwnds` code. FLAIM is C++ code. That is acceptable, but its C++ API must not leak into the old mars-nwe C code. `nwbind`, future `nwnds`, `nwdirectory`, and `nwsetup` @@ -1768,7 +1816,7 @@ equivalent note listing: ### Forked tinyldap / nwdirectory rule -`tinyldap` is different from yyjson, wolfSSL, zlog, and libflaim. It is not a +`tinyldap` is different from yyjson, MatrixSSL, zlog, and libflaim. It is not a small library dependency and it is not merely a storage engine. It becomes the LDAP service component used by mars-nwe, so it follows the existing root-level component pattern used by `admin`, `dosutils`, `mail`, and `smart`. @@ -1784,7 +1832,7 @@ mars-nwe-specific work: - a real CMake build, not only the original Makefile; - standalone tinyldap build support under the tinyldap name; - mars-nwe subdirectory build support producing the `nwdirectory` service; -- LDAP/LDAPS/StartTLS integration through `nwtls`/wolfSSL; +- LDAP/LDAPS/StartTLS integration through `nwtls`/MatrixSSL; - replacement or bypass of the original flat-file storage; - later `libdirectory` and libflaim-backed storage integration; - directory schema, bootstrap, and setup integration through `nwsetup`. @@ -1821,7 +1869,7 @@ needs them. The original tinyldap TLS code (`tinytls.h`, `tls_*.c`, `fmt_tls_*.c`, and `init_tls_context.c`) should not become the long-term TLS stack for mars-nwe. Keep it as reference material or disable it in the integrated build. The -project-facing `nwdirectory` service should use `nwtls` backed by wolfSSL for +project-facing `nwdirectory` service should use `nwtls` backed by MatrixSSL for LDAPS/StartTLS, while the standalone tinyldap build may temporarily keep legacy TLS behavior only if it is isolated behind CMake options and does not leak into mars-nwe's TLS policy. @@ -1896,7 +1944,7 @@ WITH_TCP=ON/OFF future client-facing TCP/IP transport ``` Conservative builds should still be able to disable incomplete future components, -but once a feature requires TLS, its supported TLS implementation is wolfSSL. +but once a feature requires TLS, its supported TLS implementation is MatrixSSL. ## Configuration redesign and future typed INI files @@ -2050,7 +2098,7 @@ setup/write path: ``` This keeps the old `nw.ini` compatibility path alive while giving NetWare 4.x, -`nwdirectory`, `nwnds`, libflaim-backed storage, wolfSSL TLS, and future +`nwdirectory`, `nwnds`, libflaim-backed storage, MatrixSSL TLS, and future transport settings a configuration format that can be understood and edited by a human. diff --git a/TODO.md b/TODO.md index 20c57ab..b90c69c 100644 --- a/TODO.md +++ b/TODO.md @@ -204,6 +204,31 @@ Follow-up: - Keep such consumers explicit and reviewed; do not add libowfat includes to unrelated switch dispatch code merely because the dependency is bundled. + +#### MatrixSSL fork/CMake candidate for Flaim CCS/NICI + +Current status: + +- Patch `0265` records MatrixSSL as the preferred GPL-2.0-compatible crypto/TLS + candidate to evaluate for the FLAIM CCS/NICI compatibility layer. +- MatrixSSL should be a mars-nwe-maintained fork/import under + `third_party/matrixssl`, not a moving system dependency and not an original + Makefile wrapper. +- The first intended consumer is the future CCS/NICI compatibility layer used by + libflaim encryption code. FLAIM should continue to call CCS/NICI-style APIs; + MatrixSSL belongs underneath that compatibility layer. + +Follow-up: + +- Pick and pin the exact MatrixSSL upstream/fork revision. +- Import the tree under `third_party/matrixssl` in its own dependency patch. +- Add `third_party/matrixssl/README.mars-nwe.md` documenting source, revision, + license, local patches, disabled legacy pieces, and CMake targets. +- Add a native CMake build exposing at least `MATRIXSSL::crypto`; add + `MATRIXSSL::tls` only if TLS code is kept and builds cleanly. +- Keep MatrixSSL import separate from the later FLAIM CCS/NICI implementation. +- Keep OpenSSL disabled/out of the default dependency path. + #### Source/header subtree layout migration Current status: diff --git a/third_party/README.md b/third_party/README.md index 8a53d6e..4f8cee7 100644 --- a/third_party/README.md +++ b/third_party/README.md @@ -55,25 +55,43 @@ Relevant libowfat areas for tinyldap are expected to include `byte`, `buffer`, `fmt`, `scan`, `str`, `stralloc`, `uint`, `open`, `socket`, and possibly `io` or `cdb`, depending on how much of the original tinyldap code is kept. -## Planned: wolfSSL +## Superseded candidate: wolfSSL -wolfSSL is the planned fixed TLS implementation for mars-nwe. It should be -added as `third_party/wolfssl` and configured by CMake for the server's supported -platforms and enabled TLS features. +wolfSSL was previously considered as the fixed TLS implementation. For the +current GPL-2.0-only dependency direction, MatrixSSL is the preferred candidate +to evaluate first. Do not import wolfSSL by default. It may only be reconsidered +in a later explicit dependency-review patch that pins a GPL-2.0-compatible +release or documents a commercial-license path. -mars-nwe code should not include wolfSSL headers directly from arbitrary -subsystems. TLS users should go through the future `include/nwtls.h` facade and -its wolfSSL backend, for example: +## Planned: MatrixSSL + +MatrixSSL is the planned GPL-2.0-compatible crypto/TLS candidate to evaluate for +the future FLAIM CCS/NICI compatibility layer and possible later TLS needs. If +adopted, it should live under `third_party/matrixssl` as a mars-nwe-maintained +fork/import with a pinned upstream/fork revision and explicit license notes. + +The MatrixSSL import must not rely on the original Makefiles as the long-term +mars-nwe build path. Add a native CMake build that works both standalone and as +a mars-nwe subdirectory. Expected targets are along these lines: ```text -include/nwtls.h -src/nwtls.c -src/nwtls_wolfssl.c +MATRIXSSL::crypto +MATRIXSSL::tls ``` -Planned uses include LDAP/LDAPS/StartTLS in `nwdirectory` and any future -TCP-based internal provider IPC that requires mTLS. +`MATRIXSSL::crypto` is the important first target for a Flaim CCS/NICI compat +backend. `MATRIXSSL::tls` may remain disabled until a real mars-nwe TLS consumer +needs it. +FLAIM should not call MatrixSSL APIs directly. Keep the layering as: + +```text +libflaim -> CCS/NICI compatibility layer -> MatrixSSL crypto backend +``` + +OpenSSL remains out of the default dependency policy. Any old FLAIM/FTK +OpenSSL-facing network code should be disabled or isolated inside the FLAIM +import, not exposed to mars-nwe modules. ## Planned: libflaim @@ -96,8 +114,8 @@ project and as a mars-nwe subdirectory, exposing normal CMake targets. If old FLAIM/FTK code requires OpenSSL-facing build paths, prefer disabling those paths for the initial classic `FLAIM::flaim` target. If a compatibility bridge is unavoidable, it should be a private `third_party/libflaim` CMake option using -wolfSSL's OpenSSL-compatible headers, not a new public OpenSSL/LibreSSL TLS -backend for mars-nwe. +a private shim/source adjustment inside the FLAIM import, not a new public +OpenSSL/LibreSSL TLS backend for mars-nwe. The first required targets are expected to be: @@ -148,4 +166,4 @@ test utilities. The mars-nwe CMake conversion should split those groups into explicit libraries/targets instead of preserving the old monolithic `all` target. The original tiny TLS code should be disabled or isolated for the integrated `nwdirectory` target; LDAP/LDAPS/StartTLS in mars-nwe should use `nwtls` backed -by wolfSSL. +by MatrixSSL.