79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
# Metacrypt
|
|
|
|
Metacrypt is a cryptographic service for the [Metacircular](https://metacircular.net) platform. It provides an encrypted secrets barrier and pluggable cryptographic engines (CA/PKI, SSH CA, transit encryption, user-to-user encryption) over a gRPC and HTTPS API. Authentication is delegated to [MCIAS](https://mcias.metacircular.net:8443/docs).
|
|
|
|
It operates using a seal/unseal model similar to HashiCorp Vault: the service starts sealed on every boot and must be unlocked with a password before cryptographic operations are available.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.23+
|
|
- A running [MCIAS](https://mcias.metacircular.net:8443/docs) instance
|
|
- TLS certificate and key for the server
|
|
|
|
### Build
|
|
|
|
```bash
|
|
make metacrypt metacrypt-web
|
|
```
|
|
|
|
### Configure
|
|
|
|
```bash
|
|
cp deploy/examples/metacrypt.toml /srv/metacrypt/metacrypt.toml
|
|
# Edit to set listen_addr, tls_cert, tls_key, database.path, mcias.server_url
|
|
```
|
|
|
|
### Initialize
|
|
|
|
```bash
|
|
./metacrypt init --config /srv/metacrypt/metacrypt.toml
|
|
```
|
|
|
|
This prompts for a seal password and generates the master encryption key. **Store the seal password securely — it cannot be recovered if lost.**
|
|
|
|
### Run
|
|
|
|
```bash
|
|
./metacrypt server --config /srv/metacrypt/metacrypt.toml
|
|
```
|
|
|
|
The service starts **sealed**. Unseal it:
|
|
|
|
```bash
|
|
curl -sk -X POST https://localhost:8443/v1/unseal \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"password":"<seal-password>"}'
|
|
```
|
|
|
|
Or use the web UI: navigate to `https://<host>:8443/`.
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker compose -f deploy/docker/docker-compose.yml up -d
|
|
```
|
|
|
|
See [RUNBOOK.md](RUNBOOK.md#docker-install) for volume setup instructions.
|
|
|
|
## Further Reading
|
|
|
|
| Document | Contents |
|
|
|---|---|
|
|
| [ARCHITECTURE.md](ARCHITECTURE.md) | Cryptographic design, key hierarchy, engine architecture, API reference, security model |
|
|
| [RUNBOOK.md](RUNBOOK.md) | Installation, daily operations, backup/restore, monitoring, troubleshooting |
|
|
| [PKI-ENGINE-PLAN.md](PKI-ENGINE-PLAN.md) | CA engine implementation plan |
|
|
|
|
## Development
|
|
|
|
```bash
|
|
make build # Build all packages
|
|
make test # Run tests
|
|
make vet # Static analysis
|
|
make lint # golangci-lint
|
|
make proto # Regenerate protobuf/gRPC stubs
|
|
make proto-lint # Lint and check proto breaking changes
|
|
```
|