From 9f415979fbd0f2a9257ec1d86ddfe849ebad8c50 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Sat, 15 Sep 2018 11:15:04 +0900 Subject: [PATCH] Update manual pages --- doc/h2load.1 | 2 +- doc/nghttp.1 | 2 +- doc/nghttpd.1 | 2 +- doc/nghttpx.1 | 65 ++++++++++++++++++++++++++++++++++++++++++++--- doc/nghttpx.1.rst | 57 ++++++++++++++++++++++++++++++++++++++--- 5 files changed, 118 insertions(+), 10 deletions(-) diff --git a/doc/h2load.1 b/doc/h2load.1 index 99e9f1b9..38a66bb9 100644 --- a/doc/h2load.1 +++ b/doc/h2load.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "H2LOAD" "1" "Sep 02, 2018" "1.33.0" "nghttp2" +.TH "H2LOAD" "1" "Sep 15, 2018" "1.34.0-DEV" "nghttp2" .SH NAME h2load \- HTTP/2 benchmarking tool . diff --git a/doc/nghttp.1 b/doc/nghttp.1 index 917a6686..97d0b494 100644 --- a/doc/nghttp.1 +++ b/doc/nghttp.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTP" "1" "Sep 02, 2018" "1.33.0" "nghttp2" +.TH "NGHTTP" "1" "Sep 15, 2018" "1.34.0-DEV" "nghttp2" .SH NAME nghttp \- HTTP/2 client . diff --git a/doc/nghttpd.1 b/doc/nghttpd.1 index 674f3207..3875c2e3 100644 --- a/doc/nghttpd.1 +++ b/doc/nghttpd.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPD" "1" "Sep 02, 2018" "1.33.0" "nghttp2" +.TH "NGHTTPD" "1" "Sep 15, 2018" "1.34.0-DEV" "nghttp2" .SH NAME nghttpd \- HTTP/2 server . diff --git a/doc/nghttpx.1 b/doc/nghttpx.1 index 255b2bdf..5f049f42 100644 --- a/doc/nghttpx.1 +++ b/doc/nghttpx.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "NGHTTPX" "1" "Sep 02, 2018" "1.33.0" "nghttp2" +.TH "NGHTTPX" "1" "Sep 15, 2018" "1.34.0-DEV" "nghttp2" .SH NAME nghttpx \- HTTP/2 proxy . @@ -601,19 +601,43 @@ Default: \fB2m\fP .B \-\-ciphers= Set allowed cipher list for frontend connection. The format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.2 or earlier. +Use \fI\%\-\-tls13\-ciphers\fP for TLSv1.3. .sp Default: \fBECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-SHA384:ECDHE\-RSA\-AES256\-SHA384:ECDHE\-ECDSA\-AES128\-SHA256:ECDHE\-RSA\-AES128\-SHA256\fP .UNINDENT .INDENT 0.0 .TP +.B \-\-tls13\-ciphers= +Set allowed cipher list for frontend connection. The +format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.3. Use +\fI\%\-\-ciphers\fP for TLSv1.2 or earlier. +.sp +Default: \fBTLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256\fP +.UNINDENT +.INDENT 0.0 +.TP .B \-\-client\-ciphers= Set allowed cipher list for backend connection. The format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.2 or earlier. +Use \fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.3. .sp Default: \fBECDHE\-ECDSA\-AES256\-GCM\-SHA384:ECDHE\-RSA\-AES256\-GCM\-SHA384:ECDHE\-ECDSA\-CHACHA20\-POLY1305:ECDHE\-RSA\-CHACHA20\-POLY1305:ECDHE\-ECDSA\-AES128\-GCM\-SHA256:ECDHE\-RSA\-AES128\-GCM\-SHA256:ECDHE\-ECDSA\-AES256\-SHA384:ECDHE\-RSA\-AES256\-SHA384:ECDHE\-ECDSA\-AES128\-SHA256:ECDHE\-RSA\-AES128\-SHA256\fP .UNINDENT .INDENT 0.0 .TP +.B \-\-tls13\-client\-ciphers= +Set allowed cipher list for backend connection. The +format of the string is described in OpenSSL ciphers(1). +This option sets cipher suites for TLSv1.3. Use +\fI\%\-\-tls13\-client\-ciphers\fP for TLSv1.2 or earlier. +.sp +Default: \fBTLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256\fP +.UNINDENT +.INDENT 0.0 +.TP .B \-\-ecdh\-curves= Set supported curve list for frontend connections. is a colon separated list of curve NID or names @@ -735,7 +759,7 @@ than TLSv1.2 is specified, make sure that the compatible ciphers are included in \fI\%\-\-ciphers\fP option. The default cipher list only includes ciphers compatible with TLSv1.2 or above. The available versions are: -TLSv1.2, TLSv1.1, and TLSv1.0 +TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 .sp Default: \fBTLSv1.2\fP .UNINDENT @@ -748,9 +772,9 @@ done in case\-insensitive manner. The versions between enabled. If the protocol list advertised by client does not overlap this range, you will receive the error message "unknown protocol". The available versions are: -TLSv1.2, TLSv1.1, and TLSv1.0 +TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 .sp -Default: \fBTLSv1.2\fP +Default: \fBTLSv1.3\fP .UNINDENT .INDENT 0.0 .TP @@ -1003,6 +1027,24 @@ HTTP/2. To use those cipher suites with HTTP/2, consider to use \fI\%\-\-client\-no\-http2\-cipher\-black\-list\fP option. But be aware its implications. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-no\-postpone\-early\-data +By default, nghttpx postpones forwarding HTTP requests +sent in early data, including those sent in partially in +it, until TLS handshake finishes. If all backend server +recognizes "Early\-Data" header field, using this option +makes nghttpx not postpone forwarding request and get +full potential of 0\-RTT data. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-tls\-max\-early\-data= +Sets the maximum amount of 0\-RTT data that server +accepts. +.sp +Default: \fB16K\fP +.UNINDENT .SS HTTP/2 .INDENT 0.0 .TP @@ -1366,6 +1408,12 @@ is received, it is left unaltered. .UNINDENT .INDENT 0.0 .TP +.B \-\-no\-strip\-incoming\-early\-data +Don\(aqt strip Early\-Data header field from inbound client +requests. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-no\-location\-rewrite Don\(aqt rewrite location header field in default mode. When \fI\%\-\-http2\-proxy\fP is used, location header field will @@ -2105,6 +2153,15 @@ Return true if, and only if a SSL/TLS session is reused. .B attribute [R] alpn Return ALPN identifier negotiated in this connection. .UNINDENT +.INDENT 7.0 +.TP +.B attribute [R] tls_handshake_finished +Return true if SSL/TLS handshake has finished. If it returns +false in the request phase hook, the request is received in +TLSv1.3 early data (0\-RTT) and might be vulnerable to the +replay attack. nghttpx will send Early\-Data header field to +backend servers to indicate this. +.UNINDENT .UNINDENT .INDENT 0.0 .TP diff --git a/doc/nghttpx.1.rst b/doc/nghttpx.1.rst index dedf4c56..ba0e7f14 100644 --- a/doc/nghttpx.1.rst +++ b/doc/nghttpx.1.rst @@ -559,16 +559,38 @@ SSL/TLS Set allowed cipher list for frontend connection. The format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.2 or earlier. + Use :option:`--tls13-ciphers` for TLSv1.3. Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256`` +.. option:: --tls13-ciphers= + + Set allowed cipher list for frontend connection. The + format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.3. Use + :option:`--ciphers` for TLSv1.2 or earlier. + + Default: ``TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256`` + .. option:: --client-ciphers= Set allowed cipher list for backend connection. The format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.2 or earlier. + Use :option:`--tls13-client-ciphers` for TLSv1.3. Default: ``ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256`` +.. option:: --tls13-client-ciphers= + + Set allowed cipher list for backend connection. The + format of the string is described in OpenSSL ciphers(1). + This option sets cipher suites for TLSv1.3. Use + :option:`--tls13-client-ciphers` for TLSv1.2 or earlier. + + Default: ``TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256`` + .. option:: --ecdh-curves= Set supported curve list for frontend connections. @@ -679,7 +701,7 @@ SSL/TLS ciphers are included in :option:`--ciphers` option. The default cipher list only includes ciphers compatible with TLSv1.2 or above. The available versions are: - TLSv1.2, TLSv1.1, and TLSv1.0 + TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 Default: ``TLSv1.2`` @@ -691,9 +713,9 @@ SSL/TLS enabled. If the protocol list advertised by client does not overlap this range, you will receive the error message "unknown protocol". The available versions are: - TLSv1.2, TLSv1.1, and TLSv1.0 + TLSv1.3, TLSv1.2, TLSv1.1, and TLSv1.0 - Default: ``TLSv1.2`` + Default: ``TLSv1.3`` .. option:: --tls-ticket-key-file= @@ -921,6 +943,22 @@ SSL/TLS consider to use :option:`--client-no-http2-cipher-black-list` option. But be aware its implications. +.. option:: --tls-no-postpone-early-data + + By default, nghttpx postpones forwarding HTTP requests + sent in early data, including those sent in partially in + it, until TLS handshake finishes. If all backend server + recognizes "Early-Data" header field, using this option + makes nghttpx not postpone forwarding request and get + full potential of 0-RTT data. + +.. option:: --tls-max-early-data= + + Sets the maximum amount of 0-RTT data that server + accepts. + + Default: ``16K`` + HTTP/2 ~~~~~~ @@ -1237,6 +1275,11 @@ HTTP Don't append to Via header field. If Via header field is received, it is left unaltered. +.. option:: --no-strip-incoming-early-data + + Don't strip Early-Data header field from inbound client + requests. + .. option:: --no-location-rewrite Don't rewrite location header field in default mode. @@ -1927,6 +1970,14 @@ respectively. Return ALPN identifier negotiated in this connection. + .. rb:attr_reader:: tls_handshake_finished + + Return true if SSL/TLS handshake has finished. If it returns + false in the request phase hook, the request is received in + TLSv1.3 early data (0-RTT) and might be vulnerable to the + replay attack. nghttpx will send Early-Data header field to + backend servers to indicate this. + .. rb:class:: Request Object to represent request from client. The modification to