doc: added section on reducing round-trips

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

6 files changed, 66 insertions, 2 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 70b0dce99e..edab5888ee 100644
--- 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 8cc81ac5a4..2c8d16916e 100644
--- 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 87c2f87475..0a87cfbb65 100644
--- 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 d787d0f44c..37b00514da 100644
--- 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 1165e8413c..3de3f6face 100644
--- 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 0d633594c0..bb1f464558 100644
--- 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 \