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

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, or a partial tile the log has moved past — the entry is treated as unverified rather than invalid: it is marked inclusion: unverified and delivery continues. Only a hash mismatch drops the tile. The two outcomes are counted separately as certstream_static_ct_inclusion_unavailable and certstream_static_ct_inclusion_failed, with the same split for consistency.

Verification fetches use the same per-operator rate limiter as ingest, so enabling this does not increase the request rate an operator sees. Consistency is anchored on the first checkpoint of each process; the previous root is held in memory rather than the state file, so a restart re-anchors instead of proving continuity across it.

Measured over 80 seconds against the live static-CT log set: 36,570 entries verified as included and 78 consistency proofs verified, with 11 tiles and 4 proofs unavailable and no mismatches.

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.

Measured on Geomys' Tuscolo, a names tile is roughly 3% of the size of the equivalent data tile (6.6 KB against 226 KB) and requires no X.509 parsing.

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.

To reduce record loss and duplicate delivery, the JetStream path uses three additional mechanisms:

• The saved position follows acknowledgements, not reads. A watcher that has read to entry N but had only M acknowledged persists M, and a restart re-reads M..N. The tracker advances on the contiguous acknowledged prefix, so an out-of-order acknowledgement cannot step over a gap.
• Republished records keep a stable identity. The Nats-Msg-Id is <log_id>:<index>, the same address the v2 output uses, so a re-read after a restart is deduplicated by the server inside its duplicate window (15 minutes by default) instead of appearing twice.
• Stream-full behavior is configurable. The stream is created with discard: new, so it refuses the write rather than deleting records a stopped consumer had not read. CERTSTREAM_NATS_ON_FULL decides what happens next: block (default) retries the record until the server stores it, and the queue behind it pushes back on ingest; drop gives up on the record and lets the position move past it.

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 record is addressed by (log_id, index), so a certificate present in three logs produces three records; dropping the duplicates would leave gaps in those logs' acknowledged positions. The live WebSocket and SSE streams still deduplicate.

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 index range is fixed before the first request, making the job finite and repeatable, and the live state file is never written, so a backfill cannot move the position of a running server. Supports both RFC 6962 get-entries and static-CT data tiles, using the same per-operator rate limit as the watchers. Chain certificates are omitted for static-CT logs, which serve issuers from a separate endpoint. Exits non-zero if any fetch failed.

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; see the measurements.

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)"
  force_http1_operators: ["DigiCert"]

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

Throughput and resource use do not describe how current the stream is. Over the same run the median log sat about 20 minutes behind its head, and 19 of 45 logs were more than 5,000 entries behind, with no subscriber loss and no runaway growth. The delay rose during initial catch-up, peaked near 29 minutes, and then held. certstream_ct_log_ingest_delay_seconds and certstream_ct_log_lag_entries report both figures per log; soak/measure.sh samples them alongside CPU and RSS.

Results are specific to this benchmark and will 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. That case is described in the jemalloc RSS write-up.