minica

KO | EN

gitlite — search

#python #react #typescript #llm #go #linux #macos #java #kubernetes #vue #awesome-list #ios #openai #mcp

(★ 19)

A Certificate Authority with RESTful interface and WEB UI

minica Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MiniCA (Rust)

A small Certificate Authority service with a REST API and web UI. Create CAs,
issue certificates, publish CRLs, and download PEM/PKCS#12 bundles — without ever
touching an `openssl` command line.

This is a ground-up Rust rewrite of the original
[minica](./upstream-minica/README.md) (Kotlin + Spring Boot + Angular). It keeps
the same mental model — CAs and certificates managed over a Basic-auth REST API
with admin/viewer roles — while replacing the runtime, storage, and operational
story with something smaller, safer, and easier to run.

## Feature highlights

- **Single static binary, two dependencies.** The service is one Rust binary
  that shells out to `openssl`. There is no JVM, no application server, and no
  JDK `keytool` to install — the only runtime requirement is `openssl` on
  `PATH`. *Rationale:* the original needed JDK 17+, a Spring Boot fat JAR, and
  `keytool`; this removes an entire language runtime from the deployment.

- **Database-backed, durable state.** All CAs, certificates, users, and CRLs
  live in a bundled SQLite database rather than loose files in a directory tree.
  *Rationale:* state is transactional and easy to snapshot, instead of being
  spread across per-CA folders on disk.

- **First-class CRL support.** Every CA gets a CRL that is (re)generated on
  creation, import, and revocation; issued certs can embed a
  `crlDistributionPoints` URL, and the DER CRL is served at `/crl/{ca_id}`.
  *Rationale:* the original had no certificate revocation at all — once issued, a
  cert could not be revoked.

- **Backup & restore.** One YAML export captures everything durable — users
  (bcrypt hashes), active and soft-deleted CAs/certs, all private material,
  `index.txt`/`serial.txt`, and the CRLs — and restores byte-for-byte into an
  empty database inside a transaction. *Rationale:* real disaster recovery from a
  single file, versioned for forward compatibility.

- **Safer multi-user auth.** A single bootstrap admin lives in the config file;
  all other accounts are managed in the database with **bcrypt-hashed**
  passwords via an Admin Console, with admin/viewer roles. *Rationale:* you don't
  keep every user's plaintext password in a properties file.

- **Concurrency-safe revocation.** Revocation takes a per-CA lock and persists
  the new `index.txt`, serial, and CRL atomically, releasing the lock on error.
  *Rationale:* concurrent revokes can't corrupt the CA's OpenSSL database.

- **Soft delete & restore.** CAs and certificates are soft-deleted and can be
  restored from the Admin Console. *Rationale:* an accidental delete is
  recoverable.

- **Bounded, self-cleaning OpenSSL execution.** Each `openssl` invocation runs in
  a throwaway working directory with a wall-clock timeout (SIGTERM then SIGKILL),
  and abandoned workdirs are swept periodically. *Rationale:* a hung or crashed
  subprocess can't leak processes or temp files.

- **OpenAPI / Swagger UI.** The REST API is documented and explorable in-browser
  at `/swagger`. *Rationale:* discoverable, testable API instead of README-only
  docs.

- **Companion Go CLI.** A small [`minica cert` CLI](./cli/README.md) drives the
  API end-to-end — create a cert and save the PEM, key, PKCS#12, its password,
  and the CA cert — configured by flags, `MINICA_*` env vars, or a `~/.minica`
  file. *Rationale:* automate issuance from scripts without hand-rolling the API
  calls and CSRF handling.

## Why this is a better version of minica

| Aspect | Original minica | MiniCA (Rust) |
| --- | --- | --- |
| Runtime | JVM + Spring Boot + JDK `keytool` | Single Rust binary + `openssl` |
| Storage | Per-CA directories on disk | Bundled SQLite database |
| Revocation / CRL | None | CRL generation, revocation, distribution points |
| Backup/restore | Copy the directory tree | One transactional YAML export/restore |
| User passwords | Plaintext in config | Bootstrap admin in config; DB users bcrypt-hashed |
| Delete safety | Hard delete | Soft delete with restore |
| Subprocess safety | — | Timeout-bounded, self-cleaning workdirs |
| Automation | REST API | REST API + OpenAPI/Swagger + Go CLI |

