summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorNikos Mavrogiannopoulos <nmav@redhat.com>2016-07-26 13:59:04 +0200
committerNikos Mavrogiannopoulos <nmav@redhat.com>2016-07-26 14:23:55 +0200
commit72650a09530d5e62a6e6aa5aae4e74955ff1b384 (patch)
tree53dfa274211d2dc65a05fbe881cd04392680bf94 /doc
parentf3568097ff5d81de36df395d6efb59d9d055b66d (diff)
downloadgnutls-72650a09530d5e62a6e6aa5aae4e74955ff1b384.tar.gz
doc: added section on reducing round-trips
That discusses TCP fast open with gnutls_transport_set_fastopen(), and false start.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am13
-rw-r--r--doc/cha-bib.texi5
-rw-r--r--doc/cha-functions.texi8
-rw-r--r--doc/cha-gtls-app.texi26
-rw-r--r--doc/doc.mk2
-rw-r--r--doc/manpages/Makefile.am14
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 \