WAF++ Validation Registry

About WAF++ Validation

Cryptographic design, certificate chain, and trust model of official validation.

WAF++ PASS official validation turns a compliance scan into a cryptographically signed, independently verifiable certificate.

Official validation is a mandatory three-step process:

  1. Your organization signs the run locally with its own Ed25519 key.
  2. A trusted wafpass-server receives the run, verifies the local attestation, and signs the canonical run hash with its own Ed25519 attestation key.
  3. The WAF++ validation gateway (wafpass-validation) authenticates the caller, verifies the server’s gateway-issued sub-CA certificate, verifies the local attestation, and countersigns the canonical run hash with the gateway intermediate key.

This makes the gateway the monetizable, mandatory central validator for every official WAF++ PASS validation.

Trust hierarchy

┌──────────────────────────────────────────┐
│  WAF++ Root CA (offline ceremony)        │  ← root.key / root.crt
│  Long-lived root of trust                │     root.key never on a server
└──────────────┬───────────────────────────┘
               │ signs intermediate CA cert
┌──────────────▼───────────────────────────┐
│  WAF++ Validation Intermediate CA      │  ← intermediate.key / intermediate.crt
│  Lives inside wafpass-validation        │     signs every official validation
└──────────────┬───────────────────────────┘
               │ issues sub-CA certificate
┌──────────────▼───────────────────────────┐
│  wafpass-server Sub-CA certificate     │  ← server.crt (issued by gateway)
│  Held by each trusted wafpass-server    │
└──────────────┬───────────────────────────┘
               │ presents sub-CA cert + local attestation
┌──────────────▼───────────────────────────┐
│  Validation envelope per run             │  ← signed by org key + server key + gateway
│  Immutable record of one WAF++ PASS run  │
└──────────────────────────────────────────┘

Every validation therefore carries three cryptographic facts:

  1. Local attestation — signed by the organization key that ran the scan.
  2. Server attestation — signed by the wafpass-server Ed25519 key that attests to the run before forwarding it to the gateway.
  3. Gateway countersignature — an X.509 certificate chain signed by the gateway intermediate CA and rooted in the gateway root CA.

All three signatures are over the canonical hash of the run result, which is a deterministic SHA-256 digest of the JSON result produced by wafpass check --output json.

How the certificate chain is created

Step What happens Where the private key lives
1 The WAF++ root CA key pair is generated during an offline ceremony. root.key is stored in an HSM or air-gapped backup, never on the gateway host.
2 The gateway intermediate CA key pair is generated on the validation gateway. intermediate.key lives only inside wafpass-validation.
3 The root CA signs the intermediate certificate (intermediate.crt). Done once or on rotation inside the gateway.
4 The gateway issues a sub-CA certificate to each trusted wafpass-server (server.crt). server.key lives only inside the wafpass-server instance.
5 The CLI/dashboard submits the run to the validation gateway with an API key and the server’s sub-CA certificate. wafpass-validation holds API-key hashes and the root/intermediate keys.
6 The gateway verifies the server certificate chain, verifies the local attestation, and countersigns the validation hash. Happens inside wafpass-validation.
7 The gateway persists the official validation in PostgreSQL and returns the countersignature. The validation record is immutable.

The envelope returned to the CLI contains the gateway certificate chain:

{
  "certificate_chain": [
    "-----BEGIN CERTIFICATE-----\n... intermediate.crt ...\n-----END CERTIFICATE-----",
    "-----BEGIN CERTIFICATE-----\n... root.crt ...\n-----END CERTIFICATE-----"
  ],
  "server_signature": "..."
}

Where to get the certificates

1. From the gateway (public endpoint)

The gateway publishes its root certificate at:

GET /api/v1/validations/root.crt

Example:

curl -s https://validate.waf2p.dev/api/v1/validations/root.crt > waf++-root.crt

2. From a validation envelope

Every official envelope already includes the full chain, so if you have the envelope file you already have intermediate.crt and root.crt.

3. From this registry (root certificate page)

The Root Cert page helps you download the root certificate directly from the gateway.

