Skip to content

Commit 24f237b

Browse files
Add postguard repo website docs content to centralized docs
The postguard repo contains a Docusaurus docs website in website/ that was not accounted for during the initial documentation centralization. This updates the repos/postguard.md page to incorporate the content from that website, including: - Mention of the existing Docusaurus site and its GitHub Pages URL - Cryptographic primitives table and pg-core feature flags - Full development setup: prerequisites, building each crate, WASM build, docker-compose, environment variables - PKG server setup: key generation, running, Docker deployment - CLI usage examples for encrypt and decrypt - PKG Server API endpoint reference - WASM bindings overview with cross-references to the SDK docs Relates to #8 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ea1bb6d commit 24f237b

1 file changed

Lines changed: 169 additions & 3 deletions

File tree

docs/repos/postguard.md

Lines changed: 169 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
The main PostGuard repository. It contains the core encryption library, the Private Key Generator (PKG) server, WebAssembly bindings for browsers, a command-line client, and FFI bindings for native language integration.
66

7+
The repo also includes a [Docusaurus documentation site](https://encryption4all.github.io/postguard/) in the `website/` directory, covering architecture, API reference, and Yivi integration. That content has been consolidated into this centralized docs site.
8+
79
## Workspace Structure
810

911
The repository is a Rust workspace with five crates:
@@ -16,6 +18,8 @@ The repository is a Rust workspace with five crates:
1618
| `pg-cli` | Command-line tool for encrypting and decrypting files |
1719
| `pg-ffi` | FFI bindings for calling Rust code from other languages (used by [postguard-dotnet](/repos/postguard-dotnet)) |
1820

21+
The `website/` directory contains a Docusaurus site deployed to GitHub Pages via the `docs.yml` workflow.
22+
1923
## How It Works
2024

2125
PostGuard uses Identity-Based Encryption (IBE). Instead of public keys, the sender only needs the master public key and the recipient's identity (e.g. email address). To decrypt, the recipient proves their identity to the PKG via [Yivi](https://yivi.app) and receives a decryption key.
@@ -32,16 +36,62 @@ A typical session:
3236
7. The PKG issues a decryption key for that identity.
3337
8. The recipient's client decrypts the message.
3438

39+
For the full protocol details, see the [architecture overview](/guide/architecture) and [core concepts](/guide/concepts) in the guide.
40+
41+
### Cryptographic Primitives
42+
43+
| Primitive | Implementation |
44+
|---|---|
45+
| KEM | CGW-KV anonymous IBE on BLS12-381 ([`ibe`](https://crates.io/crates/ibe) crate) |
46+
| IBS | GG identity-based signatures ([`ibs`](https://crates.io/crates/ibs) crate) |
47+
| Symmetric | AES-128-GCM (128-bit security to match BLS12-381) |
48+
| Hashing | SHA3-512 for identity derivation |
49+
50+
### pg-core Feature Flags
51+
52+
pg-core supports two backends:
53+
54+
- `rust` (default): uses RustCrypto crates for native Rust targets
55+
- `web`: uses the Web Crypto API for WASM in browsers
56+
57+
Streaming mode is enabled with the `stream` feature flag. When active, encryption and decryption process data in 256 KiB chunks instead of loading everything into memory.
58+
3559
## Development
3660

3761
### Prerequisites
3862

39-
- [Rust](https://www.rust-lang.org/tools/install) (stable)
63+
- [Rust](https://www.rust-lang.org/tools/install) (stable, 1.90.0 or later)
64+
- Docker and Docker Compose (for the local development environment)
65+
- [wasm-pack](https://rustwasm.github.io/wasm-pack/) (only for WASM development)
66+
67+
```bash
68+
# Install wasm-pack (if working on pg-wasm)
69+
cargo install --git https://github.com/rustwasm/wasm-pack.git
70+
```
4071

4172
### Building
4273

4374
```bash
75+
# Build the full workspace
4476
cargo build --release
77+
78+
# Build individual crates
79+
cargo build --release -p pg-core
80+
cargo build --release --bin pg-cli
81+
cargo build --release --bin pg-pkg
82+
```
83+
84+
### Building WASM Bindings
85+
86+
```bash
87+
cd pg-wasm
88+
wasm-pack build --release -d pkg/ --out-name index --scope e4a --target bundler
89+
```
90+
91+
For web target (without a bundler):
92+
93+
```bash
94+
wasm-pack build --release -d pkg/ --out-name index --scope e4a --target web
4595
```
4696

4797
### Testing
@@ -60,10 +110,126 @@ wasm-pack test --release --headless --firefox ./pg-wasm
60110

61111
### Running the PKG Server
62112

113+
Generate a master key pair first (run once):
114+
115+
```bash
116+
cargo run --release --bin pg-pkg gen
117+
```
118+
119+
Then start the server:
120+
63121
```bash
64-
cargo run -p pg-pkg --release
122+
cargo run --release --bin pg-pkg server \
123+
-t <irma_server_token> \
124+
-i <irma_server_url> \
125+
-d <postgres_connection_string>
65126
```
66127

128+
Or run via Docker:
129+
130+
```bash
131+
docker build -t postguard-pkg .
132+
docker run -p 8080:8080 postguard-pkg server \
133+
-t <irma_token> \
134+
-i <irma_url> \
135+
-d <postgres_url>
136+
```
137+
138+
### Local Development Environment
139+
140+
Docker Compose starts PostgreSQL and a Yivi (IRMA) server for local development:
141+
142+
```bash
143+
docker-compose up
144+
```
145+
146+
Then run the PKG server against the local services:
147+
148+
```bash
149+
cargo run --release --bin pg-pkg server \
150+
-d postgres://devuser:devpassword@localhost/devdb \
151+
-t <irma_token> \
152+
-i http://localhost:8088
153+
```
154+
155+
### Environment Variables
156+
157+
| Variable | Description | Default |
158+
|---|---|---|
159+
| `IRMA_SERVER` | Yivi/IRMA server URL | `https://is.yivi.app` |
160+
| `DATABASE_URL` | PostgreSQL connection string | (required) |
161+
| `RUST_LOG` | Log level (`debug`, `info`, `warn`, `error`) | (none) |
162+
163+
### Using the CLI
164+
165+
Encrypt a file:
166+
167+
```bash
168+
cargo run --bin pg-cli enc \
169+
-i '{"recipient@example.com": [{"t": "pbdf.sidn-pbdf.email.email", "v": "recipient@example.com"}]}' \
170+
--pub-sign-id '[{"t": "pbdf.gemeente.personalData.fullname"}]' \
171+
myfile.txt
172+
```
173+
174+
This starts a Yivi session (displays a QR code) to obtain signing keys, then encrypts `myfile.txt` into `myfile.txt.enc`.
175+
176+
Decrypt a file:
177+
178+
```bash
179+
cargo run --bin pg-cli dec myfile.txt.enc
180+
```
181+
182+
The CLI shows the recipient policies in the header, prompts you to select your identity, and starts a Yivi session to obtain your decryption key.
183+
184+
## PKG Server API
185+
186+
The PKG server (`pg-pkg`) exposes an HTTP API. By default it listens on `http://localhost:8080`.
187+
188+
### Public Parameters
189+
190+
| Method | Endpoint | Description |
191+
|---|---|---|
192+
| `GET` | `/v2/parameters` | Fetch the Master Public Key (MPK). Supports ETag/Cache-Control caching. |
193+
| `GET` | `/v2/sign/parameters` | Fetch the public verification key for signature checking. |
194+
195+
### Yivi Sessions
196+
197+
| Method | Endpoint | Description |
198+
|---|---|---|
199+
| `POST` | `/v2/irma/start` | Start a Yivi identity verification session. |
200+
| `GET` | `/v2/irma/jwt/{token}` | Retrieve the JWT result of a completed Yivi session. |
201+
202+
### Key Issuance
203+
204+
| Method | Endpoint | Description |
205+
|---|---|---|
206+
| `GET` | `/v2/irma/key/{timestamp}` | Retrieve a User Secret Key (USK). Requires `Authorization: Bearer <jwt>`. |
207+
| `POST` | `/v2/irma/sign/key` | Retrieve signing keys. Authenticate with a Yivi JWT or API key (`PG-API-<key>`). |
208+
209+
### Health
210+
211+
| Method | Endpoint | Description |
212+
|---|---|---|
213+
| `GET` | `/health` | Health check. |
214+
| `GET` | `/metrics` | Prometheus metrics. |
215+
216+
For the full API details with request/response examples, see the [architecture page](/guide/architecture#api-endpoints).
217+
218+
## WASM Bindings (pg-wasm)
219+
220+
The `@e4a/pg-wasm` package provides WebAssembly bindings for PostGuard in browser environments. Install via npm:
221+
222+
```bash
223+
npm install @e4a/pg-wasm
224+
```
225+
226+
The package exports:
227+
228+
- `seal()` and `sealStream()` for encryption (in-memory and streaming)
229+
- `Unsealer` and `StreamUnsealer` for decryption (in-memory and streaming)
230+
231+
Both streaming variants use the Web Streams API (`ReadableStream`/`WritableStream`). For usage examples and the full JavaScript/TypeScript API, see the [SDK reference](/sdk/overview).
232+
67233
## Releasing
68234

69235
This repository uses [Release-plz](https://release-plz.ieni.dev/) for automated versioning and releases. When changes are merged to `main`, Release-plz creates a release PR. Merging that PR triggers:
@@ -80,4 +246,4 @@ This repository uses [Release-plz](https://release-plz.ieni.dev/) for automated
80246
|---|---|---|
81247
| `build.yml` | Push/PR | Formatting checks, tests for all workspace members |
82248
| `delivery.yml` | Push to main | Release-plz, Docker build, FFI compilation, npm publish |
83-
| `docs.yml` | Push to main | Deploys API docs to GitHub Pages |
249+
| `docs.yml` | Push to main | Builds the Docusaurus site in `website/` and deploys to [GitHub Pages](https://encryption4all.github.io/postguard/) |

0 commit comments

Comments
 (0)