209 lines
7.6 KiB
Markdown
209 lines
7.6 KiB
Markdown
# libzuptsdk
|
|
|
|
Public C ABI for the [ZUPT](https://github.com/cristiancmoises/zupt) backup compression library.
|
|
|
|
Provides post-quantum encrypted compression as a stable, embeddable shared library, independent of the `zupt` CLI and of any external compression library — everything is built from ZUPT's own implementations.
|
|
|
|
- **Version:** 1.0.0
|
|
- **License of the built library:** AGPL-3.0-or-later AND GPL-3.0-or-later AND BSD-2-Clause AND BSD-3-Clause AND CC0-1.0
|
|
- **ABI:** Stable across 1.x via versioned symbols (`ZUPTSDK_1.0`)
|
|
- **C standard:** Public header is C99; C11 implementation; works in C++17
|
|
|
|
This in-tree compatibility SDK is named **libzuptsdk**. It is not the separately
|
|
packaged **libvuptsdk** dependency used by the CLI's optional `WITH_SDK=1`
|
|
integration. Running `make sdk` builds `libzuptsdk` from this repository; it does
|
|
not enable `--pq-sdk` or the libvuptsdk-backed Argon2id path in `zupt`.
|
|
|
|
## Features
|
|
|
|
- **Hybrid post-quantum encryption** — ML-KEM-768 + X25519 KEM
|
|
- **Authenticated encryption** — AES-256-CTR + HMAC-SHA256, PBKDF2-SHA256 KDF
|
|
- **Hardware-adaptive compression** — VaptVupt on AVX2/NEON, LZHP elsewhere
|
|
- **Streaming I/O** — read/write callbacks for sockets, pipes, encrypted volumes
|
|
- **Secure memory** — mlock-backed buffers for passwords and keys, zeroed on destroy
|
|
- **Optional assembly path** — textual Jasmin sources on supported x86_64 builds
|
|
- **Per-context state** — no globals; safe to use from any thread on distinct contexts
|
|
- **Custom allocator hooks** — supply your own malloc/free
|
|
|
|
## Quick start (C)
|
|
|
|
```c
|
|
#include <zuptsdk.h>
|
|
|
|
zuptsdk_ctx_t *ctx;
|
|
zuptsdk_ctx_create(&ctx);
|
|
|
|
zuptsdk_secure_buf_t *pw;
|
|
zuptsdk_secure_buf_from_data((const uint8_t *)"mypassword", 10, &pw);
|
|
|
|
uint8_t *archive;
|
|
size_t archive_sz;
|
|
zuptsdk_compress_buffer(ctx, NULL, "data.bin",
|
|
my_data, my_data_size,
|
|
pw, NULL,
|
|
&archive, &archive_sz);
|
|
|
|
/* ... store archive somewhere ... */
|
|
|
|
uint8_t *out;
|
|
size_t out_sz;
|
|
zuptsdk_extract_buffer(ctx, archive, archive_sz, pw, NULL, &out, &out_sz);
|
|
|
|
zuptsdk_free(archive);
|
|
zuptsdk_free(out);
|
|
zuptsdk_secure_buf_destroy(pw);
|
|
zuptsdk_ctx_destroy(ctx);
|
|
```
|
|
|
|
Build with `pkg-config`:
|
|
|
|
```sh
|
|
gcc myapp.c $(pkg-config --cflags --libs zuptsdk) -o myapp
|
|
```
|
|
|
|
## Quick start (Python)
|
|
|
|
```python
|
|
import zuptsdk
|
|
|
|
with zuptsdk.Context() as ctx:
|
|
archive = ctx.compress_buffer(b"hello world",
|
|
name="hello.txt",
|
|
password=b"secret")
|
|
|
|
data = ctx.extract_buffer(archive, password=b"secret")
|
|
assert data == b"hello world"
|
|
```
|
|
|
|
Post-quantum mode:
|
|
|
|
```python
|
|
with zuptsdk.Context() as ctx:
|
|
kp = ctx.generate_keypair()
|
|
kp.save("/tmp/mykey") # writes mykey.key (priv, 0600) + mykey.pub (pub, 0644)
|
|
|
|
archive = ctx.compress_buffer(b"secret data",
|
|
name="s.txt",
|
|
public_key=kp.public)
|
|
|
|
data = ctx.extract_buffer(archive, private_key=kp.private)
|
|
```
|
|
|
|
## Build & install
|
|
|
|
```sh
|
|
git clone https://github.com/cristiancmoises/zupt
|
|
cd zupt
|
|
make # builds the portable CLI (WITH_JASMIN=0 by default)
|
|
make sdk # builds libzuptsdk.so.1.0.0 + libzuptsdk.a + zuptsdk.pc
|
|
make sdk-test # runs C roundtrip suite (15 tests)
|
|
sudo make sdk-install PREFIX=/usr/local
|
|
```
|
|
|
|
This SDK is built from source via `make sdk`; the previously vendored prebuilt
|
|
`vendor/zuptsdk/libzuptsdk.so` has been removed from the tree. Build output is
|
|
written below the ignored `sdk/build/` directory and is never part of Git or an
|
|
upstream source archive.
|
|
|
|
The wrapper and application portions are AGPL-3.0-or-later. The library also
|
|
incorporates the bundled VaptVupt codec sources identified as
|
|
GPL-3.0-or-later, plus the BSD-2-Clause xxHash-derived routines and CC0-1.0
|
|
pq-crystals/kyber-derived ML-KEM portions, together with BSD-3-Clause
|
|
curve25519-donna-derived X25519 portions. Redistribution of the resulting
|
|
shared or static library must preserve all five scopes, `LICENSE-AGPL-3.0`,
|
|
`LICENSE-GPL-3.0`, `LICENSE-BSD-2-Clause`, `LICENSE-BSD-3-Clause`,
|
|
`LICENSE-CC0-1.0`, `NOTICE`, and `THIRD-PARTY-NOTICES.md`; see `sdk/LICENSE`
|
|
for the concise scope notice.
|
|
|
|
This installs:
|
|
- `/usr/local/include/zuptsdk.h`
|
|
- `/usr/local/lib/libzuptsdk.so.1.0.0` (with versioned `.so.1` and `.so` symlinks)
|
|
- `/usr/local/lib/libzuptsdk.a`
|
|
- `/usr/local/lib/pkgconfig/zuptsdk.pc`
|
|
- `/usr/local/share/licenses/libzuptsdk/` (all applicable texts and notices)
|
|
|
|
## Symbol visibility
|
|
|
|
The shared library exports **only** the 55 documented public symbols, all prefixed with `zuptsdk_`. Internal `zupt_*` and `vv_*` symbols are hidden via a linker version script.
|
|
|
|
Verify yourself:
|
|
|
|
```sh
|
|
make sdk-verify-symbols
|
|
# [sdk-verify] checking exported symbols in sdk/build/libzuptsdk.so.1.0.0
|
|
# 55 exported / 55 declared in version script
|
|
# PASS: no symbol leakage, all declared symbols exported
|
|
```
|
|
|
|
## ABI stability policy
|
|
|
|
Every symbol declared in `zuptsdk.h` is part of the stable v1.0 ABI and is gated under the linker tag `ZUPTSDK_1.0`.
|
|
|
|
- **New symbols** in v1.x get added under new tags (`ZUPTSDK_1.1`, ...)
|
|
- **Existing symbols** never change signature within v1.x
|
|
- **Breaking changes** require a major bump (`libzuptsdk.so.2`)
|
|
|
|
Do not link against internal `zupt_*` symbols even if you find them in the static archive — they will disappear without notice.
|
|
|
|
## Thread safety
|
|
|
|
- Concurrent calls on **distinct contexts** are safe (MT-Safe).
|
|
- Concurrent calls on the **same context** are not safe.
|
|
|
|
For parallel work, create one context per worker thread.
|
|
|
|
## Memory ownership
|
|
|
|
Every output pointer documents its destroyer. Always use the documented function (`zuptsdk_free`, `zuptsdk_*_destroy`) to release memory — never bare `free()` — because the library may have been built with a custom allocator.
|
|
|
|
Function parameter conventions:
|
|
- `[in]` — caller owns, library reads only
|
|
- `[out]` — caller owns, library writes
|
|
- `[in,out]` — caller owns, library reads and writes
|
|
- `[transfers]` — ownership moves caller ↔ library
|
|
- `[borrowed]` — pointer valid only for the duration of the call
|
|
|
|
## Error handling
|
|
|
|
Functions return `int` where 0 = success, negative = `zuptsdk_error_t` code.
|
|
|
|
```c
|
|
int rc = zuptsdk_compress_buffer(...);
|
|
if (rc != ZUPTSDK_OK) {
|
|
fprintf(stderr, "%s\n", zuptsdk_strerror(rc));
|
|
fprintf(stderr, " detail: %s\n", zuptsdk_last_error_detail());
|
|
return rc;
|
|
}
|
|
```
|
|
|
|
`zuptsdk_last_error_detail()` returns a thread-local string with file:line context.
|
|
|
|
## Components
|
|
|
|
```
|
|
sdk/
|
|
├── include/zuptsdk.h # Public C99 header (55 functions, 7 opaque types)
|
|
├── src/zuptsdk.c # Implementation (wraps zupt internals)
|
|
├── zuptsdk.map # Linker version script (gates exports)
|
|
├── Makefile.sdk # Build integration
|
|
├── bindings/python/zuptsdk.py # Python cffi reference bindings
|
|
├── tests/test_sdk_roundtrip.c # C roundtrip suite
|
|
└── tests/test_python.py # Python test suite
|
|
```
|
|
|
|
## License
|
|
|
|
The built libzuptsdk contains AGPL-3.0-or-later wrapper/application code and
|
|
GPL-3.0-or-later bundled codec code; its complete SPDX expression is
|
|
**AGPL-3.0-or-later AND GPL-3.0-or-later AND BSD-2-Clause AND BSD-3-Clause AND
|
|
CC0-1.0** (see `sdk/LICENSE`).
|
|
|
|
Redistributors must comply with the applicable terms and preserve all license
|
|
texts and notices. Consult the license texts rather than this summary for the
|
|
precise source-correspondence and network-use obligations.
|
|
|
|
## Contact
|
|
|
|
- Repository: https://github.com/cristiancmoises/zupt
|
|
- Project: https://github.com/cristiancmoises/zupt
|
|
- Email: sac@securityops.co
|