139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# checker-dane
|
|
|
|
DANE / TLSA checker for [happyDomain](https://www.happydomain.org/).
|
|
|
|
Bound to the `svcs.TLSAs` service: groups the user's TLSA records by
|
|
`(port, proto, base)`, publishes one `tls.endpoint.v1` discovery entry
|
|
per endpoint so [`checker-tls`](https://git.happydns.org/checker-tls)
|
|
probes them, then matches each TLSA against the observed certificate
|
|
chain per RFC 6698.
|
|
|
|
## Usage
|
|
|
|
### Standalone HTTP server
|
|
|
|
```bash
|
|
# Build and run
|
|
make
|
|
./checker-dane -listen :8080
|
|
```
|
|
|
|
The server exposes:
|
|
|
|
- `GET /health`, health check
|
|
- `POST /collect`, collect DANE observations (happyDomain external checker protocol)
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
make docker
|
|
docker run -p 8080:8080 happydomain/checker-dane
|
|
```
|
|
|
|
### happyDomain plugin
|
|
|
|
```bash
|
|
make plugin
|
|
# produces checker-dane.so, loadable by happyDomain as a Go plugin
|
|
```
|
|
|
|
The plugin exposes a `NewCheckerPlugin` symbol returning the checker
|
|
definition and observation provider, which happyDomain registers in its
|
|
global registries at load time.
|
|
|
|
### Versioning
|
|
|
|
The binary, plugin, and Docker image embed a version string overridable
|
|
at build time:
|
|
|
|
```bash
|
|
make CHECKER_VERSION=1.2.3
|
|
make plugin CHECKER_VERSION=1.2.3
|
|
make docker CHECKER_VERSION=1.2.3
|
|
```
|
|
|
|
### happyDomain remote endpoint
|
|
|
|
Set the `endpoint` admin option for the DANE checker to the URL of the
|
|
running checker-dane server (e.g., `http://checker-dane:8080`).
|
|
happyDomain will delegate observation collection to this endpoint.
|
|
|
|
## Behavior
|
|
|
|
- **Usage 0 (PKIX-TA) / 1 (PKIX-EE)**: TLSA match + publicly trusted PKIX chain required.
|
|
- **Usage 2 (DANE-TA) / 3 (DANE-EE)**: TLSA acts as the trust anchor; PKIX validity is informational.
|
|
- **Selector** 0 (Cert) / 1 (SPKI) and **MatchingType** 0/1/2 (Full / SHA-256 / SHA-512)
|
|
are matched against the chain slot implied by the usage.
|
|
- Common STARTTLS ports (25, 110, 143, 389, 587, 5222, 5269) are auto-mapped;
|
|
override via the `starttls` option keyed by `"<port>/<proto>"`.
|
|
|
|
## Protocol
|
|
|
|
### POST /collect
|
|
|
|
Request:
|
|
```json
|
|
{
|
|
"key": "dane_checks",
|
|
"target": {"userId": "...", "domainId": "..."},
|
|
"options": {
|
|
"domain_name": "example.com",
|
|
"subdomain": "",
|
|
"service": { "_svctype": "svcs.TLSAs", "_domain": "example.com.", "Service": { "tlsa": [ ... ] } },
|
|
"probeTimeoutMs": 5000,
|
|
"starttls": {"587/tcp": "submission"}
|
|
}
|
|
}
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"data": {
|
|
"targets": [
|
|
{
|
|
"owner": "_443._tcp.example.com",
|
|
"host": "example.com",
|
|
"port": 443,
|
|
"proto": "tcp",
|
|
"ref": "tls.endpoint.v1:...",
|
|
"records": [
|
|
{"usage": 3, "selector": 1, "matching_type": 1, "certificate": "abcd..."}
|
|
]
|
|
}
|
|
],
|
|
"collected_at": "2026-04-24T12:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
## License & licensing roadmap
|
|
|
|
This project is currently licensed under the **GNU Affero General Public
|
|
License v3.0** (see `LICENSE`), because it still decodes the on-wire
|
|
`happydns.ServiceMessage` shape from the happyDomain server module
|
|
(`git.happydns.org/happyDomain/model`), which is itself distributed
|
|
under AGPL-3.0 and a commercial license.
|
|
|
|
The core checker types (`CheckerOptions`, `CheckerDefinition`,
|
|
`ObservationProvider`, `CheckRule`, …) have already been migrated to
|
|
[`checker-sdk-go`](https://git.happydns.org/checker-sdk-go); the TLS
|
|
endpoint contract consumed from related observations lives in
|
|
[`checker-tls`](https://git.happydns.org/checker-tls). Only the
|
|
service-message type remains on the AGPL side.
|
|
|
|
**Planned relicensing:** as soon as the remaining `ServiceMessage`
|
|
dependency has been removed (moved into a dedicated permissively
|
|
licensed module), this project will be relicensed under the **MIT
|
|
License**, in line with the rest of the happyDomain checker ecosystem
|
|
(see `checker-dummy` for the target shape).
|
|
|
|
**Contributors notice:** by submitting a contribution to this
|
|
repository, you accept that your contribution will be relicensed from
|
|
AGPL-3.0 to MIT at the time of the relicensing described above. If you
|
|
do not agree with this, please do not submit contributions until the
|
|
relicensing has taken place.
|
|
|
|
The third-party Apache-2.0 attributions for `checker-sdk-go` and
|
|
`checker-tls` are recorded in `NOTICE` and must accompany any binary or
|
|
source redistribution of this project.
|