Certstream API

Each message carries two timestamps. seen is when this server processed the entry. submission_timestamp is when the CT log accepted the certificate and issued the Signed Certificate Timestamp (SCT), as defined by RFC 6962 §3.1. Both are Unix timestamps in seconds, with millisecond precision.

{
  "message_type": "certificate_update",
  "data": {
    "update_type": "X509LogEntry",
    "leaf_cert": {
      "subject": {
        "CN": "example.com",
        "O": "Example Inc",
        "C": "US",
        "aggregated": "/C=US/CN=example.com/O=Example Inc"
      },
      "issuer": {
        "CN": "R3",
        "O": "Let's Encrypt",
        "aggregated": "/CN=R3/O=Let's Encrypt"
      },
      "serial_number": "048A3F...",
      "not_before": 1703721600,
      "not_after": 1735257600,
      "fingerprint": "AB:CD:EF:01:...",
      "sha1": "AB:CD:EF:01:...",
      "sha256": "AB:CD:EF:01:...",
      "signature_algorithm": "sha256, rsa",
      "is_ca": false,
      "all_domains": [
        "example.com",
        "www.example.com"
      ],
      "extensions": {
        "keyUsage": "Digital Signature, Key Encipherment",
        "extendedKeyUsage": "serverAuth, clientAuth",
        "basicConstraints": "CA:FALSE",
        "subjectAltName": "DNS:example.com, DNS:www.example.com"
      },
      "as_der": "BASE64..."  // full-stream only
    },
    "chain": [...],  // full-stream only
    "cert_index": 1234567890,
    "seen": 1703808000.123,
    "submission_timestamp": 1703721600.456,  // when the CT log accepted this cert (RFC 6962 §3.1)
    "source": {
      "url": "ct.googleapis.com/logs/argon2025",
      "name": "Google Argon 2025"
    }
  }
}

{
  "message_type": "dns_entries",
  "data": [
    "example.com",
    "www.example.com",
    "*.example.com"
  ]
}

Unlike the full and lite streams, message_type is "dns_entries" rather than "certificate_update", and data is a JSON array of strings rather than an object with nested fields. Use this stream when you only need domain names.

WebSocket

Unfiltered WebSocket streams support permessage-deflate (RFC 7692). A client that offers it receives about 5 times less data on the lite stream, with nothing to change in its code: Python websockets, Node ws and browsers offer it by default. The stream is compressed once and shared by every compressing client, so the server's cost does not grow with them. A client starts at the next compressor reset, at most 128 messages after it connects, and after missing messages waits for the next one. Filtered streams, and clients that ask for server_no_context_takeover or a window below 15 bits, are sent uncompressed.

SSE

HTTP

REST API

Disabled by default. Enable with CERTSTREAM_API_ENABLED=true.

Every WebSocket and SSE endpoint accepts domain and issuer query parameters. Terms inside one parameter are alternatives; the two parameters narrow together.

wscat -c 'ws://localhost:8080/?domain=example.com,example.org'
curl -N 'http://localhost:8080/sse?stream=lite&domain=example.com&issuer=let%27s+encrypt'

Up to 20 terms per parameter and 64 distinct filters server-wide; beyond either limit the subscription is rejected with 400. Subscribers using the same filter share a group, so each filter is evaluated once per certificate regardless of how many clients use it, and the already-serialized payload is passed to the group rather than re-rendered per client. A server with no filtered subscribers performs no filter matching.

A filtered subscriber can lose messages in two places: on its own connection, and in the shared dispatcher before matching. Both are reported through the SSE gap event and the lag counters. Dispatcher loss cannot be attributed to a specific filter, so the reported count is raw certificates rather than matches.

Off by default. Enable with CERTSTREAM_STREAM_V2_ENABLED=true, then connect to ws://host:8080/v2 or /sse?stream=v2. The v1 streams are the CertStream shape and are unchanged; these fields appear only in v2.

{
  "message_type": "certificate_update",
  "version": 2,
  "data": {
    "source": {
      "name": "Let's Encrypt 'Sycamore2026h2'",
      "url": "https://mon.sycamore.ct.letsencrypt.org/2026h2",
      "log_id": "bP5QGUOoXqkWvFLRM+TcyR7xQRx9JYQg0XOAnhgY6zo=",
      "operator": "lets encrypt",
      "log_type": "static_ct"
    },
    "entry": {
      "index": 1000,
      "type": "x509",
      "observed_at": "2026-09-05T14:42:41.260Z",
      "submitted_at": "2025-09-09T01:01:44.517Z",
      "link": "https://mon.sycamore.ct.letsencrypt.org/2026h2/tile/data/003"
    },
    "verification": {
      "checkpoint_signature": "verified",
      "inclusion": "unverified"
    },
    "cert": { "...": "as in the lite stream" }
  }
}

