204 lines
9.0 KiB
Markdown
204 lines
9.0 KiB
Markdown
# Third-party dependencies
|
|
|
|
This directory is for mostly external building blocks that are built or linked by
|
|
mars-nwe but are not project-specific service forks. Code here should normally
|
|
be accessed through a mars-nwe facade or subsystem instead of being included
|
|
from endpoint/provider code directly.
|
|
|
|
## yyjson
|
|
|
|
The salvage metadata backend uses the bundled yyjson submodule for JSON
|
|
read/write support. The submodule is required and is linked statically into the
|
|
mars-nwe server targets that use salvage metadata.
|
|
|
|
Setup:
|
|
|
|
```sh
|
|
git submodule update --init --recursive third_party/yyjson
|
|
```
|
|
|
|
CMake expects `third_party/yyjson/CMakeLists.txt` to exist. Reader and writer
|
|
support stay enabled; yyjson tests, fuzzer, misc tools, docs, install targets,
|
|
JSON5/non-standard support, utilities and incremental reader support are disabled
|
|
for the mars-nwe build.
|
|
|
|
## Planned: libowfat
|
|
|
|
libowfat is the planned hard bundled dependency, initially for the
|
|
tinyldap-derived `mars-tinyldap` / `nwdirectory` work. It should live under
|
|
`third_party/libowfat`, not at the repository root, and should be treated as a
|
|
fixed third-party building block in the same sense as yyjson is fixed for
|
|
salvage metadata. mars-nwe core code may also use it later when there is a
|
|
concrete, reviewed helper use.
|
|
|
|
The reviewed archive is `libowfat-0.34.tar.xz`. Its README describes libowfat
|
|
as general-purpose APIs extracted from Dan Bernstein-style software and
|
|
reimplemented under GNU GPL Version 2 with no later-version grant. Record that
|
|
GPL-2.0-only license and the exact source/version in
|
|
`third_party/libowfat/README.mars-nwe.md` when the dependency is imported.
|
|
|
|
The first mars-nwe integration should provide a real CMake target, for example:
|
|
|
|
```text
|
|
OWFAT::owfat
|
|
```
|
|
|
|
Do not rely on libowfat's original Makefile as the long-term build path. The
|
|
CMake import should be usable by both the standalone tinyldap-derived build and
|
|
the mars-nwe superbuild. The first direct consumers should be the
|
|
`mars-tinyldap`/`nwdirectory` compatibility code and any small wrapper needed for
|
|
that integration. Later mars-nwe core consumers may use libowfat directly when a
|
|
real helper need exists; avoid adding libowfat includes to unrelated dispatch
|
|
code merely because the library is bundled.
|
|
|
|
|
|
The mars-nwe build may expose a renamed shared library for the bundled libowfat
|
|
import. The planned artifact name is `libnwowfat`, with the import still
|
|
recorded as libowfat 0.34 in `third_party/libowfat/README.mars-nwe.md`. Keep
|
|
local changes limited to build, CMake, portability, and naming fixes unless a
|
|
later patch documents a small upstreamable bug fix.
|
|
|
|
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.
|
|
|
|
## Superseded candidate: wolfSSL
|
|
|
|
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.
|
|
|
|
## 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
|
|
NWMatrixSSL::crypto
|
|
NWMatrixSSL::tls
|
|
```
|
|
|
|
`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:
|
|
|
|
```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.
|
|
|
|
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. If the old FLAIM/FTK network code cannot
|
|
be disabled, `libnwssl` may also provide a private OpenSSL-compat shim for that
|
|
specific import path. That shim is not a public mars-nwe TLS API and must not be
|
|
used by LDAP, provider IPC, or service code.
|
|
|
|
The preferred FLAIM integration should not patch FLAIM source call sites simply
|
|
to replace NICI/CCS or OpenSSL includes. `libnwssl` may provide private
|
|
compatibility headers under `include/nwssl/private/` and the `libnwflaimtk` /
|
|
`libnwflaim` targets may add that directory privately so legacy includes resolve
|
|
through mars-nwe wrappers:
|
|
|
|
```text
|
|
include/nwssl/private/nici.h
|
|
include/nwssl/private/openssl/*.h
|
|
```
|
|
|
|
Those headers are private to the FLAIM import path. They must not be installed
|
|
or used as the public TLS/crypto API for mars-nwe modules.
|
|
|
|
|
|
## Planned: libflaim
|
|
|
|
libflaim is the planned bundled persistent storage engine for the future
|
|
`libdirectory` store. It belongs under `third_party/libflaim` because it is a
|
|
storage engine dependency, not a mars-nwe service fork.
|
|
|
|
The import should be mars-nwe-maintained. The initial source may come from the
|
|
SourceForge FLAIM code base or from a distro-vetted source package such as the
|
|
openSUSE `libflaim-4.9.1046` source package. The exact source, version, distro
|
|
patches, licenses, and local changes must be documented in
|
|
`third_party/libflaim/README.mars-nwe.md`.
|
|
|
|
The original FLAIM build system should be replaced with a real CMake build, not
|
|
wrapped from the mars-nwe build. The uploaded r1112 trunk snapshot already has
|
|
Autotools files, but those should be treated as source inventory and build-check
|
|
reference material. The resulting tree should build both as a standalone library
|
|
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
|
|
the `libnwssl` OpenSSL-compat shim backed by `libnwmatrixssl`, not a new public
|
|
OpenSSL/LibreSSL TLS backend for mars-nwe. Keep the shim limited to the symbols
|
|
used by the imported FLAIM/FTK source rather than growing a general OpenSSL clone.
|
|
|
|
The first required targets are expected to be:
|
|
|
|
```text
|
|
NWFlaim::ftk # libnwflaimtk
|
|
NWFlaim::flaim # libnwflaim
|
|
```
|
|
|
|
SQL FLAIM, XFLAIM, tools, tests, generated documentation, package metadata,
|
|
Windows projects, NetWare NLM files, Java/C# bindings, and other legacy build
|
|
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 `libnwdirectory` C API. The
|
|
imported FLAIM libraries should be renamed to `libnwflaimtk` and `libnwflaim`
|
|
to avoid collisions with a system FLAIM installation.
|
|
|
|
## Planned: zlog
|
|
|
|
zlog is the planned optional advanced logging backend. If added, it should live
|
|
under `third_party/zlog` and be used only through the mars-nwe `nwlog` facade:
|
|
|
|
```text
|
|
include/nwlog.h
|
|
src/nwlog.c
|
|
src/nwlog_zlog.c
|
|
```
|
|
|
|
Endpoint and provider code must not call zlog APIs directly. This keeps secret
|
|
redaction, request correlation fields, and fallback logging centralized.
|
|
|
|
## Forked components are not third_party
|
|
|
|
Components that are forked and integrated as mars-nwe services should live at the
|
|
repository root, following the existing pattern used by `admin`, `dosutils`,
|
|
`mail`, and `smart`.
|
|
|
|
The planned tinyldap fork is such a component. It should live as
|
|
`mars-tinyldap/` at the repository root. Its standalone identity remains
|
|
`tinyldap`, while the mars-nwe integration builds the project-facing
|
|
`nwdirectory` service. The fork should gain a real CMake build that works both
|
|
standalone under the tinyldap name and as a mars-nwe subdirectory, and it should
|
|
later use `libdirectory`/libflaim-backed storage instead of tinyldap's original
|
|
flat-file storage.
|
|
|
|
The inspected tinyldap snapshot has one handwritten Makefile that builds ASN.1,
|
|
LDAP, LDIF, auth, storage, tiny TLS, server, client, index, ACL, conversion, and
|
|
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 MatrixSSL.
|