Class EvidenceCookies

java.lang.Object
org.frontcache.core.EvidenceCookies

public final class EvidenceCookies extends Object
Evidence cookies: a cookie whose value a client cannot produce without the node's secret - what the cookie-hmac:<name> predicate verifies, and what a serving plugin's evidence signer mints. The evidence pattern: the core decides who must prove something and checks the proof; whoever helped the visitor produce it (the origin's own challenge page, or a plugin under /fc-x/) only asks for a signature.

The value

  <expiry>.<mac>                     unbound
  <expiry>.<binding>.<mac>           bound: binding = ip | ua | ip_ua

  expiry = epoch seconds, decimal
  mac    = base64url, unpadded, of HMAC-SHA256(secret, message)
  message (unbound) = name "|" expiry
  message (bound)   = name "|" expiry "|" binding "|" <client address or ""> "|" <User-Agent or "">
The unbound form is the one an origin's challenge page writes with the shared secret (the visitor-type proposal's ยง8). The name is in the message, so a value minted for one cookie is worthless under another; a bound value is refused on a request the binding does not hold for, so a pass is not shared. The client address is the one ClientIpResolver resolves - through trusted proxies only - so a client cannot claim another's.

The secret

"front-cache.visitor.cookie-secret", at least 32 characters - a shorter one is refused, with an ERROR, because a value and its MAC are what an attacker has to guess the key offline from. Without one there are no evidence cookies: the predicate is refused at load (never "always true", never "always false and silent") and a challenge rule acts as a dry run. "front-cache.visitor.cookie-secret.previous" is accepted, never signed with - the overlap that lets a fleet rotate, as front-cache.edge-token.previous does. Read per call, as EdgeToken is.
  • Field Details

  • Method Details

    • isConfigured

      public static boolean isConfigured()
      Returns:
      whether this node has a usable secret - without one nothing is signed and nothing verifies
    • sign

      public static String sign(String name, long expiryEpochSeconds, String binding, String clientIp, String userAgent)
      Parameters:
      binding - null for an unbound value, else BIND_IP, BIND_UA or BIND_IP_UA
      clientIp - the resolved client address - required when the binding names it
      userAgent - the request's User-Agent, null as ""
      Returns:
      the cookie's value
      Throws:
      IllegalStateException - when the node has no secret
      IllegalArgumentException - for an unknown binding, or an ip binding without an address
    • holds

      public static boolean holds(RequestContext context, String name)
      Whether the request carries a valid, unexpired evidence cookie under name. Memoized per request and name; never throws - a request that cannot be read (a recycled one, a probe) holds none.