(source.log_id, entry.index) identifies the record at its source; the certificate's SHA-256 identifies the certificate. One certificate appears in several logs at different indices, so the two are separate keys. source.operator is the operator name as the catalog spells it; the canonical key used by ct_log.operator_rate_limits and the metric labels is that name lowercased with punctuation collapsed.

verification

Records which checks were performed and what they found.

Off by default, and static-CT only. A valid checkpoint signature authenticates the tree root, but does not by itself prove that recently fetched entries are included in that tree, or that the tree is consistent with one observed earlier. Both properties can be verified from the log's own hash tiles.

CERTSTREAM_STATIC_CT_MERKLE_VERIFICATION=full certstream-server-rust

If a tile cannot be fetched (a 429, a timeout, or a partial tile at the head of the log that has no full tile yet), the entry is treated as unverified rather than invalid: it is marked inclusion: unverified and delivery continues. Only a hash mismatch drops the tile; certstream_static_ct_inclusion_unavailable and certstream_static_ct_inclusion_failed count the two cases.

Verification fetches share the per-operator rate limit with ingest, so ingest gets a smaller share of it. Consistency is anchored on the first checkpoint of each process, so a restart re-anchors.

Some static-CT logs serve an optional extension that publishes the names on the certificates in a data tile as compact JSON lines. Set CERTSTREAM_STATIC_CT_NAMES_TILES=prefer to read those instead of parsing data tiles; logs that do not serve the extension fall back to the normal path automatically.

Names-tile data is not authenticated by the CT tree: the extension cannot be checked for inclusion in a signed tree head. Entries collected this way are published as message_type: "dns_entries_unauthenticated", never as dns_entries. Cross-log dedup is unavailable in this mode, since there is no certificate hash to dedup on.

A names tile carries no certificate, so this mode requires domains_only to be the only enabled stream and cannot be combined with the JetStream output. These combinations are rejected during configuration validation.

A WebSocket subscriber misses whatever arrives while it is disconnected. Enable CERTSTREAM_NATS_ENABLED=true and records are also published to JetStream, where a durable consumer resumes from where it stopped.

The saved position follows acknowledgements, not reads, so a restart re-reads anything unacknowledged. Records carry a stable Nats-Msg-Id (<log_id>:<index>), so re-reads are deduplicated by the server. When the stream is full, CERTSTREAM_NATS_ON_FULL chooses block (default, pushes back on ingest) or drop.

Records are published to certstream.<operator>.<log>, so a consumer can subscribe to one operator or one log rather than the whole feed.

Cross-log dedup does not apply to the durable path: a certificate present in three logs produces three records.

Delivery is at-least-once for the entries this server reads, not exactly-once end to end. Records discarded in drop mode are not retried, and entries that fail to parse produce no record.

certstream-server-rust --backfill --log "Sycamore2026h2" --start 1000 --end 2000 --out range.jsonl

Writes one v2 record per line. The range is fixed up front and the live state file is never written, so a backfill cannot move a running server's position. Exits non-zero if any fetch failed.

# Quick start
docker run -d -p 8080:8080 \
  ghcr.io/reloading01/certstream-server-rust:latest

# With custom config
docker run -d -p 8080:8080 \
  -v ./config.yaml:/app/config.yaml \
  -v ./state:/app/state \
  ghcr.io/reloading01/certstream-server-rust:latest

# Cargo build
cargo build --release
./target/release/certstream-server-rust

# Docker Compose
docker compose up -d

services:
  certstream:
    image: ghcr.io/reloading01/certstream-server-rust:latest
    ports:
      - "8080:8080"
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./state:/app/state
    restart: unless-stopped

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://reloading01.github.io/packages/key.gpg \
  | sudo tee /etc/apt/keyrings/certstream.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/certstream.asc] https://reloading01.github.io/packages/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/certstream.list
sudo apt update
sudo apt install certstream-server-rust
sudo systemctl enable --now certstream-server-rust

