nghttpx: Update doc

doc/nghttpx.h2r

@@ -96,6 +96,62 @@ The script file is usually installed under
 ``$(prefix)/share/nghttp2/`` directory.  The actual path to script can
 be customized using :option:`--fetch-ocsp-response-file` option.
 
+TLS SESSION RESUMPTION
+----------------------
+
+nghttpx supports TLS session resumption through both session ID and
+session ticket.
+
+SESSION ID RESUMPTION
+~~~~~~~~~~~~~~~~~~~~~
+
+By default, session ID is shared by all worker threads.
+
+If :option:`--tls-session-cache-memcached` is given, nghttpx will
+insert serialized session data to memcached with session ID as a part
+of the key, with expiry time 12 hours.  Session timeout is set to 12
+hours.
+
+TLS SESSION TICKET RESUMPTION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, session ticket is shared by all worker threads.  The
+automatic key rotation is also enabled by default.  Every an hour, new
+encryption key is generated, and previous encryption key becomes
+decryption only key.  We set session timeout to 12 hours, and thus we
+keep at most 12 keys.
+
+If :option:`--tls-session-key-memcached` is given, encryption keys are
+retrieved from memcached.  nghttpx just reads keys from memcached; one
+has to deploy key generator program to update keys frequently (e.g.,
+every 1 hour).  The data format stored in memcached is the binary
+format described below::
+
+    +--------------+-------+----------------+
+    | VERSION (4)  |LEN (2)|KEY(48 or 80) ...
+    +--------------+-------+----------------+
+                   ^                        |
+		   |                        |
+		   +------------------------+
+                   (LEN, KEY) pair can be repeated
+
+All numbers in the above figure is bytes.  All integer fields are
+network byte order.
+
+First 4 bytes integer VERSION field, which must be 1.  The 2 bytes
+integer LEN field gives the length of following KEY field, which
+contains key.  If :option:`--tls-session-key-cipher`=aes-128-cbc is
+used, LEN must be 48.  If
+:option:`--tls-session-key-cipher`=aes-256-cbc is used, LEN must be
+80.  LEN and KEY pair can be repeated multiple times to store multiple
+keys.  The key appeared first is used as encryption key.  All the
+remaining keys are used as decryption only.
+
+If :option:`--tls-session-key-file` is given, encryption key is read
+from the given file.  In this case, nghttpx does not rotate key
+automatically.  To rotate key, one has to restart nghttpx (see
+SIGNALS).
+
 SEE ALSO
 --------
 

src/shrpx.cc

@@ -1479,23 +1479,6 @@ SSL/TLS:
               1 hour internally and they are valid for 12 hours.  This
               is  recommended if  ticket key  sharing between  nghttpx
               instances is not required.
-  --tls-ticket-cipher=<TICKET_CIPHER>
-              Specify cipher  to encrypt TLS session  ticket.  Specify
-              either   aes-128-cbc   or  aes-256-cbc.    By   default,
-              aes-128-cbc is used.
-  --fetch-ocsp-response-file=<PATH>
-              Path to  fetch-ocsp-response script file.  It  should be
-              absolute path.
-              Default: )" << get_config()->fetch_ocsp_response_file.get() << R"(
-  --ocsp-update-interval=<DURATION>
-              Set interval to update OCSP response cache.
-              Default: )"
-      << util::duration_str(get_config()->ocsp_update_interval) << R"(
-  --no-ocsp   Disable OCSP stapling.
-  --tls-session-cache-memcached=<HOST>,<PORT>
-              Specify  address of  memcached server  to store  session
-              cache.   This  enables   shared  session  cache  between
-              multiple nghttpx instances.
   --tls-ticket-key-memcached=<HOST>,<PORT>
               Specify  address of  memcached server  to store  session
               cache.   This  enables  shared TLS  ticket  key  between
@@ -1524,6 +1507,23 @@ SSL/TLS:
               disabling TLS ticket until next scheduled key retrieval.
               Default: )" << get_config()->tls_ticket_key_memcached_max_fail
       << R"(
+  --tls-ticket-cipher=<TICKET_CIPHER>
+              Specify cipher  to encrypt TLS session  ticket.  Specify
+              either   aes-128-cbc   or  aes-256-cbc.    By   default,
+              aes-128-cbc is used.
+  --fetch-ocsp-response-file=<PATH>
+              Path to  fetch-ocsp-response script file.  It  should be
+              absolute path.
+              Default: )" << get_config()->fetch_ocsp_response_file.get() << R"(
+  --ocsp-update-interval=<DURATION>
+              Set interval to update OCSP response cache.
+              Default: )"
+      << util::duration_str(get_config()->ocsp_update_interval) << R"(
+  --no-ocsp   Disable OCSP stapling.
+  --tls-session-cache-memcached=<HOST>,<PORT>
+              Specify  address of  memcached server  to store  session
+              cache.   This  enables   shared  session  cache  between
+              multiple nghttpx instances.
 
 HTTP/2 and SPDY:
   -c, --http2-max-concurrent-streams=<N>