From a262caba33a7fc25ffccf0519aaf54bae20946c7 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Wed, 3 Jun 2026 04:09:35 +0000 Subject: [PATCH] docs: document shared library layering plan --- AI.md | 34 +++++++++++++++++++- REDESIGN.md | 75 +++++++++++++++++++++++++++++++++++++++---- TODO.md | 27 ++++++++++++++++ third_party/README.md | 24 +++++++++----- 4 files changed, 144 insertions(+), 16 deletions(-) diff --git a/AI.md b/AI.md index c25cd85..cc8d20f 100644 --- a/AI.md +++ b/AI.md @@ -1385,4 +1385,36 @@ Next patch number should be `0253`. - 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`. +## 2026-06-02 - Patch 0266 shared library layering for MatrixSSL, FLAIM, and directory services + +- The third-party storage/crypto plan now uses mars-nwe-named shared library + layers, not raw upstream target names as public project interfaces. +- `libnwmatrixssl` is the patched MatrixSSL fork/library. It exists only to make + the GPL-2.0-compatible MatrixSSL source build cleanly under mars-nwe CMake and + to avoid collisions with any system MatrixSSL package. Keep local changes + limited to portability, naming, CMake, and build hygiene unless a later + security/compatibility patch explicitly says otherwise. +- `libnwssl` is the mars-nwe SSL/crypto facade. It owns the MatrixSSL-facing + wrappers, future TLS abstraction used by apps/services, and the CCS/NICI + compatibility layer that FLAIM needs. Application code should include/use + `libnwssl`, not raw MatrixSSL headers. +- `libnwflaimtk` and `libnwflaim` are the renamed mars-nwe FLAIM libraries built + from the imported FLAIM sources. The rename is intentional so mars-nwe never + accidentally links against, or conflicts with, a system `libflaim`/FTK install. +- `libnwdirectory` is the directory abstraction library above the FLAIM store. It + is the API used by `nwdirectory`, future `nwnds`, setup/import tooling, and + later Bindery/NDS integration; those consumers should not call `libnwflaim` + directly. +- Keep the layering explicit: + + ```text + apps/services/setup/nwnds -> libnwdirectory -> libnwflaim -> libnwflaimtk + -> libnwssl CCS/NICI -> libnwmatrixssl + apps/services TLS -> libnwssl TLS -> libnwmatrixssl + ``` + +- FLAIM source import, MatrixSSL fork/CMake work, `libnwssl` facade work, + CCS/NICI implementation, and `libnwdirectory` API work should remain separate + patches. + +Next patch number should be `0267`. diff --git a/REDESIGN.md b/REDESIGN.md index a595805..93e4481 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -1649,6 +1649,66 @@ 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. + +### mars-nwe shared library layering + +The MatrixSSL/FLAIM/directory plan should produce mars-nwe-named libraries instead +of exposing raw upstream library identities to the rest of the project. This keeps +linking deterministic, avoids collisions with distro packages, and makes it clear +which layer owns which compatibility boundary. + +Planned library names: + +```text +libnwmatrixssl + mars-nwe-maintained MatrixSSL fork/import + patched only for CMake, portability, symbol/library naming, and build hygiene + provides the low-level GPL-2.0-compatible crypto/TLS implementation + +libnwssl + mars-nwe SSL/crypto facade + provides TLS abstraction for apps/services + provides the CCS/NICI compatibility API used by FLAIM encryption paths + is the only normal project layer that talks directly to libnwmatrixssl + +libnwflaimtk + renamed FLAIM FTK support library + built from the imported FLAIM source but renamed to avoid system-library + conflicts + +libnwflaim + renamed classic FLAIM database library + depends on libnwflaimtk and uses libnwssl only through the CCS/NICI interface + when encrypted storage support is enabled + +libnwdirectory + mars-nwe directory abstraction library + provides the C API used by nwdirectory, future nwnds, nwsetup/import tools, and + any later Bindery/NDS integration + owns the mapping from directory objects/schema/security policy to libnwflaim +``` + +The intended dependency direction is: + +```text +LDAP/LDAPS nwdirectory service -> libnwdirectory -> libnwflaim -> libnwflaimtk +future nwnds/NDS provider -> libnwdirectory -> libnwflaim -> libnwflaimtk +nwsetup/import tooling -> libnwdirectory -> libnwflaim -> libnwflaimtk + +libnwflaim encrypted storage -> libnwssl CCS/NICI compat -> libnwmatrixssl +service/app TLS -> libnwssl TLS facade -> libnwmatrixssl +``` + +Consumers must not skip layers for convenience. `nwdirectory`, future `nwnds`, +`nwsetup`, `nwbind`, and provider code should call `libnwdirectory` for directory +state and `libnwssl` for TLS/crypto policy. They should not include FLAIM, +MatrixSSL, OpenSSL-style, or CCS/NICI implementation headers directly. + +This also means the imported FLAIM targets should not be named exactly like a +system installation. Use mars-nwe names such as `NWFlaim::ftk` / +`NWFlaim::flaim` or equivalent targets that produce `libnwflaimtk` and +`libnwflaim`, while keeping source-origin notes in `third_party/libflaim`. + ### MatrixSSL fork/CMake rule `MatrixSSL` should be evaluated as the preferred GPL-2.0-compatible crypto/TLS @@ -1680,8 +1740,8 @@ 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 +NWMatrixSSL::crypto # produces/represents libnwmatrixssl crypto primitives +NWMatrixSSL::tls # optional TLS surface from the MatrixSSL fork, if built ``` FLAIM should still not include MatrixSSL headers directly. The intended layering @@ -1741,7 +1801,7 @@ inside mars-nwe: ``` The CMake conversion should separate the library from optional tools/tests, -expose a normal target such as `FLAIM::flaim`, and support static/shared choices +expose a normal target such as `NWFlaim::flaim`, and support static/shared choices where useful. The original Makefiles may remain as reference material during the import, but they should not be the long-term build path. @@ -1757,8 +1817,8 @@ The first CMake import should be intentionally small and storage-focused: ```text required first targets: - FLAIM::ftk # cross-platform toolkit used by libflaim - FLAIM::flaim # classic FLAIM database library used by libdirectory + NWFlaim::ftk # produces libnwflaimtk, the renamed FTK support library + NWFlaim::flaim # produces libnwflaim, the renamed classic FLAIM DB library optional later targets: FLAIM::sql # SQL FLAIM, not needed for initial directory store @@ -1768,7 +1828,8 @@ optional later targets: flaim docs # off by default ``` -`FLAIM::flaim` depends on the FTK toolkit, so the CMake conversion should model +`NWFlaim::flaim` depends on the renamed FTK toolkit target, so the CMake +conversion should model that dependency explicitly instead of relying on Autotools' installed-library search. The initial mars-nwe directory-store work only needs the classic FLAIM library path; SQL FLAIM, XFLAIM, Java/C# bindings, Doxygen, OBS/debian package @@ -1788,7 +1849,7 @@ 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. First disable the old FTK TLS-facing code for the required -`FLAIM::ftk`/`FLAIM::flaim` targets. If a legacy path is unavoidable, keep the +`NWFlaim::ftk`/`NWFlaim::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. diff --git a/TODO.md b/TODO.md index b90c69c..d381cc1 100644 --- a/TODO.md +++ b/TODO.md @@ -2013,3 +2013,30 @@ Follow-up: - When importing third-party code, keep its original license in the corresponding `third_party/` subtree and document it separately rather than mixing it into mars-nwe-owned source headers. + +### Shared library layering for MatrixSSL, FLAIM, and directory services + +Current status: + +- Patch `0266` documents the planned mars-nwe shared-library layering for the + MatrixSSL, FLAIM, SSL/crypto, and directory work. +- The intended library names are: + - `libnwmatrixssl` for the patched MatrixSSL fork with native CMake support; + - `libnwssl` for the mars-nwe TLS facade and CCS/NICI compatibility layer; + - `libnwflaimtk` for the renamed FLAIM FTK support library; + - `libnwflaim` for the renamed classic FLAIM database library; + - `libnwdirectory` for the directory abstraction API consumed by `nwdirectory`, + future `nwnds`, setup/import tooling, and later provider integration. +- The intended dependency direction is `libnwdirectory -> libnwflaim -> + libnwflaimtk`, with encrypted-storage crypto flowing through `libnwssl -> + libnwmatrixssl`. + +Follow-up: + +- Add build-system support for these shared libraries in small mechanical + patches. +- Import/fork MatrixSSL first as `libnwmatrixssl` with native CMake. +- Add `libnwssl` as a thin facade before wiring FLAIM encryption paths. +- Import/Fork FLAIM as renamed `libnwflaimtk`/`libnwflaim` targets. +- Add `libnwdirectory` only after the storage and crypto library boundaries are + clear. diff --git a/third_party/README.md b/third_party/README.md index 4f8cee7..b97ba02 100644 --- a/third_party/README.md +++ b/third_party/README.md @@ -75,13 +75,15 @@ 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 -MATRIXSSL::crypto -MATRIXSSL::tls +NWMatrixSSL::crypto +NWMatrixSSL::tls ``` -`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. +`NWMatrixSSL::crypto` is the important first target for `libnwssl` and the +Flaim CCS/NICI compat backend. `NWMatrixSSL::tls` may remain disabled until a +real mars-nwe TLS consumer needs it. The built library should use a mars-nwe +name such as `libnwmatrixssl` to avoid collisions with system MatrixSSL +packages. FLAIM should not call MatrixSSL APIs directly. Keep the layering as: @@ -93,6 +95,10 @@ 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. +The normal mars-nwe consumer target should be `libnwssl`, not MatrixSSL directly. +`libnwssl` owns TLS facade APIs and the CCS/NICI compatibility API used by FLAIM; +it links to `libnwmatrixssl` underneath. + ## Planned: libflaim libflaim is the planned bundled persistent storage engine for the future @@ -120,8 +126,8 @@ OpenSSL/LibreSSL TLS backend for mars-nwe. The first required targets are expected to be: ```text -FLAIM::ftk -FLAIM::flaim +NWFlaim::ftk # libnwflaimtk +NWFlaim::flaim # libnwflaim ``` SQL FLAIM, XFLAIM, tools, tests, generated documentation, package metadata, @@ -130,7 +136,9 @@ outputs should remain optional/off by default until mars-nwe actually needs them. FLAIM is C++ code. mars-nwe C components should not include FLAIM C++ headers -directly. Access should go through the future `libdirectory` C API. +directly. Access should go through the future `libnwdirectory` C API. The +imported FLAIM libraries should be renamed to `libnwflaimtk` and `libnwflaim` +to avoid collisions with a system FLAIM installation. ## Planned: zlog