sudo rpm --import https://reloading01.github.io/packages/key.gpg
sudo tee /etc/yum.repos.d/certstream.repo > /dev/null <<'REPO'
[certstream]
name=certstream-server-rust
baseurl=https://reloading01.github.io/packages/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://reloading01.github.io/packages/key.gpg
REPO
sudo dnf install certstream-server-rust
sudo systemctl enable --now certstream-server-rust

The packaged systemd unit reads settings from /etc/default/certstream-server-rust.

General

Protocols

Stream types

Disabled stream types are not serialized and their routes are not registered.

Connection limiting

Authentication

Rate limiting

CT log settings

CERTSTREAM_CT_LOG_FORCE_HTTP1_OPERATORS changes how many TCP connections concurrent fetches use. On its own it does not imply higher throughput.

Verification and collection

NATS JetStream

Hot reload

host: "0.0.0.0"
port: 8080
log_level: "info"
buffer_size: 1000

protocols:
  websocket: true
  sse: false
  metrics: true
  health: true
  example_json: true
  api: false

streams:
  full: true
  lite: true
  domains_only: true

ct_log:
  state_file: "/data/state.json"
  batch_size: 1024
  fetch_concurrency: 4
  poll_interval_ms: 500
  retry_max_attempts: 3
  request_timeout_secs: 30
  user_agent: "certstream-server-rust (security@example.com)"

dedup:
  capacity: 200000
  ttl_secs: 900

connection_limit:
  enabled: true
  max_connections: 10000
  per_ip_limit: 100

auth:
  enabled: false
  tokens:
    - "secret-token-1"
  header_name: "Authorization"

rate_limit:
  enabled: false
  max_tokens: 100
  refill_rate: 10

hot_reload:
  enabled: true

# Static CT logs (static-ct-api protocol).
# Use the monitoring prefix (mon.*) for read access.
# Trusted logs are also auto-discovered from the Google + Apple log lists.
static_logs:
  - name: "Let's Encrypt 'Willow' 2026h1"
    url: "https://mon.willow.ct.letsencrypt.org/2026h1/"
  - name: "Let's Encrypt 'Sycamore' 2026h1"
    url: "https://mon.sycamore.ct.letsencrypt.org/2026h1/"

Config search order: CERTSTREAM_CONFIG env var → ./config.yaml → ./config.yml → /etc/certstream/config.yaml

Logs without a checkpoint

Some RFC 6962 logs serve static-CT tiles but no /checkpoint. Set tree_size_source: get_sth on a static_logs entry to take the tree size from get-sth and read entries from the tiles. The server cannot verify such a log itself.

Forcing HTTP/1.1

Some operators limit per TCP connection, and HTTP/2 shares one connection across watchers. Operators listed under ct_log.force_http1_operators get their own HTTP/1.1 connections. The default is [digicert, microsec]: DigiCert throttles per connection, and Microsec resets HTTP/2 streams under concurrent tile fetches. Set it to [] to use HTTP/2 everywhere. The request rate does not change.

Per-operator pacing

Each operator gets one request budget shared by all of its logs: ct_log.default_operator_rate_limit_ms (25 ms) unless ct_log.operator_rate_limits names it. The default map holds Cloudflare to 125 ms, because Cloudflare blocks an IP for a minute after 100 requests in 10 seconds. Setting the map replaces the default, so keep cloudflare: 125 when adding an operator; {} removes it.

Throughput does not say how current the stream is. Watch certstream_ct_log_lag_entries and certstream_ct_log_ingest_delay_seconds per log; sustained growth is the signal. Results vary by host and workload.

Core

Static CT

Log lag

A healthy log is not necessarily a log the watcher is keeping up with. Health status tells you whether requests are succeeding. Lag tells you whether the local position is falling behind the log head. For alerting, sustained growth in lag is more useful than an absolute value, since a watcher legitimately has lag while catching up after a restart.

Bandwidth

Serialization is counted once per certificate for each enabled stream format. If serialized bytes stay high for a stream nobody consumes, disable that stream type under streams so it is not serialized.

Memory

RSS alone does not show how much memory the application currently has allocated. The jemalloc counters below separate the two: a gap between allocated and resident is allocator behaviour, while growth in allocated is the application holding data.

The current workload settles at roughly 80 MB RSS while processing about 420 certificates per second. If process RSS is much higher than jemalloc's allocated or resident counters, check the host's Transparent Huge Pages setting with cat /sys/kernel/mm/transparent_hugepage/enabled.

jemalloc settings can be overridden without rebuilding through _RJEM_MALLOC_CONF.