diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api_ref/tls.rst | 78 |
1 files changed, 59 insertions, 19 deletions
diff --git a/doc/api_ref/tls.rst b/doc/api_ref/tls.rst index 1da40c58f..1980e094b 100644 --- a/doc/api_ref/tls.rst +++ b/doc/api_ref/tls.rst @@ -666,6 +666,12 @@ Every time your handshake callback is called, a new session has been established, and a ``TLS::Session`` is included that provides information about that session: +.. note:: + + The serialization format of Session is not considered stable and is allowed + to change even within a single major release cycle. In the event of such a + change, old sessions will no longer be able to be resumed. + .. cpp:class:: TLS::Session .. cpp:function:: Protocol_Version version() const @@ -705,10 +711,8 @@ information about that session: Encrypts a session using a symmetric key *key* and returns a raw binary value that can later be passed to ``decrypt``. The key - may be of any length. - - Currently the implementation encrypts the session using AES-256 - in GCM mode with a random nonce. + may be of any length. The format is described in + :ref:`tls_session_encryption`. .. cpp:function:: static Session decrypt(const uint8_t ciphertext[], \ size_t length, \ @@ -988,18 +992,23 @@ policy settings from a file. Signals that we prefer ECC points to be compressed when transmitted to us. The other party may not support ECC point compression and therefore may still send points uncompressed. - + Note that the certificate used during authentication must also follow the other party's preference. Default: false + .. note:: + + Support for EC point compression is deprecated and will be removed in a + future major release. + .. cpp:function:: bool acceptable_protocol_version(Protocol_Version version) Return true if this version of the protocol is one that we are willing to negotiate. - Default: Accepts TLS v1.0 or higher and DTLS v1.2 or higher. + Default: Accepts TLS v1.2 and DTLS v1.2, and rejects all older versions. .. cpp:function:: bool server_uses_own_ciphersuite_preferences() const @@ -1007,19 +1016,6 @@ policy settings from a file. most out of the client's list. Otherwise, it will negotiate the first cipher in the client's ciphersuite list that it supports. - .. cpp:function:: bool negotiate_heartbeat_support() const - - If this function returns true, clients will offer the heartbeat - support extension, and servers will respond to clients offering - the extension. Otherwise, clients will not offer heartbeat - support and servers will ignore clients offering heartbeat - support. - - If this returns true, callers should expect to handle heartbeat - data in their ``alert_cb``. - - Default: false - .. cpp:function:: bool allow_client_initiated_renegotiation() const If this function returns true, a server will accept a @@ -1036,6 +1032,16 @@ policy settings from a file. Default: false + .. cpp:function:: bool abort_connection_on_undesired_renegotiation() const + + If a renegotiation attempt is being rejected due to the configuration of + :cpp:func:`TLS::Policy::allow_client_initiated_renegotiation` or + :cpp:func:`TLS::Policy::allow_server_initiated_renegotiation`, and + this function returns true then the connection is closed with a fatal + alert instead of the default warning alert. + + Default: false + .. cpp:function:: bool allow_insecure_renegotiation() const If this function returns true, we will allow renegotiation attempts @@ -1873,3 +1879,37 @@ Stream Code Example io_context.run(); } + +.. _tls_session_encryption: + +TLS Session Encryption +------------------------- + +A unified format is used for encrypting TLS sessions either for durable storage +(on client or server) or when creating TLS session tickets. This format is *not +stable* even across the same major version. + +The current session encryption scheme was introduced in 1.11.13. + +Session encryption accepts a key of any length, though for best security a key +of 256 bits should be used. This master key is used to key an instance of HMAC +using the SHA-256 hash. + +A random 96 bit nonce is created and included in the header. Then the nonce is +hashed using the keyed HMAC to produce a 256-bit GCM key. This key and nonce +pair are used to encrypt the session. + +The current design is unfortunate in several ways: + + * If the random 96-bit nonce ever repeats, then the same GCM key *and nonce* + are used to encrypt 2 different sessions, breaking the security of sessions + encrypted using that duplicated key/nonce. The GCM nonce should have been + independently created and included in the header, making a key collision + harmless. + + * There is no simple way to detect old or rotated keys, except by attempting + decryption. Instead a key identifier should be included in the header. + + * There is no indicator of the format used, which makes handling format + upgrades without breaking compatability awkward. + |