This is a documentation clarification request (not a bug report). When ssl_ech_file is specified multiple times for ECH key rotation, the ordering is significant, but the directive documentation does not mention it. In the current implementation, only the first file is used to populate the ECHConfigList included in ECH retry-configs; subsequent files are loaded without being included in retry-configs. This order-dependent behavior is easy to miss and can cause operational mistakes during key rotation.
How I encountered the problem:
While reviewing the ECH implementation, I noticed the order-dependent behavior in the code path that loads ECH PEM files. The first file is loaded with OSSL_ECH_FOR_RETRY and the rest with OSSL_ECH_NO_RETRY: nginx/src/event/ngx_event_openssl.c at 9e7f0f4c538e5bbd7a5662786724491ee4eaa42e · nginx/nginx · GitHub
Solutions I’ve tried:
I checked the nginx.org documentation for ssl_ech_file but couldn’t find any mention that the first file is treated specially for retry-configs, or that the directive order matters.
Version of NGINX or NGINX adjacent software (e.g. NGINX Gateway Fabric):
NGINX Open Source (ECH support series; behavior shown in the source link above).
Deployment environment:
N/A (documentation/behavior clarification request).
Minimal NGINX config to reproduce your issue (preferably running on https://tech-playground.com/playgrounds/nginx for ease of debugging, and if not as a code block):
N/A (not a runtime error; this is an ordering rule). For illustration, the intended operational usage seems to be:
- first
ssl_ech_file: current key (used for retry-config ECHConfigList) - additional
ssl_ech_file: previous keys (accepted for decryption, not included in retry-configs)
NGINX access/error log:
N/A.
Suggested doc change:
Please consider documenting on Module ngx_http_ssl_module (and possibly the stream SSL docs as well) something like:
“ssl_ech_file can be specified multiple times. Only the first file is used to populate the ECHConfigList sent in ECH retry-configs; additional files are loaded to accept older keys and are not included in retry-configs. The order matters.”