or usernames and passwords should also be associated with the session
current session using @funcref{gnutls_credentials_set} (see @ref{Authentication methods}).
+@subsection Setting up the transport layer
+
The next step is to setup the underlying transport layer details. The
-Berkeley sockets for TCP are implicitly used by default in GnuTLS, thus a
+Berkeley sockets are implicitly used by GnuTLS, thus a
call to @funcref{gnutls_transport_set_ptr2} would be sufficient to
specify the socket descriptor.
@showfuncdesc{gnutls_transport_set_vec_push_function}
@showfuncdesc{gnutls_transport_set_pull_function}
-In the case of DTLS it is also desirable to override the
-functions above with functions that emulate the operation
+The functions above accept a callback function which
+should return the number of bytes written, or -1 on
+error and should set @code{errno} appropriately.
+In some environments, setting @code{errno} 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 @funcref{gnutls_transport_set_errno} with the intended errno
+value instead of setting @code{errno} directly.
+
+@showfuncdesc{gnutls_transport_set_errno}
+
+@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
+values and returns the corresponding @acronym{GnuTLS} error codes:
+@itemize
+@item @code{GNUTLS_E_INTERRUPTED}
+@item @code{GNUTLS_E_AGAIN}
+@end itemize
+The EINTR and EAGAIN values are returned by interrupted system calls,
+or when non blocking IO is used. All @acronym{GnuTLS} functions can be
+resumed (called again), if any of the above error codes is returned.
+
+In the case of DTLS it is also desirable to override the generic
+transport functions with functions that emulate the operation
of @code{recvfrom} and @code{sendto}. In addition
-the following function must also be called to specify a
-callback that will receive data from within a specified
-time limit.
+@acronym{DTLS} requires timers during the receive of a handshake
+message. This requires the following function to be used.
@showfuncdesc{gnutls_transport_set_pull_timeout_function}
+To avoid @acronym{GnuTLS} from blocking in a DTLS handshake on
+a timer, the @funcref{gnutls_init} can be called with the
+@code{GNUTLS_NONBLOCK} flag (see @ref{TLS and DTLS sessions}).
+
+
@subsection Handshake
Once a session has been initialized and a network
connection has been set up, TLS and DTLS protocols
@acronym{TLS} is not limited to any transport layer and can be used
above any transport layer, as long as it is a reliable one. @acronym{DTLS}
can be used over reliable and unreliable transport layers.
-A set of functions is provided and their purpose is to load to @acronym{GnuTLS} the
-required callbacks to access the transport layer.
-
-@showfuncE{gnutls_transport_set_push_function,gnutls_transport_set_vec_push_function,gnutls_transport_set_pull_timeout_function,gnutls_transport_set_pull_function,gnutls_transport_set_ptr}
-
-The function @funcref{gnutls_transport_set_pull_timeout_function} is only applicable
-to @acronym{DTLS} sessions.
-All those functions accept a callback function as a parameter. The
-callback functions should return the number of bytes written, or -1 on
-error and should set @code{errno} appropriately.
-
-In some environments, setting @code{errno} is unreliable, for example
-Windows have several errno variables in different CRTs, or it may be
-that errno is not a thread-local variable. If this is a concern to
-you, call @funcref{gnutls_transport_set_errno} with the intended errno
-value instead of setting @code{errno} directly.
-
-@showfuncA{gnutls_transport_set_errno}
-
-@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
-values and returns the corresponding @acronym{GnuTLS} error codes:
-@itemize
-@item @code{GNUTLS_E_INTERRUPTED}
-@item @code{GNUTLS_E_AGAIN}
-@end itemize
-These values are usually returned by interrupted system calls, or when non blocking
-IO is used. All @acronym{GnuTLS} functions can be resumed (called
-again), if any of these error codes is returned. The error codes
-above refer to the system call, not the @acronym{GnuTLS} function,
-since signals do not interrupt @acronym{GnuTLS}' functions.
-
-@acronym{DTLS} however deviates from this rule. Because it requires
-timers and waiting for peer's messages during the handshake process,
-@acronym{GnuTLS} will block and might be interrupted by signals. The
-blocking operation of @acronym{GnuTLS} during @acronym{DTLS} handshake
-can be changed using the appropriate flags in @funcref{gnutls_init} (see
-@ref{TLS and DTLS sessions}).
-By default, if the transport functions are not set, @acronym{GnuTLS}
-will use the Berkeley sockets.
+@acronym{GnuTLS} supports TCP and UDP layers transparently using
+the Berkeley sockets API. However, any transport layer can be used
+by providing callbacks for @acronym{GnuTLS} to access the transport layer
+(for details see @ref{TLS and DTLS sessions}).
@node The TLS record protocol
@section The TLS record protocol
* @session: is a #gnutls_session_t structure.
* @ptr: is the value.
*
- * Used to set the first argument of the transport function (like PUSH
- * and PULL). In berkeley style sockets this function will set the
- * connection handle.
+ * Used to set the first argument of the transport function (for push
+ * and pull callbacks). In berkeley style sockets this function will set the
+ * connection descriptor.
**/
void
gnutls_transport_set_ptr (gnutls_session_t session,
* @recv_ptr: is the value for the pull function
* @send_ptr: is the value for the push function
*
- * Used to set the first argument of the transport function (like PUSH
- * and PULL). In berkeley style sockets this function will set the
- * connection handle. With this function you can use two different
+ * Used to set the first argument of the transport function (for push
+ * and pull callbacks). In berkeley style sockets this function will set the
+ * connection descriptor. With this function you can use two different
* pointers for receiving and sending.
**/
void
* for @err is EAGAIN and EINTR, other values are treated will be
* treated as real errors in the push/pull function.
*
- * This function is useful in replacement push/pull functions set by
- * gnutls_transport_set_push_function and
- * gnutls_transport_set_pullpush_function under Windows, where the
- * replacement push/pull may not have access to the same @errno
+ * This function is useful in replacement push and pull functions set by
+ * gnutls_transport_set_push_function() and
+ * gnutls_transport_set_pull_function() under Windows, where the
+ * replacements may not have access to the same @errno
* variable that is used by GnuTLS (e.g., the application is linked to
* msvcr71.dll and gnutls is linked to msvcrt.dll).
*
projects / thirdparty / gnutls.git / commitdiff
