doc: added section on reducing round-trips

That discusses TCP fast open with gnutls_transport_set_fastopen(), and false start.

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 70b0dce99eb84136fec04f44b269d403ef2f81f1..edab5888ee38a00f5e86302fca3fa500de082923 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -200,7 +200,7 @@ MAINTAINERCLEANFILES =
 
 # Generated texinfos.
 
-API_FILES=gnutls-api.texi x509-api.texi pgp-api.texi pkcs12-api.texi \
+API_FILES=gnutls-api.texi socket-api.texi x509-api.texi pgp-api.texi pkcs12-api.texi \
        tpm-api.texi pkcs11-api.texi abstract-api.texi compat-api.texi \
        dtls-api.texi crypto-api.texi ocsp-api.texi tpm-api.texi dane-api.texi \
        pkcs7-api.texi
@@ -225,6 +225,17 @@ gnutls-api.texi: $(top_srcdir)/lib/includes/gnutls/gnutls.h.in
        done
        mv -f $@-tmp $@
 
+socket-api.texi: $(top_srcdir)/lib/includes/gnutls/socket.h
+       echo "" > $@-tmp
+       for i in `$(top_srcdir)/doc/scripts/getfuncs.pl < $< |sort|uniq`; do \
+               echo $(ECHO_N) "Creating documentation for $$i... " && \
+               $(srcdir)/scripts/gdoc -texinfo \
+                       -function $$i \
+                       $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \
+               echo "ok"; \
+       done
+       mv -f $@-tmp $@
+
 dane-api.texi: $(top_srcdir)/libdane/includes/gnutls/dane.h
        echo "" > $@-tmp
        for i in `$(top_srcdir)/doc/scripts/getfuncs.pl < $< |sort|uniq`; do \

diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi
index 8cc81ac5a44e1d62f5a4aa87c259dd4dac460dee..2c8d16916e35c2f2121a036d312efbcd856f1626 100644 (file)
--- a/doc/cha-bib.texi
+++ b/doc/cha-bib.texi
@@ -26,6 +26,11 @@ NIST Special Publication 800-57, "Recommendation for Key Management -
 Part 1: General (Revised)", March 2007, available from
 @url{http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf}.
 
+@item @anchor{RFC7413}[RFC7413]
+Y. Cheng and J. Chu and S. Radhakrishnan and A. Jain, "TCP Fast Open",
+December 2014, Available from
+@url{http://www.ietf.org/rfc/rfc7413.txt}.
+
 @item @anchor{RFC6125}[RFC6125]
 Peter Saint-Andre and Jeff Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)",
 March 2011, Available from

diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi
index 87c2f8747573ddf4f079377c67a5010b34eae588..0a87cfbb6525c49a0fe62dfd1527a07ba9c06697 100644 (file)
--- a/doc/cha-functions.texi
+++ b/doc/cha-functions.texi
@@ -13,6 +13,7 @@
 * PKCS 11 API::
 * TPM API::
 * Abstract key API::
+* Socket specific API::
 * DANE API::
 * Cryptographic API::
 * Compatibility API::
@@ -102,6 +103,13 @@ Their prototypes lie in @file{gnutls/abstract.h}.
 
 @include abstract-api.texi
 
+@node Socket specific API
+@section Socket specific API
+
+The prototypes for the following functions lie in
+@file{gnutls/socket.h}.
+@include socket-api.texi
+
 @node DANE API
 @section DANE API
 

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index d787d0f44c0ee37ab856e7e2a2ca6e7aef5714d7..37b00514da1a521515eb3316272644ebb01b7eb0 100644 (file)
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -792,6 +792,7 @@ remaining until the next retransmission, or better the time until
 
 @menu
 * Asynchronous operation::
+* Reducing round-trips::
 * DTLS sessions::
 @end menu
 
@@ -859,6 +860,31 @@ the function @funcref{gnutls_dtls_get_timeout}
 should be used to estimate when to call @funcref{gnutls_handshake} if
 no data have been received.
 