In short: the original proved the model — a friendly REST/UI front end over
`openssl` so you never memorize its flags. This rewrite keeps that ergonomics
win and hardens everything around it: fewer moving parts to deploy, durable and
backup-able state, real revocation, hashed credentials, and safe concurrency.

### Honest trade-offs

- **No JKS / Java truststore output.** Dropping the JDK dependency also drops
  `keytool`-produced JKS keystores and truststores; downloads are PEM and
  PKCS#12. If your toolchain needs JKS, convert from the PKCS#12 bundle.
- **CRLs are not auto-refreshed on a timer.** A CRL is regenerated on
  create/import/revoke, so a quiet CA can serve a CRL past its `nextUpdate` until
  the next change.

## Getting started

1. **Configure.** Generate a starter config from the bundled sample, then edit it:
   ```sh
   minica --gen-config        # writes ./config.yaml (won't overwrite an existing one)
   ```
   Set the server bind/port and `base_path`, `public_base_url` (used for CRL
   distribution URLs and links behind a proxy), the `openssl` path, and the
   bootstrap `admin` user. The bootstrap password may be a **bcrypt hash**
   (recommended — generate one with `minica --gen-password`) or plaintext; a
   plaintext bootstrap password still works but logs a warning at startup. All
   other users are bcrypt-hashed in the DB.

2. **Run the service.**
   ```sh
   cargo run --release -- --start -c config.yaml
   # or, from a built binary:
   ./minica --start -c config.yaml
   ```
   The UI and API are served under `base_path` (default `/minica`); Swagger is at
   `/minica/swagger`. Run `minica --help` to see all actions
   (`--start`, `--gen-config`, `--gen-password`, `--verify-password`).

3. **Issue certs from the CLI.** See [cli/README.md](./cli/README.md):
   ```sh
   cd cli && go build -o mcacli .
   MINICA_URL=http://127.0.0.1:9988/minica MINICA_USER=admin \
   MINICA_PASSWORD=adminpass MINICA_CA_ID=<ca-id> \
   ./mcacli cert --cn test1.example.com --hostnames a.com,b.com,10.0.0.5
   ```

### Docker-friendly environment variables

Any value in the config file may be written as `{{ENV:VAR:default}}`: it
resolves to the environment variable `VAR` when set, otherwise to the default
after the second colon. `{{ENV:VAR}}` with no default resolves to an empty
string when the variable is unset. Variable names and fallback values are
trimmed. Variable names must match `[A-Za-z_][A-Za-z0-9_]*`. Fallback values
may contain colons, and percent escapes in fallbacks are decoded on a
best-effort basis, so `}}` can be written as `%7D%7D`. Only strict `%HH` hex
escapes are decoded; `+` is left as a literal plus. Resolution happens after
the file is read and before YAML parsing, so tokens don't need quoting and may
expand to any YAML value.

```yaml
auth:
  users:
    enabled: {{ENV:MINICA_BASIC_AUTH_ENABLE:true}}
    list:
      - username: {{ENV:MINICA_ADMIN_USER:admin}}
        password: {{ENV:MINICA_ADMIN_PASSWORD:adminpass}}
        role: admin
  headers:
    enabled: {{ENV:MINICA_HEADER_AUTH_ENABLE:false}}
    trusted_remotes:
      - '{{ENV:MINICA_TRUSTED_REMOTE_1:-}}'
```

[config.yaml.docker](./config.yaml.docker) is a fully parameterised template —
every setting has a `MINICA_*` variable whose default matches
`config.yaml.example`, except that the container image overrides mutable paths
under `/data`. Treat `/data` as persistent storage: use a Docker/Podman named
volume, a bind mount, or a Kubernetes PersistentVolumeClaim. If `/data` is not
persistent, the SQLite database and generated CA/certificate state are lost when
the container is removed.

- `/data/runtime` for runtime state
- `/data/sqlite` for the SQLite database folder
- `/data/logs/minica.log` for logs
- `/data/runtime/openssl-work` for OpenSSL temporary workdirs

Build the local image with Podman:

```sh
docker/build.sh minica:local
```

Run it with `/data` mounted:

