From 72650a09530d5e62a6e6aa5aae4e74955ff1b384 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Tue, 26 Jul 2016 13:59:04 +0200 Subject: doc: added section on reducing round-trips That discusses TCP fast open with gnutls_transport_set_fastopen(), and false start. --- doc/Makefile.am | 13 ++++++++++++- doc/cha-bib.texi | 5 +++++ doc/cha-functions.texi | 8 ++++++++ doc/cha-gtls-app.texi | 26 ++++++++++++++++++++++++++ doc/doc.mk | 2 +- doc/manpages/Makefile.am | 14 ++++++++++++++ 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 \ -- cgit v1.2.1