diff options
Diffstat (limited to 'doc/manual/tls.rst')
| -rw-r--r-- | doc/manual/tls.rst | 44 |
1 files changed, 30 insertions, 14 deletions
diff --git a/doc/manual/tls.rst b/doc/manual/tls.rst index 7210fc092..6c1ca42f2 100644 --- a/doc/manual/tls.rst +++ b/doc/manual/tls.rst @@ -38,17 +38,21 @@ information about the connection. .. cpp:function:: void tls_emit_data(const byte data[], size_t data_len) - The TLS stack requests that all bytes of *data* be queued up to send to the + Mandatory. The TLS stack requests that all bytes of *data* be queued up to send to the counterparty. After this function returns, the buffer containing *data* will be overwritten, so a copy of the input must be made if the callback cannot send the data immediately. - The write can be deferred but for TLS all writes must occur *in order*. - For DTLS this is not strictly required, but is still recommended. + As an example you could ``send`` to perform a blocking write on a socket, + or append the data to a queue managed by your application, and initiate + an asyncronous write. + + For TLS all writes must occur *in the order requested*. + For DTLS this ordering is not strictly required, but is still recommended. .. cpp:function:: void tls_record_received(uint64_t rec_no, const byte data[], size_t data_len) - Called once for each application_data record which is received, with the + Mandatory. Called once for each application_data record which is received, with the matching (TLS level) record sequence number. Currently empty records are ignored and do not instigate a callback, @@ -57,15 +61,21 @@ information about the connection. As with ``tls_emit_data``, the array will be overwritten sometime after the callback returns, so a copy should be made if needed. + For TLS the record number will always increase. + + For DTLS, it is possible to receive records with the `rec_no` field + field out of order or repeated. It is even possible (from a malicious or + faulty peer) to receive multiple copies of a single record with differing plaintexts. + .. cpp:function:: void tls_alert(Alert alert) - Called when an alert is received from the peer. Note that alerts + Mandatory. Called when an alert is received from the peer. Note that alerts received before the handshake is complete are not authenticated and could have been inserted by a MITM attacker. .. cpp:function:: bool tls_session_established(const TLS::Session& session) - Called whenever a negotiation completes. This can happen more + Mandatory. Called whenever a negotiation completes. This can happen more than once on any connection, if renegotiation occurs. The *session* parameter provides information about the session which was just established. @@ -76,6 +86,13 @@ information about the connection. exception which will send a close message to the counterparty and reset the connection state. + .. cpp:function:: std::string tls_server_choose_app_protocol(const std::vector<std::string>& client_protos) + + Optional. Called by the server when a client includes a list of protocols in the ALPN extension. + The server then choose which protocol to use, or "" to disable sending any ALPN response. + The default implementation returns the empty string all of the time, effectively disabling + ALPN responses. + .. cpp:function:: void tls_inspect_handshake_msg(const Handshake_Message&) This callback is optional, and can be used to inspect all handshake messages @@ -90,7 +107,7 @@ Versions from 1.11.0 to 1.11.30 did not have ``TLS::Callbacks` and instead used independent std::functions to pass the various callback functions. This interface is currently still included but is deprecated and will be removed in a future release. For the documentation for this interface, please check -the docs in 1.11.30. This version of the manual only documents the new interface +the docs for 1.11.30. This version of the manual only documents the new interface added in 1.11.31. TLS Channels @@ -278,7 +295,6 @@ TLS Servers Credentials_Manager& creds, \ const Policy& policy, \ RandomNumberGenerator& rng, \ - next_protocol_fn next_proto = next_protocol_fn(), \ bool is_datagram = false, \ size_t reserved_io_buffer_size = 16*1024 \ ) @@ -287,12 +303,12 @@ The first 5 arguments as well as the final argument *reserved_io_buffer_size*, are treated similiarly to the :ref:`client <tls_client>`. -The (optional) argument, *next_proto*, is a function called if the -client sent the ALPN extension to negotiate an application -protocol. In that case, the function should choose a protocol to use -and return it. Alternately it can throw an exception to abort the -exchange; the ALPN specification says that if this occurs the alert -should be of type `NO_APPLICATION_PROTOCOL`. +If a client sends the ALPN extension, the ``callbacks`` function +``tls_server_choose_app_protocol`` will be called and the result +sent back to the client. If the empty string is returned, the server +will not send an ALPN response. The function can also throw an exception +to abort the handshake entirely, the ALPN specification says that if this +occurs the alert should be of type `NO_APPLICATION_PROTOCOL`. The optional argument *is_datagram* specifies if this is a TLS or DTLS server; unlike clients, which know what type of protocol (TLS vs DTLS) |