Skip to content

Commit 08c73b4

Browse files
sftcdnotroj
sftcd
authored and
notroj
committed
fixup! ECH collected changes
1 parent 053f3a2 commit 08c73b4

File tree

3 files changed

+156
-0
lines changed

3 files changed

+156
-0
lines changed

‎changes-entries/ech.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
*) mod_ssl: Add support for Encrypted Client Hello (ECH)
3+
Github #551 [Stephen Farrell]

‎docs/ECH-build.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,3 +219,35 @@ of the configuration, without dropping existing connections.
219219
> code](https://github.com/lighttpd/lighttpd1.4/blob/master/src/mod_openssl.c#L799)
220220
> for details.
221221
222+
## Building the docs
223+
224+
Early comments suggested moving some of the above into XML source
225+
docuemnts, especially `docs/manual/mod/mod_ssl.xml`. That then needs
226+
to be built which requires another repo:
227+
228+
```bash
229+
$ cd /home/user/code/httpd
230+
$ cd docs/manual
231+
$ git clone https://github.com/apache/httpd-docs-build.git build
232+
$ cd build
233+
```
234+
235+
To get things working I needed to install an OpenJDK version,
236+
to set the `JAVA_HOME` environment variable and to also modify
237+
the `build.sh` script to remove `-Xbootclasspath/p:"$LOCALCLASSPATH"`
238+
from the last line of the script, and then:
239+
240+
```bash
241+
$ ./build.sh
242+
...
243+
```
244+
245+
This re-builds many files we don't want to commit, so only add the
246+
`mod_ssl.xml` file and directly derived files that seem to mention ECH, at
247+
present, that set being:
248+
249+
- `docs/manual/mod/mod_ssl.xml`
250+
- `docs/manual/mod/mod_ssl.html.en.utf8`
251+
- `docs/manual/mod/directives.html.en.utf8`
252+
- `docs/manual/mod/quickreference.html.en.utf8`
253+

‎docs/manual/mod/mod_ssl.xml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,9 @@ compatibility variables.</p>
118118
<tr><td><code>SSL_CLIENTHELLO_SIG_ALGOS</code></td> <td>string</td> <td>Value of Signature Algorithms extension (13) from ClientHello as four hex encoded characters per item</td></tr>
119119
<tr><td><code>SSL_CLIENTHELLO_ALPN</code></td> <td>string</td> <td>Value of ALPN extension (16) from ClientHello as hex encoded string including leading string lengths</td></tr>
120120
<tr><td><code>SSL_CLIENTHELLO_VERSIONS</code></td> <td>string</td> <td>Value of Supported Versions extension (43) from ClientHello as four hex encoded characters per item</td></tr>
121+
<tr><td><code>SSL_ECH_STATUS</code></td> <td>string</td> <td><code>success</code> means that others also mean what they say</td></tr>
122+
<tr><td><code>SSL_ECH_INNER_SNI</code></td> <td>string</td> <td>SNI value that was encrypted in ECH (or `NONE`)</td></tr>
123+
<tr><td><code>SSL_ECH_OUTER_SNI</code></td> <td>string</td> <td>SNI value that was seen in plaintext SNI (or `NONE`)</td></tr>
121124
</table>
122125

123126
<p><em>x509</em> specifies a component of an X.509 DN; one of
@@ -3016,4 +3019,122 @@ httpd -t -D DUMP_SSL_POLICIES
30163019
</usage>
30173020
</directivesynopsis>
30183021

3022+
<directivesynopsis>
3023+
<name>SSLECHKeyDir</name>
3024+
<description>Load the set of Encrypted Client Hello (ECH) PEM files in the named directory</description>
3025+
<syntax>SSLECHKeyDir <em>dirname</em></syntax>
3026+
<contextlist><context>server config</context></contextlist>
3027+
<compatibility>Available in httpd 2.X.0 and later</compatibility>
3028+
3029+
<usage>
3030+
3031+
<p>
3032+
ECH is specified in
3033+
<a href="https://datatracker.ietf.org/doc/draft-ietf-tls-esni/">draft-ietf-tls-esni</a>
3034+
httpd supports ECH "shared-mode" where the httpd instance does the
3035+
ECH decryption and also hosts both the ECH `public-name` and `backend` web
3036+
sites.
3037+
</p>
3038+
3039+
<p>
3040+
The <code>SSLECHKeyDir</code> directive
3041+
names the directory where ECH PEM files (named <code>*.ech</code>) are stored.
3042+
Once an ECH PEM file is successfully loaded, httpd will perform ECH decryption
3043+
and, if that succeeds, will process the relevant TLS session using the
3044+
SNI from the inner ClientHello.
3045+
</p>
3046+
3047+
<example><title>Example ECH Config</title>
3048+
<highlight language="config">
3049+
...
3050+
SSLEngine On
3051+
SSLProtocol TLSv1.3
3052+
SSLECHKeyDir /etc/apache2/echkeydir
3053+
...
3054+
# virtual hosts
3055+
&lt;VirtualHost *:443&gt;
3056+
SSLEngine On
3057+
SSLProtocol TLSv1.3
3058+
ServerName example.com
3059+
DocumentRoot "/var/www/dir-example.com"
3060+
&lt;/VirtualHost&gt;
3061+
&lt;VirtualHost *:443&gt;
3062+
SSLEngine On
3063+
SSLProtocol TLSv1.3
3064+
ServerName foo.example.com
3065+
DocumentRoot "/var/www/dir-foo.example.com"
3066+
&lt;/VirtualHost&gt;
3067+
...
3068+
</highlight>
3069+
</example>
3070+
3071+
<note><title>ECH Key Generation and Publication</title>
3072+
<p>
3073+
In the above, we describe a configuration that uses <code>example.com</code> as the
3074+
ECH <code>public-name</code> and where <code>foo.example.com</code> is a web-site for which we want
3075+
ECH to be used, with both hosted on the same httpd instance.
3076+
</p>
3077+
<p>
3078+
Using ECH requries that httpd load an ECH key pair with a private value for ECH
3079+
decryption. Browsers will require that the public component of that key pair be
3080+
published in the DNS. With OpenSSL we generate and store that key pair in an ECH PEM
3081+
formatted file as shown below.
3082+
</p>
3083+
<p>
3084+
To generate ECH PEM files, use the ECH-enabled openssl command line
3085+
to generate an ECH key pair and store the result in an ECH PEM file.
3086+
You must also supply the <code>public-name</code> required by the ECH protocol.
3087+
</p>
3088+
<p>
3089+
Key generation operations should be carried out under whatever local account is
3090+
used for httpd configuration.
3091+
</p>
3092+
<example><title>Example: ECH Key Generation</title>
3093+
<highlight language="config">
3094+
~# OSSL=/home/user/code/openssl/apps/openssl
3095+
~# mkdir -p /etc/apache2/echkeydir
3096+
~# chmod 700 /etc/apache2/echkeydir
3097+
~# cd /etc/apache2/echkeydir
3098+
~# $OSSL ech -public-name example.com -o example.com.pem.ech
3099+
~# cat example.com.pem.ech
3100+
-----BEGIN PRIVATE KEY-----
3101+
MC4CAQAwBQYDK2VuBCIEIJi22Im2rJ/lJqzNFZdGfsVfmknXAc8xz3fYPhD0Na5I
3102+
-----END PRIVATE KEY-----
3103+
-----BEGIN ECHCONFIG-----
3104+
AD7+DQA6QwAgACA8mxkEsSTp2xXC/RUFCC6CZMMgdM4x1iTWKu3EONjbMAAEAAEA
3105+
AQALZXhhbXBsZS5vcmcAAA==
3106+
-----END ECHCONFIG-----
3107+
</highlight>
3108+
</example>
3109+
<p>
3110+
The ECHConfig value then needs to be published in an HTTPS resource record in
3111+
the DNS, so as to be accessible as shown below:
3112+
</p>
3113+
<example>
3114+
$ dig +short HTTPS foo.example.com
3115+
1 . ech=AD7+DQA6QwAgACA8mxkEsSTp2xXC/RUFCC6CZMMgdM4x1iTWKu3EONjbMAAEAAEAAQALZXhhbXBsZS5vcmcAAA==
3116+
$
3117+
</example>
3118+
<p>
3119+
Various other fields may be included in an HTTPS resource record. For many
3120+
httpd deployments, existing methods for publishing DNS records may be used to
3121+
achieve the above. In some cases, one might use
3122+
<a href="https://datatracker.ietf.org/doc/html/draft-ietf-tls-wkech">
3123+
A well-known URI for publishing service parameters</a>
3124+
designed to assist web servers in handling e.g. frequent ECH key rotation.
3125+
</p>
3126+
</note>
3127+
3128+
<note><title>Reloading ECH Keys</title>
3129+
3130+
<p>
3131+
Giving httpd a command line argument of <code>-k graceful</code> causes a graceful reload
3132+
of the configuration, without dropping existing connections.
3133+
</p>
3134+
3135+
</note>
3136+
3137+
</usage>
3138+
</directivesynopsis>
3139+
30193140
</modulesynopsis>

0 commit comments

Comments
 (0)