Merge branch 'docs-fix' into 'master'

Updated documentation on Hello extensions.

Closes #437

See merge request gnutls/gnutls!644

2 files changed, 164 insertions, 167 deletions

diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi
index 020a023542..9d8fa6788b 100644
--- a/doc/cha-internals.texi
+++ b/doc/cha-internals.texi
@@ -11,7 +11,7 @@ happens inside the black box.
 * The TLS Protocol::
 * TLS Handshake Protocol::
 * TLS Authentication Methods::
-* TLS Extension Handling::
+* TLS Hello Extension Handling::
 * Cryptographic Backend::
 * Random Number Generators-internals::
 * FIPS140-2 mode::
@@ -40,10 +40,10 @@ transport layer functions are used. The main idea is shown in @ref{fig-gnutls-ha
 @caption{GnuTLS handshake state machine.}
 @end float
 
-Also the way the input is processed varies per ciphersuite. Several 
-implementations of the internal handlers are available and 
-@funcref{gnutls_handshake} only multiplexes the input to the appropriate 
-handler. For example a @acronym{PSK} ciphersuite has a different 
+Also the way the input is processed varies per ciphersuite. Several
+implementations of the internal handlers are available and
+@funcref{gnutls_handshake} only multiplexes the input to the appropriate
+handler. For example a @acronym{PSK} ciphersuite has a different
 implementation of the @code{process_client_key_exchange} than a
 certificate ciphersuite. We illustrate the idea in @ref{fig-gnutls-handshake-sequence}.
 
@@ -60,7 +60,7 @@ affect only the handshake protocol, a simple interface is used. An
 authentication method needs to implement the functions shown below.
 
 @verbatim
-typedef struct 
+typedef struct
 {
   const char *name;
   int (*gnutls_generate_server_certificate) (gnutls_session_t, gnutls_buffer_st*);
@@ -97,10 +97,10 @@ ciphersuites. After implementing these functions the structure holding
 its pointers has to be registered in @code{gnutls_@-algorithms.c} in the
 @code{_gnutls_@-kx_@-algorithms} structure.
 
-@node TLS Extension Handling
+@node TLS Hello Extension Handling
 @section TLS Extension Handling
-As with authentication methods, the TLS extensions handlers can be
-implemented using the interface shown below.
+As with authentication methods, adding TLS hello extensions can be done
+quite easily by implementing the interface shown below.
 
 @verbatim
 typedef int (*gnutls_ext_recv_func) (gnutls_session_t session,
@@ -109,35 +109,37 @@ typedef int (*gnutls_ext_send_func) (gnutls_session_t session,
                                      gnutls_buffer_st *extdata);
 @end verbatim
 
-Here there are two functions, one for receiving the extension data
-and one for sending. These functions have to check internally whether
-they operate in client or server side. 
+Here there are two main functions, one for parsing the received extension data
+and one for formatting the extension data that must be send. These functions
+have to check internally whether they operate within a client or a server session.
 
 A simple example of an extension handler can be seen in
-@code{ext/@-srp.c} in GnuTLS' source code. After implementing these functions, 
-together with the extension number they handle, they have to be registered 
-using @funcintref{_gnutls_ext_register} in
-@code{gnutls_extensions.c} typically within @funcintref{_gnutls_ext_init}.
-
-@subheading Adding a new TLS extension
-
-Adding support for a new TLS extension is done from time to time, and
-the process to do so is not difficult.  Here are the steps you need to
-follow if you wish to do this yourself.  For sake of discussion, let's
-consider adding support for the hypothetical TLS extension
-@code{foobar}. The following section is about adding an extension to GnuTLS,
-for custom application extensions you should check the exported functions
+@code{lib/ext/@-srp.c} in GnuTLS' source code. After implementing these functions,
+the extension has to be registered. Registering an extension can be done in two
+ways. You can create a GnuTLS internal extension and register it in
+@code{hello_ext.c} or write an external extension (not inside GnuTLS but
+inside an application using GnuTLS) and register it via the exported functions
+@funcref{gnutls_session_ext_register} or @funcref{gnutls_ext_register}.
+
+@subheading Adding a new TLS hello extension
+
+Adding support for a new TLS hello extension is done from time to time, and
+the process to do so is not difficult. Here are the steps you need to
+follow if you wish to do this yourself. For the sake of discussion, let's
+consider adding support for the hypothetical TLS extension @code{foobar}.
+The following section is about adding an hello extension to GnuTLS itself.
+For custom application extensions you should check the exported functions
 @funcref{gnutls_session_ext_register} or @funcref{gnutls_ext_register}.
 
 @subsubheading Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}.
 
 This step is useful when the extension code is large and it might be desirable
-to disable the extension under some circumstances. Otherwise it can be safely
-skipped.
+under some circumstances to be able to leave out the extension during compilation of GnuTLS.
+If you don't need this kind of feature this step can be safely skipped.
 
-Whether to chose enable or disable depends on whether you intend to make the extension be
-enabled by default.  Look at existing checks (i.e., SRP, authz) for
-how to model the code.  For example:
+Whether to choose enable or disable depends on whether you intend to make the extension be
+enabled by default. Look at existing checks (i.e., SRP, authz) for
+how to model the code. For example:
 
 @example
 AC_MSG_CHECKING([whether to disable foobar support])
@@ -155,135 +157,157 @@ fi
 AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no")
 @end example
 
-These lines should go in @code{m4/hooks.m4}.
+These lines should go in @code{lib/m4/hooks.m4}.
 
-@subsubheading Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}.
+@subsubheading Add an extension identifier to @code{extensions_t} in @code{gnutls_int.h}.
 
-A good name for the value would be GNUTLS_EXTENSION_FOOBAR.  Check
+A good name for the identifier would be GNUTLS_EXTENSION_FOOBAR. If the
+extension that you are implementing is an extension that is officially
+registered by IANA then it is recommended to use its official name such
+that the extension can be correctly identified by other developers. Check
 with @url{http://www.iana.org/assignments/tls-extensiontype-values}
-for allocated values.  For experiments, you could pick a number but
-remember that some consider it a bad idea to deploy such modified
-version since it will lead to interoperability problems in the future
-when the IANA allocates that number to someone else, or when the
-foobar protocol is allocated another number.
+for registered extensions.
 
-@subsubheading Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}.
+@subsubheading Register the extension in @code{lib/hello_ext.c}.
+
+In order for the extension to be executed you need to register it in the
+@code{static hello_ext_entry_st const *extfunc[]} list in @code{lib/hello_ext.c}.
 
 A typical entry would be:
 
 @example
-  int ret;
-
-#if ENABLE_FOOBAR
-  ret = _gnutls_ext_register (&foobar_ext);
-  if (ret != GNUTLS_E_SUCCESS)
-    return ret;
+#ifdef ENABLE_FOOBAR
+	[GNUTLS_EXTENSION_FOOBAR] = &ext_mod_foobar,
 #endif
 @end example
 
-Most likely you'll need to add an @code{#include "ext/@-foobar.h"}, that
-will contain something like
-like:
+Also for every extension you need to create an @code{hello_ext_entry_st}
+that describes the extension. This structure is placed in the designated
+c file for your extension and its name is used in the registration entry
+as depicted above.
+
+The structure of @code{hello_ext_entry_st} is as follows:
 @example
-  extension_entry_st foobar_ext = @{
+  const hello_ext_entry_st ext_mod_foobar = @{
     .name = "FOOBAR",
-    .type = GNUTLS_EXTENSION_FOOBAR,
+    .tls_id = 255,
+    .gid = GNUTLS_EXTENSION_FOOBAR,
     .parse_type = GNUTLS_EXT_TLS,
-    .recv_func = _foobar_recv_params,
-    .send_func = _foobar_send_params,
-    .pack_func = _foobar_pack,
-    .unpack_func = _foobar_unpack,
-    .deinit_func = NULL
-  @}
+    .validity = GNUTLS_EXT_FLAG_CLIENT_HELLO |
+	GNUTLS_EXT_FLAG_TLS12_SERVER_HELLO |
+	GNUTLS_EXT_FLAG_TLS13_SERVER_HELLO |
+	GNUTLS_EXT_FLAG_TLS,
+    .recv_func = _gnutls_foobar_recv_params,
+    .send_func = _gnutls_foobar_send_params,
+    .pack_func = _gnutls_foobar_pack,
+    .unpack_func = _gnutls_foobar_unpack,
+    .deinit_func = _gnutls_foobar_deinit,
+    .cannot_be_overriden = 1
+  @};
 @end example
 
-The GNUTLS_EXTENSION_FOOBAR is the integer value you added to
-@code{gnutls_int.h} earlier.  In this structure you specify the
-functions to read the extension from the hello message, the function
-to send the reply to, and two more functions to pack and unpack from
-stored session data (e.g. when resumming a session). The @code{deinit} function
-will be called to deinitialize the extension's private parameters, if any.
-
-Note that the conditional @code{ENABLE_FOOBAR} definition should only be 
+The GNUTLS_EXTENSION_FOOBAR is the identifier that you've added to
+@code{gnutls_int.h} earlier. The @code{.tls_id} should contain the number
+that IANA has assigned to this extension, or an unassigned number of your
+choice if this is an unregistered extension. In the rest of this structure
+you specify the functions to handle the extension data. The @code{receive} function
+will be called upon reception of the data and will be used to parse or
+interpret the extension data. The @code{send} function will be called prior to
+sending the extension data on the wire and will be used to format the data
+such that it can be send over the wire. The @code{pack} and @code{unpack}
+functions will be used to prepare the data for storage in case of session resumption
+(and vice versa). The @code{deinit} function will be called to deinitialize
+the extension's private parameters, if any.
+
+Look at @code{gnutls_ext_parse_type_t} and @code{gnutls_ext_flags_t} for a complete
+list of available flags.
+
+Note that the conditional @code{ENABLE_FOOBAR} definition should only be
 used if step 1 with the @code{configure} options has taken place.
 
-@subsubheading Add new files that implement the extension.
+@subsubheading Add new files that implement the hello extension.
 
-The functions you are responsible to add are those mentioned in the
-previous step.  They should be added in a file such as @code{ext/@-foobar.c} 
-and headers should be placed in @code{ext/@-foobar.h}.
+To keep things structured every extension should have its own files. The
+functions that you should (at least) add are those referenced in the struct
+from the previous step. Use descriptive file names such as @code{lib/ext/@-foobar.c}
+and for the corresponding header @code{lib/ext/@-foobar.h}.
 As a starter, you could add this:
 
 @example
 int
-_foobar_recv_params (gnutls_session_t session, const opaque * data,
+_gnutls_foobar_recv_params (gnutls_session_t session, const uint8_t * data,
                      size_t data_size)
 @{
   return 0;
 @}
 
 int
-_foobar_send_params (gnutls_session_t session, gnutls_buffer_st* data)
+_gnutls_foobar_send_params (gnutls_session_t session, gnutls_buffer_st* data)
 @{
   return 0;
 @}
 
 int
-_foobar_pack (extension_priv_data_t epriv, gnutls_buffer_st * ps)
+_gnutls_foobar_pack (extension_priv_data_t epriv, gnutls_buffer_st * ps)
 @{
    /* Append the extension's internal state to buffer */
    return 0;
 @}
 
 int
-_foobar_unpack (gnutls_buffer_st * ps, extension_priv_data_t * epriv)
+_gnutls_foobar_unpack (gnutls_buffer_st * ps, extension_priv_data_t * epriv)
 @{
    /* Read the internal state from buffer */
    return 0;
 @}
 @end example
 
-The @funcintref{_foobar_recv_params} function is responsible for
+The @funcintref{_gnutls_foobar_recv_params} function is responsible for
 parsing incoming extension data (both in the client and server).
 
-The @funcintref{_foobar_send_params} function is responsible for
-sending extension data (both in the client and server). It should
-append data to provided buffer and return a positive (or zero) number on
-success or a negative error code. Previous to 3.6.0 versions of GnuTLS required
-that function to return the number of bytes that were written. If zero
-is returned and no bytes are appended the extension will not be sent.
-If a zero byte extension is to be sent this function must return
-@code{GNUTLS_E_INT_RET_0}.
+The @funcintref{_gnutls_foobar_send_params} function is responsible for
+formatting extension data such that it can be send over the wire (both in
+the client and server). It should append data to provided buffer and
+return a positive (or zero) number on success or a negative error code.
+Previous to 3.6.0 versions of GnuTLS required that function to return the
+number of bytes that were written. If zero is returned and no bytes are
+appended the extension will not be sent. If a zero byte extension is to
+be sent this function must return @code{GNUTLS_E_INT_RET_0}.
 
 If you receive length fields that don't match, return
 @code{GNUTLS_E_@-UNEXPECTED_@-PACKET_@-LENGTH}.  If you receive invalid
 data, return @code{GNUTLS_E_@-RECEIVED_@-ILLEGAL_@-PARAMETER}.  You can use
-other error codes from the list in @ref{Error codes}.  Return 0 on success.
+other error codes from the list in @ref{Error codes}. Return 0 on success.
 
 An extension typically stores private information in the @code{session}
-data for later usage. That can be done using the functions 
-@funcintref{_gnutls_ext_set_session_data} and
-@funcintref{_gnutls_ext_get_session_data}. You can check simple examples
-at @code{ext/@-max_@-record.c} and @code{ext/@-server_@-name.c} extensions.
-That private information can be saved and restored across session 
+data for later usage. That can be done using the functions
+@funcintref{_gnutls_hello_ext_set_datum} and
+@funcintref{_gnutls_hello_ext_get_datum}. You can check simple examples
+at @code{lib/ext/@-max_@-record.c} and @code{lib/ext/@-server_@-name.c} extensions.
+That private information can be saved and restored across session
 resumption if the following functions are set:
 
-The @funcintref{_foobar_pack} function is responsible for packing
+The @funcintref{_gnutls_foobar_pack} function is responsible for packing
 internal extension data to save them in the session resumption storage.
 
-The @funcintref{_foobar_unpack} function is responsible for
+The @funcintref{_gnutls_foobar_unpack} function is responsible for
 restoring session data from the session resumption storage.
 
-Recall that both the client and server, send and receive
-parameters, and your code most likely will need to do different things
-depending on which mode it is in.  It may be useful to make this
-distinction explicit in the code.  Thus, for example, a better
+When the internal data is stored using the @funcintref{_gnutls_hello_ext_set_datum},
+then you can rely on the default pack and unpack functions:
+@funcintref{_gnutls_hello_ext_default_pack} and
+@funcintref{_gnutls_hello_ext_default_unpack}.
+
+Recall that both for the client and server, the send and receive
+functions most likely will need to do different things
+depending on which mode they are in. It may be useful to make this
+distinction explicit in the code. Thus, for example, a better
 template than above would be:
 
 @example
 int
 _gnutls_foobar_recv_params (gnutls_session_t session,
-                            const opaque * data,
+                            const uint8_t * data,
                             size_t data_size)
 @{
   if (session->security_parameters.entity == GNUTLS_CLIENT)
@@ -305,7 +329,8 @@ _gnutls_foobar_send_params (gnutls_session_t session,
 
 The functions used would be declared as @code{static} functions, of
 the appropriate prototype, in the same file.
-When adding the files, you'll need to add them to @code{ext/@-Makefile.am}
+
+When adding the new extension files, you'll need to add them to @code{lib/ext/@-Makefile.am}
 as well, for example:
 
 @example
@@ -314,54 +339,26 @@ libgnutls_ext_la_SOURCES += ext/foobar.c ext/foobar.h
 endif
 @end example
 
-@subsubheading Add API functions to enable/disable the extension.
+@subsubheading Add API functions to use the extension.
 
 It might be desirable to allow users of the extension to
-request use of the extension, or set extension specific data.  
+request the use of the extension, or set extension specific data.
 This can be implemented by adding extension specific function calls
 that can be added to @code{includes/@-gnutls/@-gnutls.h},
 as long as the LGPLv2.1+ applies.
-The implementation of the function should lie in the @code{ext/@-foobar.c} file.
+The implementation of these functions should lie in the @code{lib/ext/@-foobar.c} file.
 
-To make the API available in the shared library you need to add the
-symbol in @code{lib/@-libgnutls.map}, so that the symbol
-is exported properly.
+To make the API available in the shared library you need to add the added
+symbols in @code{lib/@-libgnutls.map}, so that the symbols are exported properly.
 
 When writing GTK-DOC style documentation for your new APIs, don't
 forget to add @code{Since:} tags to indicate the GnuTLS version the
 API was introduced in.
 
-@subsubheading Heartbeat extension.
-
-One such extension is HeartBeat protocol (RFC6520:
-@url{https://tools.ietf.org/html/rfc6520}) implementation. To enable
-it use option --heartbeat with example client and server supplied with
-gnutls:
-
-@example
-./doc/credentials/gnutls-http-serv --priority "NORMAL:-CIPHER-ALL:+NULL" -d 100 \
-    --heartbeat --echo
-./src/gnutls-cli --priority "NORMAL:-CIPHER-ALL:+NULL" -d 100 localhost -p 5556 \
-    --insecure --heartbeat
-@end example
-
-After that pasting
-@example
-**HEARTBEAT**
-@end example
-command into gnutls-cli will trigger corresponding command on the server and it will send HeartBeat Request with random length to client.
-
-Another way is to run capabilities check with:
-
-@example
-./doc/credentials/gnutls-http-serv -d 100 --heartbeat
-./src/gnutls-cli-debug localhost -p 5556
-@end example
-
 @subheading Adding a new Supplemental Data Handshake Message
 
 TLS handshake extensions allow to send so called supplemental data
-handshake messages @xcite{RFC4680}. This short section explains how to 
+handshake messages @xcite{RFC4680}. This short section explains how to
 implement a supplemental data handshake message for a given TLS extension.
 
 First of all, modify your extension @code{foobar} in the way, to instruct
@@ -387,7 +384,7 @@ _gnutls_foobar_send_params (gnutls_session_t session, gnutls_buffer_st *extdata)
 @end example
 
 Furthermore you'll need two new functions @funcintref{_foobar_supp_recv_params}
-and @funcintref{_foobar_supp_send_params}, which must conform to the following 
+and @funcintref{_foobar_supp_send_params}, which must conform to the following
 prototypes.
 
 @example
@@ -402,7 +399,7 @@ The following example code shows how to send a
 ``Hello World'' string in the supplemental data handshake message.
 
 @example
-int 
+int
 _foobar_supp_recv_params(gnutls_session_t session, const opaque *data, size_t _data_size)
 @{
    uint8_t len = _data_size;
@@ -420,7 +417,7 @@ _foobar_supp_recv_params(gnutls_session_t session, const opaque *data, size_t _d
    return len;
 @}
 
-int 
+int
 _foobar_supp_send_params(gnutls_session_t session, gnutls_buffer_t buf)
 @{
    unsigned char *msg = "hello world";
@@ -441,8 +438,8 @@ or @funcref{gnutls_supplemental_register} at some point in your program.
 
 Today most new processors, either for embedded or desktop systems
 include either instructions  intended to speed up cryptographic operations,
-or a co-processor with cryptographic capabilities. Taking advantage of 
-those is a challenging task for every cryptographic  application or 
+or a co-processor with cryptographic capabilities. Taking advantage of
+those is a challenging task for every cryptographic  application or
 library. GnuTLS handles the cryptographic provider in a modular
 way, following a layered approach to access
 cryptographic operations as in @ref{fig-crypto-layers}.
@@ -452,7 +449,7 @@ cryptographic operations as in @ref{fig-crypto-layers}.
 @caption{GnuTLS cryptographic back-end design.}
 @end float
 
-The TLS layer uses a cryptographic provider layer, that will in turn either 
+The TLS layer uses a cryptographic provider layer, that will in turn either
 use the default crypto provider -- a software crypto library, or use an external
 crypto provider, if available in the local system. The reason of handling
 the external cryptographic provider in GnuTLS and not delegating it to
@@ -470,16 +467,16 @@ In the future other cryptographic libraries might be supported as well.
 
 @subheading External cryptography provider
 Systems that include a cryptographic co-processor, typically come with
-kernel drivers to utilize the operations from software. For this reason 
+kernel drivers to utilize the operations from software. For this reason
 GnuTLS provides a layer where each individual algorithm used can be replaced
 by another implementation, i.e., the one provided by the driver. The
-FreeBSD, OpenBSD and Linux kernels@footnote{Check @url{http://home.gna.org/cryptodev-linux/} 
-for the Linux kernel implementation of @code{/dev/crypto}.} include already 
-a number of hardware assisted implementations, and also provide an interface 
+FreeBSD, OpenBSD and Linux kernels@footnote{Check @url{http://home.gna.org/cryptodev-linux/}
+for the Linux kernel implementation of @code{/dev/crypto}.} include already
+a number of hardware assisted implementations, and also provide an interface
 to access them, called @code{/dev/crypto}.
 GnuTLS will take advantage of this interface if compiled with special
-options. That is because in most systems where hardware-assisted 
-cryptographic operations are not available, using this interface might 
+options. That is because in most systems where hardware-assisted
+cryptographic operations are not available, using this interface might
 actually harm performance.
 
 In systems that include cryptographic instructions with the CPU's
@@ -495,7 +492,7 @@ source code in @code{lib/accelerated/}.
 @subsubheading Overriding specific algorithms
 When an optimized implementation of a single algorithm is available,
 say a hardware assisted version of @acronym{AES-CBC} then the
-following functions, from @code{crypto.h}, can 
+following functions, from @code{crypto.h}, can
 be used to register those algorithms.
 
 @itemize
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index 79aa58bd7e..ca3fa92daa 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -8,11 +8,11 @@ by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force,
 is a large open international community of network designers,
 operators, vendors, and researchers concerned with the evolution of
 the Internet architecture and the smooth operation of the Internet.
-It is open to any interested individual.}, described in @xcite{RFC5246}.  
+It is open to any interested individual.}, described in @xcite{RFC5246}.
 The protocol provides
 confidentiality, and authentication layers over any reliable transport
 layer.  The description, above, refers to @acronym{TLS} 1.0 but applies
-to all other TLS versions as the differences between the protocols are not major.  
+to all other TLS versions as the differences between the protocols are not major.
 
 The @acronym{DTLS} protocol, or ``Datagram @acronym{TLS}'' @xcite{RFC4347} is a
 protocol with identical goals as @acronym{TLS}, but can operate
@@ -48,7 +48,7 @@ conditions.  @xref{The Alert Protocol}, for more information.  The
 alert protocol is above the record protocol.
 
 The handshake protocol is responsible for the security parameters'
-negotiation, the initial key exchange and authentication.  
+negotiation, the initial key exchange and authentication.
 @xref{The Handshake Protocol}, for more information about the handshake
 protocol.  The protocol layering in TLS is shown in @ref{fig-tls-layers}.
 
@@ -67,7 +67,7 @@ above any transport layer, as long as it is a reliable one.  @acronym{DTLS}
 can be used over reliable and unreliable transport layers.
 @acronym{GnuTLS} supports TCP and UDP layers transparently using
 the Berkeley sockets API. However, any transport layer can be used
-by providing callbacks for @acronym{GnuTLS} to access the transport layer 
+by providing callbacks for @acronym{GnuTLS} to access the transport layer
 (for details see @ref{Setting up the transport layer}).
 
 @node The TLS record protocol
@@ -81,11 +81,11 @@ the handshake process is finished, when there is need to receive
 or send data. In @acronym{DTLS} however, due to re-transmission
 timers used in the handshake out-of-order handshake data might
 be received for some time (maximum 60 seconds) after the handshake
-process is finished. 
+process is finished.
 
 The functions to access the record protocol are limited to send
-and receive functions, which might, given 
-the importance of this protocol in @acronym{TLS}, seem awkward.  This is because 
+and receive functions, which might, given
+the importance of this protocol in @acronym{TLS}, seem awkward.  This is because
 the record protocol's parameters are all set by the handshake protocol.
 The record protocol initially starts with NULL parameters, which means
 no encryption, and no MAC is used. Encryption and authentication begin
@@ -102,10 +102,10 @@ just after the handshake protocol has finished.
 @cindex symmetric encryption algorithms
 
 Confidentiality in the record layer is achieved by using symmetric
-ciphers like @code{AES} or @code{CHACHA20}.  Ciphers are encryption algorithms 
+ciphers like @code{AES} or @code{CHACHA20}.  Ciphers are encryption algorithms
 that use a single, secret, key to encrypt and decrypt data. Early
 versions of TLS separated between block and stream ciphers and had
-message authentication plugged in to them by the protocol, though later 
+message authentication plugged in to them by the protocol, though later
 versions switched to using authenticated-encryption (AEAD) ciphers. The AEAD
 ciphers are defined to combine encryption and authentication, and as such
 they are not only more efficient, as the primitives used are designed to
@@ -198,11 +198,11 @@ implicitly disabled.
 @multitable @columnfractions .20 .70
 @headitem Algorithm @tab Description
 @item MAC-MD5 @tab
-This is an HMAC based on MD5 a cryptographic hash algorithm designed 
+This is an HMAC based on MD5 a cryptographic hash algorithm designed
 by Ron Rivest. Outputs 128 bits of data.
 
 @item MAC-SHA1 @tab
-An HMAC based on the SHA1 cryptographic hash algorithm 
+An HMAC based on the SHA1 cryptographic hash algorithm
 designed by NSA. Outputs 160 bits of data.
 
 @item MAC-SHA256 @tab
@@ -270,7 +270,7 @@ session ID. All supported alert messages are summarized in the table below.
 The alert messages are protected by the record protocol, thus the
 information that is included does not leak. You must take extreme care
 for the alert information not to leak to a possible attacker, via
-public log files etc. 
+public log files etc.
 
 @include alerts.texi
 
@@ -283,7 +283,7 @@ The handshake protocol is responsible for the ciphersuite negotiation,
 the initial key exchange, and the authentication of the two peers.
 This is fully controlled by the application layer, thus your program
 has to set up the required parameters. The main handshake function
-is @funcref{gnutls_handshake}. In the next paragraphs we elaborate on 
+is @funcref{gnutls_handshake}. In the next paragraphs we elaborate on
 the handshake protocol, i.e., the ciphersuite negotiation.
 
 
@@ -332,7 +332,7 @@ All the supported ciphersuites are listed in @ref{ciphersuites}.
 @subsection Authentication
 
 The key exchange algorithms of the @acronym{TLS} protocol offer
-authentication, which is a prerequisite for a secure connection. 
+authentication, which is a prerequisite for a secure connection.
 The available authentication methods in @acronym{GnuTLS}, under
 TLS 1.3 or earlier versions, follow.
 
@@ -360,7 +360,7 @@ are also available.
 In the case of ciphersuites that use certificate authentication, the
 authentication of the client is optional in @acronym{TLS}.  A server
 may request a certificate from the client using the
-@funcref{gnutls_certificate_server_set_request} function. We elaborate 
+@funcref{gnutls_certificate_server_set_request} function. We elaborate
 in @ref{Certificate credentials}.
 
 @node Resuming Sessions
@@ -370,7 +370,7 @@ in @ref{Certificate credentials}.
 @cindex session resumption
 
 The TLS handshake process performs expensive calculations
-and a busy server might easily be put under load. To 
+and a busy server might easily be put under load. To
 reduce the load, session resumption may be used. This
 is a feature of the @acronym{TLS} protocol which allows a
 client to connect to a server after a successful handshake, without
@@ -378,8 +378,8 @@ the expensive calculations.  This is achieved by re-using the previously
 established keys, meaning the server needs to store the state of established
 connections (unless session tickets are used -- @ref{Session tickets}).
 
-Session resumption is an integral part of @acronym{GnuTLS}, and 
-@ref{Session resumption}, @ref{ex-resume-client} illustrate typical 
+Session resumption is an integral part of @acronym{GnuTLS}, and
+@ref{Session resumption}, @ref{ex-resume-client} illustrate typical
 uses of it.
 
 @node TLS Extensions
@@ -465,10 +465,10 @@ This is a TLS extension that allows to ping and receive confirmation from the pe
 and is described in @xcite{RFC6520}. The extension is disabled by default and
 @funcref{gnutls_heartbeat_enable} can be used to enable it. A policy
 may be negotiated to only allow sending heartbeat messages or sending and receiving.
-The current session policy can be checked with @funcref{gnutls_heartbeat_allowed}. 
+The current session policy can be checked with @funcref{gnutls_heartbeat_allowed}.
 The requests coming from the peer result to @code{GNUTLS_@-E_@-HEARTBEAT_@-PING_@-RECEIVED}
 being returned from the receive function. Ping requests to peer can be send via
-@funcref{gnutls_heartbeat_ping}. 
+@funcref{gnutls_heartbeat_ping}.
 
 @showfuncB{gnutls_heartbeat_allowed,gnutls_heartbeat_enable}
 
@@ -501,7 +501,7 @@ to access certain parts of a web site.  The
 attack works by having the attacker simulate a client and connect to a
 server, with server-only authentication, and send some data intended
 to cause harm.  The server will then require renegotiation from him
-in order to perform the request. 
+in order to perform the request.
 When the proper client attempts to contact the server,
 the attacker hijacks that connection and forwards traffic to
 the initial server that requested renegotiation.  The
@@ -539,7 +539,7 @@ Note that it is easy to configure clients to always require the safe
 renegotiation extension from servers.
 
 To modify the default behavior, we have introduced some new priority
-strings (see @ref{Priority Strings}).  
+strings (see @ref{Priority Strings}).
 The @code{%UNSAFE_RENEGOTIATION} priority string permits
 (re-)handshakes even when the safe renegotiation extension was not
 negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will
@@ -657,7 +657,7 @@ but only when the negotiated parameters exceed @code{GNUTLS_SEC_PARAM_HIGH}
 @cindex ALPN
 @cindex Application Layer Protocol Negotiation
 
-The TLS protocol was extended in @code{RFC7301} 
+The TLS protocol was extended in @code{RFC7301}
 to provide the application layer a method of
 negotiating the application protocol version. This allows for negotiation
 of the application protocol during the TLS handshake, thus reducing
@@ -678,8 +678,8 @@ to register them.
 It is possible to transfer supplemental data during the TLS handshake, following
 @xcite{RFC4680}. This is for "custom" protocol modifications for applications which
 may want to transfer additional data (e.g. additional authentication messages). Such
-an exchange requires a custom extension to be registered. 
-The provided API for this functionality is low-level and described in @ref{TLS Extension Handling}.
+an exchange requires a custom extension to be registered.
+The provided API for this functionality is low-level and described in @ref{TLS Hello Extension Handling}.
 
 @include sec-tls-app.texi