feat: Sprint 3 — C FFI bindings, WASM compilation, Python example, SDK docs
- Create quicproquo-ffi crate with 7 extern "C" functions: connect, login, send, receive, disconnect, last_error, free_string (produces libquicproquo_ffi.so and .a) - Feature-gate quicproquo-core for WASM: identity, hybrid_kem, safety_numbers, sealed_sender, app_message, padding, transcript all compile to wasm32-unknown-unknown - Add Python ctypes example (examples/python/qpq_client.py) with QpqClient wrapper class and CLI - Add SDK documentation: FFI reference, WASM guide, qpq-gen generators - Update Dockerfile for quicproquo-ffi workspace member
This commit is contained in:
70
docs/src/getting-started/wasm.md
Normal file
70
docs/src/getting-started/wasm.md
Normal file
@@ -0,0 +1,70 @@
|
||||
# WASM Integration
|
||||
|
||||
The `quicproquo-core` crate supports compilation to `wasm32-unknown-unknown`
|
||||
when the `native` feature is disabled. This exposes the pure-crypto subset of
|
||||
the library for use in browsers or other WASM runtimes.
|
||||
|
||||
## Building for WASM
|
||||
|
||||
```bash
|
||||
rustup target add wasm32-unknown-unknown
|
||||
|
||||
cargo build -p quicproquo-core \
|
||||
--target wasm32-unknown-unknown \
|
||||
--no-default-features
|
||||
```
|
||||
|
||||
The `--no-default-features` flag disables the `native` feature, which gates
|
||||
MLS (openmls), OPAQUE, Cap'n Proto, and tokio -- all of which have dependencies
|
||||
that do not compile to WASM.
|
||||
|
||||
## What is available in WASM mode
|
||||
|
||||
The following modules compile to WASM and are fully functional:
|
||||
|
||||
| Module | Description |
|
||||
|-------------------|----------------------------------------------------|
|
||||
| `identity` | Ed25519 identity keypair (generate, sign, verify) |
|
||||
| `hybrid_kem` | X25519 + ML-KEM-768 hybrid key encapsulation |
|
||||
| `safety_numbers` | Signal-style safety number computation |
|
||||
| `sealed_sender` | Sender identity + Ed25519 signature envelope |
|
||||
| `app_message` | Rich application message serialisation/parsing |
|
||||
| `padding` | Message padding to hide plaintext lengths |
|
||||
| `transcript` | Encrypted tamper-evident message transcript |
|
||||
| `error` | `CoreError` type |
|
||||
|
||||
## What is NOT available in WASM mode
|
||||
|
||||
The following require the `native` feature and will not compile to WASM:
|
||||
|
||||
- `group` -- MLS group state machine (openmls)
|
||||
- `keypackage` -- MLS KeyPackage generation
|
||||
- `hybrid_crypto` -- hybrid HPKE provider for OpenMLS
|
||||
- `keystore` -- OpenMLS key store with disk persistence
|
||||
- `opaque_auth` -- OPAQUE cipher suite configuration
|
||||
|
||||
Networking (`quicproquo-client`, `quicproquo-server`) is not available in WASM.
|
||||
|
||||
## Random number generation
|
||||
|
||||
On `wasm32`, the `getrandom` crate is configured with the `js` feature to
|
||||
use the browser's `crypto.getRandomValues()` API. This is set automatically
|
||||
in `quicproquo-core/Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
getrandom = { version = "0.2", features = ["js"] }
|
||||
```
|
||||
|
||||
This means the WASM build works in browser environments out of the box.
|
||||
For non-browser WASM runtimes (WASI, etc.), you may need to adjust the
|
||||
`getrandom` backend.
|
||||
|
||||
## Future plans
|
||||
|
||||
- **wasm-bindgen JS bindings**: Wrap the WASM-compatible modules with
|
||||
`#[wasm_bindgen]` annotations to provide a native JavaScript/TypeScript API.
|
||||
This would allow web frontends to perform client-side encryption without a
|
||||
server round-trip.
|
||||
- **wasm-pack integration**: Publish the WASM module as an npm package for
|
||||
easy consumption in web projects.
|
||||
Reference in New Issue
Block a user