From 80d96590c580d4c21ec9af658aa575ff50db234a Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Tue, 28 Jul 2015 23:43:32 +0900 Subject: [PATCH] nghttpx: Update doc --- doc/nghttpx.h2r | 56 +++++++++++++++++++++++++++++++++++++++++++++++++ src/shrpx.cc | 34 +++++++++++++++--------------- 2 files changed, 73 insertions(+), 17 deletions(-) diff --git a/doc/nghttpx.h2r b/doc/nghttpx.h2r index 61519f36..db96a134 100644 --- a/doc/nghttpx.h2r +++ b/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 -------- diff --git a/src/shrpx.cc b/src/shrpx.cc index f200f672..9e113e3a 100644 --- a/src/shrpx.cc +++ b/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= - 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 to fetch-ocsp-response script file. It should be - absolute path. - Default: )" << get_config()->fetch_ocsp_response_file.get() << R"( - --ocsp-update-interval= - 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=, - Specify address of memcached server to store session - cache. This enables shared session cache between - multiple nghttpx instances. --tls-ticket-key-memcached=, 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= + 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 to fetch-ocsp-response script file. It should be + absolute path. + Default: )" << get_config()->fetch_ocsp_response_file.get() << R"( + --ocsp-update-interval= + 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=, + 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=