How a validation is submitted

When the CLI submits a run:

export WAFPASS_VALIDATION_URL=https://validate.waf2p.dev
export WAFPASS_VALIDATION_API_KEY=wafpass_...
export WAFPASS_SERVER_CERTIFICATE=/path/to/wafpass-server.crt
wafpass validate official wafpass-result.json

the following happens:

  1. The CLI signs the canonical run hash with the organization key (~/.wafpass/validation.key).
  2. The CLI sends {server_certificate, local_attestation, run} to the validation gateway at POST /api/v1/validations with an X-Api-Key header.
  3. The gateway verifies the API key and verifies the server sub-CA certificate against its root CA and the registered ServerCertificate table.
  4. The gateway verifies the local attestation by recomputing the canonical hash and checking the Ed25519 signature.
  5. The gateway signs the canonical hash with intermediate.key and stores the official validation in PostgreSQL.
  6. The gateway returns ValidationOut containing the validation ID, signatures, certificate chain, and public badge/verification URLs.
  7. The CLI assembles the final ValidationEnvelopeSchema and writes:
    • wafpass-validation-<hash>.json
    • wafpass-badge-<hash>.json
    • wafpass-badge-<hash>.svg
    • wafpass-certificate-<hash>.pdf

How to create or rotate the chain in a private deployment

In production the root key should be generated offline and mounted into the gateway as a secret. wafpass-validation can auto-generate a dev chain on first start when no key material is present. To run a private authority:

  1. Create the root key offline:
openssl genpkey -algorithm ED25519 -out root.key
chmod 400 root.key
  1. Create the root certificate:
openssl req -new -x509 -key root.key -out root.crt \
  -subj "/CN=WAF++ Root CA" -days 3650

  1. Mount root.key, root.crt, and a fresh intermediate.key into wafpass-validation at WAFPASS_ROOT_KEYS_DIR (the gateway will generate the intermediate certificate if it is missing).

  2. Use the gateway admin endpoint to issue a sub-CA certificate for each wafpass-server:

curl -X POST https://validate.waf2p.dev/api/admin/server-certs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"prod-1","server_public_key_pem":"-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"}'
  1. Configure wafpass-server with the returned server.crt via WAFPASS_SERVER_SUBCA_CERT (or place it in WAFPASS_VALIDATION_KEYS_DIR as server.crt as a fallback).

What this registry does

The WAF++ validation registry is a dynamic FastAPI gateway that:

  • Serves the public marketing and verification pages with the same WAF++ design.
  • Issues and revokes API keys for validation submissions.
  • Issues sub-CA certificates to trusted wafpass-server instances.
  • Records every submission in PostgreSQL for audit, verification, public badges, and monetization reporting.
  • Signs every official validation with the gateway intermediate CA.

This makes it the mandatory central validator for every official WAF++ PASS validation.

Supported endpoints

The gateway exposes these public endpoints:

Endpoint Purpose
GET /api/v1/validations/{id}/verify Signed verification record
GET /api/v1/validations/{id}/badge.svg Embeddable status badge
GET /api/v1/validations/{id}/badge.json Portable badge JSON
GET /api/v1/validations/{id}/certificate.pdf Printable certificate
GET /api/v1/validations/root.crt Root certificate
GET /api/v1/revocations Signed revocation list

Admin endpoints (API-key management, server-certificate issuance, revocation) require a bearer token from the dedicated Keycloak realm with the wafpass-admin role, or the legacy X-Admin-Key header when Keycloak is not configured.

Verifying without this site

The registry is optional. Anyone can verify directly with curl and the CLI:

# Fetch the signed record
curl -s https://validate.waf2p.dev/api/v1/validations/123e4567-.../verify

# Fetch the root certificate
curl -s https://validate.waf2p.dev/api/v1/validations/root.crt > waf++-root.crt

# Verify the envelope file
wafpass verify wafpass-validation-<hash>.json --root-public-key waf++-root.crt

This makes the validation system suitable for audit handouts, compliance portals, and CI/CD artifacts that must remain verifiable years after they were issued.