3.2 The Transport Layer

TLS is not limited to one transport layer, it can be used above any transport layer, as long as it is a reliable one. A set of functions is provided and their purpose is to load to GnuTLS the required callbacks to access the transport layer.

• gnutls_transport_set_push_function
• gnutls_transport_set_pull_function
• gnutls_transport_set_ptr
• gnutls_transport_set_lowat
• gnutls_transport_set_errno

These 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 errno appropriately.

In some environments, setting 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 gnutls_transport_set_errno with the intended errno value instead of setting errno directly.

GnuTLS currently only interprets the EINTR and EAGAIN errno values and returns the corresponding GnuTLS error codes GNUTLS_E_INTERRUPTED and GNUTLS_E_AGAIN. These values are usually returned by interrupted system calls, or when non blocking IO is used. All 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 GnuTLS function, since signals do not interrupt GnuTLS' functions.

For non blocking sockets or other custom made pull/push functions the gnutls_transport_set_lowat must be called, with a zero low water mark value.

By default, if the transport functions are not set, GnuTLS will use the Berkeley Sockets functions. In this case GnuTLS will use some hacks in order for select to work, thus making it easy to add TLS support to existing TCP/IP servers.