75 lines
3.7 KiB
Markdown
75 lines
3.7 KiB
Markdown
|
# HKP-Clavis
|
||
|
|
|
||
|
|
HKP-Clavis was born out of a desire for simplicity. I found existing solutions like hkp-hagrid to be over-engineered and difficult to administer for smaller, focused deployments. My goal was to create a "minimally stable" implementation of an HKP server that does exactly what is needed—no more, no less—while maintaining high performance.
|
||
|
|
|
||
|
|
- Note on Storage: During testing, it became clear that handling large keys (>2MB) directly in PostgreSQL isn't ideal. In the future, I plan to add S3/FileStorage support for blobs to keep the database lean and mean
|
||
|
|
|
||
|
|
|
||
|
|
## 🚀 Features
|
||
|
|
|
||
|
|
* **HKP Protocol Support**: Implements core `add`, `get`, and `index` operations.
|
||
|
|
* **High-Performance Architecture**:
|
||
|
|
* **Object Pooling**: Uses `sync.Pool` via a custom `KeyManager` to reuse `PGPKey` and `PGPUid` objects, significantly reducing GC pressure.
|
||
|
|
* **Efficient Memory Allocation**: Controller and Service layers are built to minimize allocations during key parsing and transformation.
|
||
|
|
* **Database Optimization**:
|
||
|
|
* **PostgreSQL Backend**: Utilizes `pgx/v5` for robust connection pooling.
|
||
|
|
* **Security & Sanitization**:
|
||
|
|
* **Verification-Aware**: Only returns UIDs that have been marked as verified in the database.
|
||
|
|
* **Key Sanitization**: Automatically filters out sensitive or unverified metadata before serving keys.
|
||
|
|
|
||
|
|
## 🛠 Tech Stack
|
||
|
|
|
||
|
|
* **Language**: Go 1.22+
|
||
|
|
* **Database**: PostgreSQL
|
||
|
|
* **Library**: `ProtonMail/go-crypto` (for OpenPGP operations)
|
||
|
|
* **Driver**: `pgx/v5`
|
||
|
|
|
||
|
|
## 📋 Backlog & Future Roadmap
|
||
|
|
|
||
|
|
The project is currently in a "feature freeze" for the core engine. The following features are planned for future development:
|
||
|
|
|
||
|
|
### 1. 🌐 GOTH Stack Web Interface
|
||
|
|
* **Frontend**: Implement a lightweight web UI using **Go Templates + HTMX** (The GOTH Stack).
|
||
|
|
* **Search**: A user-friendly search bar for finding keys without using the CLI.
|
||
|
|
* **Stats**: A dashboard showing server uptime, key count, and pool utilization metrics.
|
||
|
|
* **Kick GPG**: Debug. why key.openpgp.org server (hagrid) and clavis not work with `gpg --recv-key` T__T
|
||
|
|
|
||
|
|
### 2. 🗄️ Hybrid Storage & Large Payload Handling
|
||
|
|
* **Blob Storage Integration**: Implement an external Blob Storage (e.g., MinIO, S3, or local disk) for keys exceeding **1MB** in size to keep the PostgreSQL database lean.
|
||
|
|
* **Metadata/Binary Split**: Store key metadata in Postgres and the actual `.asc` packets in Blob storage.
|
||
|
|
|
||
|
|
### 3. 📧 Email Verification System
|
||
|
|
* **SMTP Service**: Activate the `SMTPPool` for sending verification emails.
|
||
|
|
* **Template Engine**: Support for both HTML and Plaintext email templates (required for classic PGP users).
|
||
|
|
* **Verification Route**: Implement the `GET /verify` endpoint to process tokens and update UID status.
|
||
|
|
|
||
|
|
### 4. 🛡️ System Hardening
|
||
|
|
* **Rate Limiting**: Add middleware to prevent brute-force key uploads or search "scraping".
|
||
|
|
* **SKS Peering**: Support for the synchronization protocol to federate with other global keyservers.
|
||
|
|
|
||
|
|
## ⚙️ Configuration
|
||
|
|
|
||
|
|
The application is configured via environment variables:
|
||
|
|
|
||
|
|
| Variable | Description |
|
||
|
|
| :--- | :--- |
|
||
|
|
| `LISTEN_ADDRESS` | Host to bind the server (e.g., `localhost`) |
|
||
|
|
| `LISTEN_PORT` | Port for the HKP service (e.g., `8181`) |
|
||
|
|
| `POSTGRES_USER` | Database user |
|
||
|
|
| `POSTGRES_PASSWORD` | Database password |
|
||
|
|
| `POSTGRES_ADDRESS` | Database host |
|
||
|
|
| `POSTGRES_PORT` | Database port |
|
||
|
|
| `POSTGRES_DATABASE` | Database name |
|
||
|
|
| `VERIFY_DEFAULT` | If `true`, new keys are marked as verified immediately (Dev mode) |
|
||
|
|
|
||
|
|
ps: verify by smtp not implemented `VERIFY_DEFAULT=true` is recommended
|
||
|
|
|
||
|
|
## 📦 Installation & Usage
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Build the binary
|
||
|
|
go build -o build/hkp-clavis internal/cmd/server/
|
||
|
|
|
||
|
|
# Run the server (ensure env vars are set)
|
||
|
|
./build/hkp-clavis
|