```sh
podman run --rm -p 9988:9988 -v minica-data:/data \
  -e MINICA_ADMIN_PASSWORD='$2b$12$...' \
  minica:local
```

Docker uses the same image recipe. If you prefer Docker instead of Podman:

```sh
./build.sh
docker build -f docker/Dockerfile -t minica:local .
docker run --rm -p 9988:9988 -v minica-data:/data \
  -e MINICA_ADMIN_PASSWORD='$2b$12$...' \
  minica:local
```

When MiniCA resolves environment tokens at startup, it prints each resolved
variable to stderr. Password-like names are masked (`MINICA_ADMIN_PASSWORD ->
a*******s`), and any set `MINICA_` variable not referenced by the loaded config
prints a warning.

Common Docker-friendly variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `MINICA_HOST` | `0.0.0.0` | Server bind address. |
| `MINICA_PORT` | `9988` | Server port. |
| `MINICA_BASE_PATH` | `/minica` | UI/API base path. |
| `MINICA_PUBLIC_BASE_URL` | `http://127.0.0.1:9988/minica` | External URL used in links and CRL distribution points. |
| `MINICA_CRL_ENABLED` | `true` | Enable CRL generation and serving. |
| `MINICA_CRL_NEXT_UPDATE_DAYS` | `30` | CRL `nextUpdate` interval. |
| `MINICA_RUNTIME_FOLDER` | `/data/runtime` in the image | Runtime state folder. |
| `MINICA_DB_FOLDER` | `/data/sqlite` in the image | Folder containing `db.sqlite`. |
| `MINICA_LOG_FILE` | `/data/logs/minica.log` in the image | Log file path. |
| `MINICA_LOG_ROTATE_SIZE_BYTES` | `10485760` | Log rotation size. |
| `MINICA_LOG_MAX_BACKUPS` | `10` | Number of rotated log files to keep. |
| `MINICA_LOG_COMPRESS` | `true` | Compress rotated logs. |
| `MINICA_OPENSSL_PATH` | `/usr/bin/openssl` | OpenSSL binary path. |
| `MINICA_OPENSSL_TIMEOUT_SECONDS` | `15` | Per-command OpenSSL timeout. |
| `MINICA_OPENSSL_WORKING_ROOT` | `/data/runtime/openssl-work` in the image | OpenSSL temporary working root. |
| `MINICA_OPENSSL_KEEP_FAILED_WORKDIRS` | `false` | Keep failed OpenSSL workdirs for debugging. |
| `MINICA_OPENSSL_REAP_AFTER_HOURS` | `24` | Age threshold for cleaning abandoned OpenSSL workdirs. |
| `MINICA_BASIC_AUTH_ENABLE` | `true` | Enable config/bootstrap Basic auth. |
| `MINICA_ADMIN_USER` | `admin` | Bootstrap admin username. |
| `MINICA_ADMIN_PASSWORD` | `adminpass` | Bootstrap admin password or bcrypt hash. Use `minica --gen-password`. |
| `MINICA_ADMIN_ROLE` | `admin` | Bootstrap account role. |
| `MINICA_HEADER_AUTH_ENABLE` | `false` | Enable reverse-proxy header auth. |
| `MINICA_HEADER_USERNAME` | `Remote-User` | Header carrying the authenticated username. |
| `MINICA_HEADER_GROUP` | `Remote-Groups` | Header carrying user groups. |
| `MINICA_HEADER_ADMIN_GROUP` | `admin` | Group that grants admin role. |
| `MINICA_HEADER_VIEWER_GROUP` | `user` | Group that grants viewer role. |
| `MINICA_TRUSTED_REMOTE_1` ... `MINICA_TRUSTED_REMOTE_10` | `-` | Trusted reverse-proxy peers, as IPs or CIDRs. Unset slots are ignored; no trusted peers means trust every remote. |

```sh
podman run --rm -p 8443:8443 -v minica-data:/data \
  -e MINICA_PORT=8443 \
  -e MINICA_ADMIN_PASSWORD='$2b$12$...' \
  -e MINICA_HEADER_AUTH_ENABLE=true \
  -e MINICA_TRUSTED_REMOTE_1=10.0.0.7 \
  minica:local
```

Docker equivalent:

