Class EvidenceCookies
java.lang.Object
org.frontcache.core.EvidenceCookies
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 achallenge 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 Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionstatic booleanholds(RequestContext context, String name) Whether the request carries a valid, unexpired evidence cookie undername.static booleanstatic String
-
Field Details
-
SECRET_PROPERTY
- See Also:
-
PREVIOUS_SECRET_PROPERTY
- See Also:
-
MIN_SECRET_LENGTH
public static final int MIN_SECRET_LENGTH- See Also:
-
NAME
A cookie name the predicate may name: an RFC 6265 token, short. -
BIND_IP
- See Also:
-
BIND_UA
- See Also:
-
BIND_IP_UA
- See Also:
-
-
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, elseBIND_IP,BIND_UAorBIND_IP_UAclientIp- the resolved client address - required when the binding names ituserAgent- the request's User-Agent, null as ""- Returns:
- the cookie's value
- Throws:
IllegalStateException- when the node has no secretIllegalArgumentException- for an unknown binding, or an ip binding without an address
-
holds
Whether the request carries a valid, unexpired evidence cookie undername. Memoized per request and name; never throws - a request that cannot be read (a recycled one, a probe) holds none.
-