mars_nwe/mars-nwe
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 2 Wiki Activity

docs: document matrixssl fork cmake policy

Browse Source
This commit is contained in:
Mario Fetka
2026-06-02 23:30:06 +00:00
parent f8317503df
commit 40f95d079a
4 changed files with 190 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
AI.md
View File

@@ -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`.

150
REDESIGN.md
View File

@@ -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.

25
TODO.md
View File

@@ -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:

48
third_party/README.md vendored
View File

@@ -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.