```sh
docker run --rm -p 8443:8443 -v minica-data:/data \
  -e MINICA_PORT=8443 \
  -e MINICA_ADMIN_PASSWORD='$2b$12$...' \
  -e MINICA_HEADER_AUTH_ENABLE=true \
  -e MINICA_TRUSTED_REMOTE_1=10.0.0.7 \
  minica:local
```

### Using LibreSSL instead of OpenSSL

MiniCA shells out to the `openssl` binary, and every subcommand it uses
(`genpkey`, `req`, `ca` — including `copy_extensions`, `-gencrl`, `-revoke`,
`-crl_reason` — `crl`, `pkcs12 -export`, `verify`, `x509`) is also provided by
LibreSSL; the one OpenSSL-only flag MiniCA used (`x509 -ext`) has an automatic
fallback. To use LibreSSL, just point the config at its binary:

```yaml
openssl:
  path: /usr/bin/openssl        # OpenBSD (LibreSSL is the system openssl)
  # path: /usr/local/opt/libressl/bin/openssl   # Homebrew libressl
  # path: /usr/bin/eopenssl33                   # some Linux libressl packages
```

Caveats:

- **PKCS#12 encryption defaults.** LibreSSL's `pkcs12 -export` still defaults
  to 3DES for keys and 40-bit RC2 for certificates (OpenSSL 3 uses AES-256 +
  PBKDF2). The resulting `.p12` bundles import fine into Windows, Java, and
  browsers, but *reading* an RC2-encrypted bundle with an OpenSSL 3.x client
  needs its legacy provider (`openssl pkcs12 -legacy ...`).
- Compatibility was verified against the LibreSSL manual and sources; if you
  hit an issue with a specific LibreSSL version, set
  `openssl.keep_failed_workdirs: true` and check the logged command that
  failed.

### Reverse-proxy (SSO) header authentication

MiniCA can trust an authenticating reverse proxy (Authelia, oauth2-proxy,
Traefik forward-auth, ...) to identify users via request headers. You can run
this instead of Basic auth, or alongside Basic auth. In header-only mode no
local account is needed at all. Both `auth.users` and `auth.headers` may be
configured side by side, each with an `enabled` toggle (default true when the
section is present). At least one mode must be enabled. When both are enabled,
requests with a header-auth identity use header auth; requests without identity
headers fall back to Basic auth, which keeps CLI access usable beside
browser/proxy SSO.

When `auth.headers.enabled` and `auth.users.enabled` are both `true`, MiniCA
uses this order:

- If the configured username header is missing or empty, Basic auth handles the
  request.
- If the username header is present, header auth handles the request; failed
  trust or group checks do not fall back to Basic auth.
- A header-auth user in `admin_group` gets admin access, even if they are also
  in `viewer_group`.
- A header-auth user in `viewer_group` plus any other non-admin groups gets
  viewer access.
- A header-auth user in neither `admin_group` nor `viewer_group`, or with no
  group header, is denied.

```yaml
auth:
  users:
    enabled: false               # or omit the whole section
    list: []
  headers:
    enabled: true
    username: Remote-User        # header carrying the authenticated user id
    group: Remote-Groups         # header carrying the group list
    admin_group: admin           # group that grants the admin role
    viewer_group: user           # group that grants the viewer role
    # Honor identity headers only from these peers (IPs or CIDRs) — typically
    # the upstream reverse proxy. Omit or leave empty to trust every remote.
    #trusted_remotes:
    #  - 127.0.0.1
    #  - 10.0.0.0/8
```

- The group header accepts `a,b`, `a;b`, or a JSON array `["a","b"]`; group
  names match case-insensitively.
- There is no browser login prompt for header-auth failures.
- `trusted_remotes` matches the **TCP peer** of the connection, not
  `X-Forwarded-For` — behind a chain of proxies, list the last hop. A request
  from an untrusted peer gets a page naming the declared identity, e.g.
  *user 'xyz' was declared by untrusted remote 192.168.1.5*.
- Only enable this when MiniCA is reachable exclusively through the proxy, or
  pin the proxy with `trusted_remotes`. CSRF protection stays enabled.

> **Note:** Like the original, this is intended for development and internal/test
> environments where standing up a full enterprise PKI is overkill.

minica

minica Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

minica

minica Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README