checker-dane

DANE / TLSA checker for happyDomain.

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 probes them, then matches each TLSA against the observed certificate chain per RFC 6698.

Usage

Standalone HTTP server

# 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

make docker
docker run -p 8080:8080 happydomain/checker-dane

happyDomain plugin

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:

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:

{
  "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:

{
  "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; the TLS endpoint contract consumed from related observations lives in 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.

4.1 KiB Raw Blame History