Next: TLS handshake, Previous: Associating the credentials, Up: How to use GnuTLS in applications [Contents][Index]
The next step is to setup the underlying transport layer details. The Berkeley sockets are implicitly used by GnuTLS, thus a call to gnutls_transport_set_int would be sufficient to specify the socket descriptor.
void gnutls_transport_set_int (gnutls_session_t session, int fd)void gnutls_transport_set_int2 (gnutls_session_t session, int recv_fd, int send_fd)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.
void gnutls_transport_set_ptr (gnutls_session_t session, gnutls_transport_ptr_t ptr)void gnutls_transport_set_ptr2 (gnutls_session_t session, gnutls_transport_ptr_t recv_ptr, gnutls_transport_ptr_t send_ptr)Moreover all of the following push and pull callbacks should be set.
session: is a gnutls_session_t type.
push_func: a callback function similar to write()
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.
push_func is of the form,
ssize_t (*gnutls_push_func)(gnutls_transport_ptr_t, const void*, size_t);
session: is a gnutls_session_t type.
vec_func: a callback function similar to writev()
Using this function you can override the default writev(2)
function for gnutls to send data. Setting this callback
instead of gnutls_transport_set_push_function() is recommended
since it introduces less overhead in the TLS handshake process.
vec_func is of the form,
ssize_t (*gnutls_vec_push_func) (gnutls_transport_ptr_t, const giovec_t * iov, int iovcnt);
Since: 2.12.0
session: is a gnutls_session_t type.
pull_func: a callback function similar to read()
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.
gnutls_pull_func is of the form,
ssize_t (*gnutls_pull_func)(gnutls_transport_ptr_t, void*, size_t);
session: is a gnutls_session_t type.
func: a callback function
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 select() is not suitable
for the provided transport calls.
As with select() , if the timeout value is zero the callback should return
zero if no data are immediately available. The special value
GNUTLS_INDEFINITE_TIMEOUT indicates that the callback should wait indefinitely
for data.
gnutls_pull_timeout_func is of the form,
int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
This callback is necessary when gnutls_handshake_set_timeout() or
gnutls_record_set_timeout() are set, under TLS1.3 and for enforcing the DTLS
mode timeouts when in blocking mode.
For compatibility with future GnuTLS versions this callback must be set when
a custom pull function is registered. The callback will not be used when the
session is in TLS mode with non-blocking sockets. That is, when GNUTLS_NONBLOCK
is specified for a TLS session in gnutls_init() .
The helper function gnutls_system_recv_timeout() is provided to
simplify writing callbacks.
Since: 3.0
The functions above accept a callback function which
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 in other
systems it may be a non 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.
session: is a gnutls_session_t type.
err: error value to store in session-specific errno variable.
Store err in the session-specific errno variable. Useful values
for err are EINTR, EAGAIN and EMSGSIZE, other values are treated will be
treated as real errors in the push/pull function.
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).
This function is unreliable if you are using the same
session in different threads for sending and receiving.
GnuTLS currently only interprets the EINTR, EAGAIN and EMSGSIZE errno values and returns the corresponding GnuTLS error codes:
GNUTLS_E_INTERRUPTED
GNUTLS_E_AGAIN
GNUTLS_E_LARGE_PACKET
The EINTR and EAGAIN values are returned by interrupted system calls, or when non blocking IO is used. All GnuTLS 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.
In the case of DTLS it is also desirable to override the generic
transport functions with functions that emulate the operation
of recvfrom and sendto. In addition
DTLS requires timers during the receive of a handshake
message, set using the gnutls_transport_set_pull_timeout_function
function. To check the retransmission timers the function
gnutls_dtls_get_timeout is provided, which returns the time
remaining until the next retransmission, or better the time until
gnutls_handshake should be called again.
session: is a gnutls_session_t type.
func: a callback function
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 select() is not suitable
for the provided transport calls.
As with select() , if the timeout value is zero the callback should return
zero if no data are immediately available. The special value
GNUTLS_INDEFINITE_TIMEOUT indicates that the callback should wait indefinitely
for data.
gnutls_pull_timeout_func is of the form,
int (*gnutls_pull_timeout_func)(gnutls_transport_ptr_t, unsigned int ms);
This callback is necessary when gnutls_handshake_set_timeout() or
gnutls_record_set_timeout() are set, under TLS1.3 and for enforcing the DTLS
mode timeouts when in blocking mode.
For compatibility with future GnuTLS versions this callback must be set when
a custom pull function is registered. The callback will not be used when the
session is in TLS mode with non-blocking sockets. That is, when GNUTLS_NONBLOCK
is specified for a TLS session in gnutls_init() .
The helper function gnutls_system_recv_timeout() is provided to
simplify writing callbacks.
Since: 3.0
session: is a gnutls_session_t type.
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 gnutls_handshake()
if no packets have been received.
Returns: the remaining time in milliseconds.
Since: 3.0
| • Asynchronous operation | ||
| • Reducing round-trips | ||
| • Zero-roundtrip mode | ||
| • Anti-replay protection | ||
| • DTLS sessions | ||
| • DTLS and SCTP |
Next: TLS handshake, Previous: Associating the credentials, Up: How to use GnuTLS in applications [Contents][Index]