nginx validators are only as sound as their representation identity

Thu, 17 Feb 2028 00:00:00 +0000

A validator lets a recipient ask whether its stored representation still matches the selected one. A successful conditional GET can return 304 without retransmitting the body. Freshness is a separate decision: it determines when a stored response can be reused without that request. An ETag does not itself specify a cache lifetime, and a 304 is not a replacement body.

When it breaks

Calling every ETag a body hash hides an important nginx detail. In the tested 1.28.0 static-file implementation, the generated tag combines modification time and content length. It does not hash file contents. Replacing bytes while preserving both inputs can retain the same tag, allowing a client holding different bytes to receive an apparently successful validation.

Weak and strong validators also serve different comparisons. A strong validator must distinguish representation data changes for uses requiring byte identity. A weak validator can group representations considered semantically equivalent, even when their bytes differ. The W/ prefix does not mean “byte-equivalent changes,” nor does it make the tag suitable for every precondition or resumable byte-range operation.

Conditional requests do not guarantee that application work was avoided. A server might compute the representation before deciding that its validator matches. Static nginx handling has no application renderer in this example. A smaller response proves saved body transfer here; it does not establish a universal reduction in database queries, rendering cost, or origin request count.

Check it quickly

Save the script as check-validators.py, obtain the pinned nginx image, and run it with Python and Docker. It serves a disposable four-byte static file through host loopback using nginx 1.28.0. File times are deliberately controlled inside the experiment container; the host and Docker VM clocks are not changed:

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
files={'asset.txt':'AAAA','noetag.txt':'AAAA'}
with lab(config('location = /noetag.txt { etag off; }'),files) as (proxy,request):
 def timestamp(value):docker('exec',proxy,'touch','-m','-d','@'+str(value),'/srv/asset.txt')
 timestamp(1577836800)
 status,headers,body=request('/asset.txt');assert status==200 and body==b'AAAA'
 tag=headers['etag'];modified=headers['last-modified'];results={'etag':tag,'last_modified':modified}
 cases={
 'matching_tag':({'If-None-Match':tag},304),
 'weak_comparison':({'If-None-Match':'W/'+tag},304),
 'matching_date':({'If-Modified-Since':modified},304),
 'tag_takes_precedence':({'If-None-Match':'"different"','If-Modified-Since':modified},200),
 'weak_if_match_rejected':({'If-Match':'W/'+tag},412),
 }
 for name,(conditions,expected) in cases.items():
 status,_,body=request('/asset.txt',headers=conditions);assert status==expected,(name,status)
 if status==304:assert body==b''
 results[name]=status
 docker('exec',proxy,'sh','-c','printf BBBB > /srv/asset.txt');timestamp(1577836800)
 status,current,body=request('/asset.txt');assert status==200 and body==b'BBBB' and current['etag']==tag
 status,_,body=request('/asset.txt',headers={'If-None-Match':tag});assert status==304 and body==b''
 results['changed_bytes_preserved_metadata']=status
 timestamp(1577836802)
 status,current,body=request('/asset.txt',headers={'If-None-Match':tag})
 assert status==200 and body==b'BBBB' and current['etag']!=tag and current['last-modified']!=modified
 results['changed_metadata']={'status':status,'etag':current['etag']}
 status,current,_=request('/noetag.txt');assert status==200 and 'etag' not in current
 print(json.dumps(results,sort_keys=True))

The initial file contains AAAA, has modification time 2020-01-01, and produces ETag "5e0be100-4". A GET carrying that tag in If-None-Match returns 304 with an empty body. Adding W/ to the request tag still returns 304 because this condition uses weak comparison. An equal If-Modified-Since date also returns 304 in the tested configuration.

When a nonmatching If-None-Match accompanies the matching date, the response is 200. The entity-tag condition takes precedence over the date condition; a client cannot make the mismatching tag disappear by also supplying a favorable timestamp. The separate If-Match check rejects the weak request tag with 412. That test is a GET precondition check, not an executed write workflow.

Next, the script changes AAAA to BBBB and restores the original modification time. An unconditional GET proves the bytes changed, while the tag remains identical. Sending the old tag now yields 304 again. This deliberate counterexample demonstrates why metadata preservation during deployment can violate the intended identity contract, even though nginx follows its configured tag-generation algorithm.

Advancing the file time by two seconds changes the generated tag and Last-Modified value. The old entity tag then receives 200 with BBBB. The final control disables etag on another resource and confirms that no ETag header is generated there. Disabling tags removes that validator; it does not automatically provide a stronger replacement or disable every form of caching.

Make deployments preserve the validator contract

For assets whose bytes must remain addressable independently, content-derived filenames can separate versions at the URL level. For stable URLs, ensure deployment metadata changes when representation bytes change, or deliberately supply an appropriate content-derived validator through the serving application. Review rapid same-length updates as well as tools that preserve timestamps while copying new content.

Treat Last-Modified with similar care. It represents a timestamp with limited precision, not a cryptographic identity. Do not assume every date is a strong validator for range resumption. The relevant protocol conditions and the server’s update behavior matter, especially when multiple revisions can occur within the timestamp’s effective resolution.

Finally, test the representation actually delivered through intermediaries and content codings. A validator for one selected representation must not falsely identify another byte sequence where strong comparison is required. Keep cache lifetime, validation, privacy, and byte integrity as explicit decisions, and verify both the unchanged and changed cases during deployment checks.

Sources

RFC 9110 HTTP Semantics, strong and weak validators, conditional precedence, and 304/412 responses, checked 2026-09-12.
RFC 9111 HTTP Caching, freshness, stored responses, and successful validation, checked 2026-09-12.
nginx 1.28.0 core source, the static ETag calculation from modification time and content length, checked 2026-09-12.
nginx HTTP core module, etag and if_modified_since configuration, checked 2026-09-12.

Etag · XB Field Notes

nginx validators are only as sound as their representation identity

When it breaks

Check it quickly

Make deployments preserve the validator contract

Sources