diff options
Diffstat (limited to 'manual/html_node/Setting-up-the-transport-layer.html')
| -rw-r--r-- | manual/html_node/Setting-up-the-transport-layer.html | 416 |
1 files changed, 0 insertions, 416 deletions
diff --git a/manual/html_node/Setting-up-the-transport-layer.html b/manual/html_node/Setting-up-the-transport-layer.html deleted file mode 100644 index 9f9448e624..0000000000 --- a/manual/html_node/Setting-up-the-transport-layer.html +++ /dev/null @@ -1,416 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -<html> -<!-- This manual is last updated 4 March 2015 for version -3.5.4 of GnuTLS. - -Copyright (C) 2001-2015 Free Software Foundation, Inc.\\ -Copyright (C) 2001-2015 Nikos Mavrogiannopoulos - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A -copy of the license is included in the section entitled "GNU Free -Documentation License". --> -<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ --> -<head> -<title>GnuTLS 3.5.4: Setting up the transport layer</title> - -<meta name="description" content="GnuTLS 3.5.4: Setting up the transport layer"> -<meta name="keywords" content="GnuTLS 3.5.4: Setting up the transport layer"> -<meta name="resource-type" content="document"> -<meta name="distribution" content="global"> -<meta name="Generator" content="makeinfo"> -<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> -<link href="index.html#Top" rel="start" title="Top"> -<link href="Function-and-Data-Index.html#Function-and-Data-Index" rel="index" title="Function and Data Index"> -<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> -<link href="How-to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications" rel="up" title="How to use GnuTLS in applications"> -<link href="Asynchronous-operation.html#Asynchronous-operation" rel="next" title="Asynchronous operation"> -<link href="Anonymous-credentials.html#Anonymous-credentials" rel="prev" title="Anonymous credentials"> -<style type="text/css"> -<!-- -a.summary-letter {text-decoration: none} -blockquote.indentedblock {margin-right: 0em} -blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} -blockquote.smallquotation {font-size: smaller} -div.display {margin-left: 3.2em} -div.example {margin-left: 3.2em} -div.lisp {margin-left: 3.2em} -div.smalldisplay {margin-left: 3.2em} -div.smallexample {margin-left: 3.2em} -div.smalllisp {margin-left: 3.2em} -kbd {font-style: oblique} -pre.display {font-family: inherit} -pre.format {font-family: inherit} -pre.menu-comment {font-family: serif} -pre.menu-preformatted {font-family: serif} -pre.smalldisplay {font-family: inherit; font-size: smaller} -pre.smallexample {font-size: smaller} -pre.smallformat {font-family: inherit; font-size: smaller} -pre.smalllisp {font-size: smaller} -span.nolinebreak {white-space: nowrap} -span.roman {font-family: initial; font-weight: normal} -span.sansserif {font-family: sans-serif; font-weight: normal} -ul.no-bullet {list-style: none} -body { - margin: 2%; - padding: 0 5%; - background: #ffffff; -} -h1,h2,h3,h4,h5 { - font-weight: bold; - padding: 5px 5px 5px 5px; - background-color: #c2e0ff; - color: #336699; -} -h1 { - padding: 2em 2em 2em 5%; - color: white; - background: #336699; - text-align: center; - letter-spacing: 3px; -} -h2 { text-decoration: underline; } -pre { - margin: 0 5%; - padding: 0.5em; -} -pre.example,pre.verbatim { - padding-bottom: 1em; - - border: solid #c2e0ff; - background: #f0faff; - border-width: 1px 1px 1px 5px; - margin: 1em auto; - width: 90%; -} - -div.node { - margin: 0 -5% 0 -2%; - padding: 0.5em 0.5em; - margin-top: 0.5em; - margin-bottom: 0.5em; - font-weight: bold; -} -dd, li { - padding-top: 0.1em; - padding-bottom: 0.1em; -} -div.float { - - margin-bottom: 0.5em; - text-align: center; -} - -table { - text-align: left; - margin-left:auto; - margin-right:auto; - border-spacing: 7px; - width: 50%; -} - -th { - padding: 0; - color: #336699; - background-color: #c2e0ff; - border: solid #000000; - border-width: 0px; - margin: 1em auto; - text-align: center; - margin-left:auto; - margin-right:auto; -} - -td { - padding: 0; - border: solid #000000; - background-color: #f0faff; - border-width: 0px; - margin: 1em auto; - text-align: left; - margin-left:auto; - margin-right:auto; - padding-left: 1em; -} - -dl { - text-align: left; - margin-left:auto; - margin-right:auto; - width: 50%; - - padding-left: 1em; - border: solid #c2e0ff; - background: #f0faff; - border-width: 5px 1px 1px 1px; - margin: 1em auto; -} - ---> -</style> - - -</head> - -<body lang="en"> -<a name="Setting-up-the-transport-layer"></a> -<div class="header"> -<p> -Next: <a href="TLS-handshake.html#TLS-handshake" accesskey="n" rel="next">TLS handshake</a>, Previous: <a href="Associating-the-credentials.html#Associating-the-credentials" accesskey="p" rel="prev">Associating the credentials</a>, Up: <a href="How-to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Function-and-Data-Index.html#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p> -</div> -<hr> -<a name="Setting-up-the-transport-layer-1"></a> -<h3 class="section">6.5 Setting up the transport layer</h3> - -<p>The next step is to setup the underlying transport layer details. The -Berkeley sockets are implicitly used by GnuTLS, thus a -call to <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fint">gnutls_transport_set_int</a> would be sufficient to -specify the socket descriptor. -</p> -<dl compact="compact"> -<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fint">gnutls_transport_set_int</a> (gnutls_session_t <var>session</var>, int <var>fd</var>)</code></dt> -<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fint2">gnutls_transport_set_int2</a> (gnutls_session_t <var>session</var>, int <var>recv_fd</var>, int <var>send_fd</var>)</code></dt> -</dl> - -<p>If however another transport layer than TCP is selected, then -a pointer should be used instead to express the parameter to be -passed to custom functions. In that case the following functions should -be used instead. -</p> -<dl compact="compact"> -<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fptr">gnutls_transport_set_ptr</a> (gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>ptr</var>)</code></dt> -<dt><code><var>void</var> <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fptr2">gnutls_transport_set_ptr2</a> (gnutls_session_t <var>session</var>, gnutls_transport_ptr_t <var>recv_ptr</var>, gnutls_transport_ptr_t <var>send_ptr</var>)</code></dt> -</dl> - -<p>Moreover all of the following push and pull callbacks should be set. -</p> - - - - -<dl> -<dt><a name="index-gnutls_005ftransport_005fset_005fpush_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_push_func <var>push_func</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p><var>push_func</var>: a callback function similar to <code>write()</code> -</p> -<p>This is the function where you set a push function for gnutls to -use in order to send data. If you are going to use berkeley style -sockets, you do not need to use this function since the default -send(2) will probably be ok. Otherwise you should specify this -function for gnutls to be able to send data. -The callback should return a positive number indicating the -bytes sent, and -1 on error. -</p> -<p><code>push_func</code> is of the form, -ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t); -</p></dd></dl> - - - - -<dl> -<dt><a name="index-gnutls_005ftransport_005fset_005fvec_005fpush_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_vec_push_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_vec_push_func <var>vec_func</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p><var>vec_func</var>: a callback function similar to <code>writev()</code> -</p> -<p>Using this function you can override the default writev(2) -function for gnutls to send data. Setting this callback -instead of <code>gnutls_transport_set_push_function()</code> is recommended -since it introduces less overhead in the TLS handshake process. -</p> -<p><code>vec_func</code> is of the form, -ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt); -</p> -<p><strong>Since:</strong> 2.12.0 -</p></dd></dl> - - - - -<dl> -<dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_func <var>pull_func</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p><var>pull_func</var>: a callback function similar to <code>read()</code> -</p> -<p>This is the function where you set a function for gnutls to receive -data. Normally, if you use berkeley style sockets, do not need to -use this function since the default recv(2) will probably be ok. -The callback should return 0 on connection termination, a positive -number indicating the number of bytes received, and -1 on error. -</p> -<p><code>gnutls_pull_func</code> is of the form, -ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t); -</p></dd></dl> - - - - -<dl> -<dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p><var>func</var>: a callback function -</p> -<p>This is the function where you set a function for gnutls to know -whether data are ready to be received. It should wait for data a -given time frame in milliseconds. The callback should return 0 on -timeout, a positive number if data can be received, and -1 on error. -You’ll need to override this function if <code>select()</code> is not suitable -for the provided transport calls. -</p> -<p>As with <code>select()</code> , if the timeout value is zero the callback should return -zero if no data are immediately available. The special value -<code>GNUTLS_INDEFINITE_TIMEOUT</code> indicates that the callback should wait indefinitely -for data. -</p> -<p><code>gnutls_pull_timeout_func</code> is of the form, -int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms); -</p> -<p>This callback is necessary when <code>gnutls_handshake_set_timeout()</code> or -<code>gnutls_record_set_timeout()</code> are set. It will not be used when -non-blocking sockets are in use. That is, this function will -not operate when <code>GNUTLS_NONBLOCK</code> is specified in <code>gnutls_init()</code> , -or a custom pull function is registered without updating the -pull timeout function. -</p> -<p>The helper function <code>gnutls_system_recv_timeout()</code> is provided to -simplify writing callbacks. -</p> -<p><strong>Since:</strong> 3.0 -</p></dd></dl> - - -<p>The functions above accept a callback function which -should return the number of bytes written, or -1 on -error and should set <code>errno</code> appropriately. -In some environments, setting <code>errno</code> is unreliable. For example -Windows have several errno variables in different CRTs, or in other -systems it may be a non thread-local variable. If this is a concern to -you, call <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005ferrno">gnutls_transport_set_errno</a> with the intended errno -value instead of setting <code>errno</code> directly. -</p> - - - - -<dl> -<dt><a name="index-gnutls_005ftransport_005fset_005ferrno"></a>Function: <em>void</em> <strong>gnutls_transport_set_errno</strong> <em>(gnutls_session_t <var>session</var>, int <var>err</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p><var>err</var>: error value to store in session-specific errno variable. -</p> -<p>Store <code>err</code> in the session-specific errno variable. Useful values -for <code>err</code> are EINTR, EAGAIN and EMSGSIZE, other values are treated will be -treated as real errors in the push/pull function. -</p> -<p>This function is useful in replacement push and pull functions set by -<code>gnutls_transport_set_push_function()</code> and -<code>gnutls_transport_set_pull_function()</code> under Windows, where the -replacements may not have access to the same <code>errno</code> variable that is used by GnuTLS (e.g., the application is linked to -msvcr71.dll and gnutls is linked to msvcrt.dll). -</p></dd></dl> - -<p><acronym>GnuTLS</acronym> currently only interprets the EINTR, EAGAIN and EMSGSIZE errno -values and returns the corresponding <acronym>GnuTLS</acronym> error codes: -</p><ul> -<li> <code>GNUTLS_E_INTERRUPTED</code> -</li><li> <code>GNUTLS_E_AGAIN</code> -</li><li> <code>GNUTLS_E_LARGE_PACKET</code> -</li></ul> -<p>The EINTR and EAGAIN values are returned by interrupted system calls, -or when non blocking IO is used. All <acronym>GnuTLS</acronym> functions can be -resumed (called again), if any of the above error codes is returned. The -EMSGSIZE value is returned when attempting to send a large datagram. -</p> -<p>In the case of DTLS it is also desirable to override the generic -transport functions with functions that emulate the operation -of <code>recvfrom</code> and <code>sendto</code>. In addition -<acronym>DTLS</acronym> requires timers during the receive of a handshake -message, set using the <a href="Core-TLS-API.html#gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction">gnutls_transport_set_pull_timeout_function</a> -function. To check the retransmission timers the function -<a href="Datagram-TLS-API.html#gnutls_005fdtls_005fget_005ftimeout">gnutls_dtls_get_timeout</a> is provided, which returns the time -remaining until the next retransmission, or better the time until -<a href="Core-TLS-API.html#gnutls_005fhandshake">gnutls_handshake</a> should be called again. -</p> - - - - -<dl> -<dt><a name="index-gnutls_005ftransport_005fset_005fpull_005ftimeout_005ffunction-1"></a>Function: <em>void</em> <strong>gnutls_transport_set_pull_timeout_function</strong> <em>(gnutls_session_t <var>session</var>, gnutls_pull_timeout_func <var>func</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p><var>func</var>: a callback function -</p> -<p>This is the function where you set a function for gnutls to know -whether data are ready to be received. It should wait for data a -given time frame in milliseconds. The callback should return 0 on -timeout, a positive number if data can be received, and -1 on error. -You’ll need to override this function if <code>select()</code> is not suitable -for the provided transport calls. -</p> -<p>As with <code>select()</code> , if the timeout value is zero the callback should return -zero if no data are immediately available. The special value -<code>GNUTLS_INDEFINITE_TIMEOUT</code> indicates that the callback should wait indefinitely -for data. -</p> -<p><code>gnutls_pull_timeout_func</code> is of the form, -int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms); -</p> -<p>This callback is necessary when <code>gnutls_handshake_set_timeout()</code> or -<code>gnutls_record_set_timeout()</code> are set. It will not be used when -non-blocking sockets are in use. That is, this function will -not operate when <code>GNUTLS_NONBLOCK</code> is specified in <code>gnutls_init()</code> , -or a custom pull function is registered without updating the -pull timeout function. -</p> -<p>The helper function <code>gnutls_system_recv_timeout()</code> is provided to -simplify writing callbacks. -</p> -<p><strong>Since:</strong> 3.0 -</p></dd></dl> - - - - -<dl> -<dt><a name="index-gnutls_005fdtls_005fget_005ftimeout"></a>Function: <em>unsigned int</em> <strong>gnutls_dtls_get_timeout</strong> <em>(gnutls_session_t <var>session</var>)</em></dt> -<dd><p><var>session</var>: is a <code>gnutls_session_t</code> type. -</p> -<p>This function will return the milliseconds remaining -for a retransmission of the previously sent handshake -message. This function is useful when DTLS is used in -non-blocking mode, to estimate when to call <code>gnutls_handshake()</code> -if no packets have been received. -</p> -<p><strong>Returns:</strong> the remaining time in milliseconds. -</p> -<p><strong>Since:</strong> 3.0 -</p></dd></dl> - -<table class="menu" border="0" cellspacing="0"> -<tr><td align="left" valign="top">• <a href="Asynchronous-operation.html#Asynchronous-operation" accesskey="1">Asynchronous operation</a>:</td><td> </td><td align="left" valign="top"> -</td></tr> -<tr><td align="left" valign="top">• <a href="Reducing-round_002dtrips.html#Reducing-round_002dtrips" accesskey="2">Reducing round-trips</a>:</td><td> </td><td align="left" valign="top"> -</td></tr> -<tr><td align="left" valign="top">• <a href="DTLS-sessions.html#DTLS-sessions" accesskey="3">DTLS sessions</a>:</td><td> </td><td align="left" valign="top"> -</td></tr> -<tr><td align="left" valign="top">• <a href="DTLS-and-SCTP.html#DTLS-and-SCTP" accesskey="4">DTLS and SCTP</a>:</td><td> </td><td align="left" valign="top"> -</td></tr> -</table> - -<hr> -<div class="header"> -<p> -Next: <a href="TLS-handshake.html#TLS-handshake" accesskey="n" rel="next">TLS handshake</a>, Previous: <a href="Associating-the-credentials.html#Associating-the-credentials" accesskey="p" rel="prev">Associating the credentials</a>, Up: <a href="How-to-use-GnuTLS-in-applications.html#How-to-use-GnuTLS-in-applications" accesskey="u" rel="up">How to use GnuTLS in applications</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Function-and-Data-Index.html#Function-and-Data-Index" title="Index" rel="index">Index</a>]</p> -</div> - - - -</body> -</html> |