Update manual pages

2018-09-15 11:15:04 +09:00 · 2018-09-15 11:15:04 +09:00 · 9f415979fb
parent 4bfc0cd196
commit 9f415979fb
5 changed files with 118 additions and 10 deletions
--- 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
 .
--- 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
 .
--- 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
 .
--- 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=<SUITE>
 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=<SUITE>
+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=<SUITE>
 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=<SUITE>
+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=<LIST>
 Set  supported  curve  list  for  frontend  connections.
 <LIST> 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=<SIZE>
+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
--- 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=<SUITE>
+
+    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=<SUITE>

    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=<SUITE>
+
+    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=<LIST>

    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=<PATH>

@ -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=<SIZE>
+
+    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