+@node Reducing round-trips
+@subsection Reducing round-trips
+
+The full TLS 1.2 handshake requires 2 round-trips to complete, and when
+combined with TCP's SYN and SYN-ACK negotiation it extends to 3 full
+round-trips. While, the abbreviated (resumed) TLS handshake drops that to 2.5
+round-trips, it still adds considerable latency, reducing its applicability
+to certain applications.
+
+In client side, it is possible to take advantage of the TCP fast open
+@xcite{RFC7413} mechanism on operating
+systems that support it. That can be done either by manually crafting the push and pull
+callbacks, or by utilizing @funcref{gnutls_transport_set_fastopen}. In that
+case the initial TCP handshake is eliminated, reducing the TLS handshake round-trip to 2.
+Note, that in that case any connection failures will be reported during the
+@funcref{gnutls_handshake} function call with error code
+@code{GNUTLS_E_PUSH_ERROR}.
+
+@showfuncdesc{gnutls_transport_set_fastopen}
+
+In non-resumed sessions it is possible to further reduce the round-trips to
+a single one by taking advantage of the @ref{False Start} TLS extension.
+This can be enabled by setting the @acronym{GNUTLS_ENABLE_FALSE_START} flag
+on @funcref{gnutls_init}.
+
 @node DTLS sessions
 @subsection DTLS sessions
 

diff --git a/doc/doc.mk b/doc/doc.mk
index 1165e8413cf58fc2f915253ce759979d40ccebea..3de3f6faceecb5b9a28837b4281867918e7792ec 100644 (file)
--- a/doc/doc.mk
+++ b/doc/doc.mk
@@ -26,7 +26,7 @@ HEADER_FILES = $(top_srcdir)/lib/includes/gnutls/gnutls.h.in \
        $(top_srcdir)/lib/includes/gnutls/ocsp.h $(top_srcdir)/lib/includes/gnutls/tpm.h \
        $(top_srcdir)/libdane/includes/gnutls/dane.h $(top_srcdir)/lib/includes/gnutls/x509-ext.h \
        $(top_srcdir)/lib/includes/gnutls/urls.h $(top_srcdir)/lib/includes/gnutls/system-keys.h \
-       $(top_srcdir)/lib/includes/gnutls/pkcs7.h
+       $(top_srcdir)/lib/includes/gnutls/pkcs7.h $(top_srcdir)/lib/includes/gnutls/socket.h
 
 C_SOURCE_FILES = $(top_srcdir)/lib/*/*.c $(top_srcdir)/lib/*.c $(top_srcdir)/libdane/*.c
 C_X509_SOURCE_FILES = $(top_srcdir)/lib/x509/*.c $(top_srcdir)/lib/*.c

diff --git a/doc/manpages/Makefile.am b/doc/manpages/Makefile.am
index 0d633594c084ac4f1f9c48525b925fe6bb04b469..bb1f4645584cf17b37cb78b5bc90fa34a06b15d2 100644 (file)
--- a/doc/manpages/Makefile.am
+++ b/doc/manpages/Makefile.am
@@ -1232,6 +1232,20 @@ stamp_mans: $(HEADER_FILES)
                echo $(ECHO_N) "."; \
        done
        @echo ""
+       @echo $(ECHO_N) "Creating man pages for socket.h..." && \
+       for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/socket.h`; do \
+               $(top_srcdir)/doc/scripts/gdoc -man \
+                       -module $(PACKAGE) -sourceversion $(VERSION) \
+                       -bugsto $(PACKAGE_BUGREPORT) \
+                       -pkg-site "http://www.gnutls.org" \
+                       -include "gnutls/socket.h" \
+                       -seeinfo $(PACKAGE) -verbatimcopying \
+                       -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \
+                       -function $$i \
+                       $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \
+               echo $(ECHO_N) "."; \
+       done
+       @echo ""
        @echo $(ECHO_N) "Creating man pages for dane.h..." && \
        for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/libdane/includes/gnutls/dane.h`; do \
                $(top_srcdir)/doc/scripts/gdoc -man \