diff options
author | Nikos Mavrogiannopoulos <nmav@redhat.com> | 2015-04-30 14:06:09 +0200 |
---|---|---|
committer | Nikos Mavrogiannopoulos <nmav@redhat.com> | 2015-04-30 14:47:05 +0200 |
commit | 6960214489571befc743894660e9b39f830eba75 (patch) | |
tree | 35ba804254c525acd30dd25b075ed3963d6c40e6 | |
parent | 830419da7befb3d51cec3f0a41a547a5c00122af (diff) | |
download | gnutls-6960214489571befc743894660e9b39f830eba75.tar.gz |
doc: updated async operation text
-rw-r--r-- | doc/cha-gtls-app.texi | 45 |
1 files changed, 30 insertions, 15 deletions
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index c15d7f382b..e6b60618f3 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -739,6 +739,7 @@ remaining until the next retransmission, or better the time until @node Asynchronous operation @subsection Asynchronous operation + @acronym{GnuTLS} can be used with asynchronous socket or event-driven programming. The approach is similar to using Berkeley sockets under such an environment. The blocking, due to network interaction, calls such as @@ -755,18 +756,34 @@ The only exception is @funcref{gnutls_record_send}, which if interrupted subsequent calls need not to include the data to be sent (can be called with NULL argument). -The @funcintref{select} system call can also be used in combination with the -@acronym{GnuTLS} functions. @funcintref{select} allows monitoring of sockets -and notifies on them being ready for reading or writing data. Note however -that this system call cannot notify on data present in @acronym{GnuTLS} -read buffers, it is only applicable to the kernel sockets API. Thus if -you are using it for reading from a @acronym{GnuTLS} session, make sure -that any cached data are read completely. That can be achieved by checking there -are no data waiting to be read (using @funcref{gnutls_record_check_pending}), +When using the @funcintref{select} system call though, one should remember +that it is only applicable to the kernel sockets API. To check for any +available buffers in a @acronym{GnuTLS} session, +utilize @funcref{gnutls_record_check_pending}, either before the @funcintref{select} system call, or after a call to @funcref{gnutls_record_recv}. @acronym{GnuTLS} does not keep a write buffer, thus when writing no additional actions are required. +The following paragraphs describe the detailed requirements for non-blocking +operation when using the TLS or DTLS protocols. + +@subsubsection TLS protocol +There are no special requirements for the TLS protocol operation in non-blocking +mode if a non-blocking socket is used. + +It is recommended, however, for future compatibility, when in non-blocking mode, to +call the @funcref{gnutls_init} function with the +@code{GNUTLS_NONBLOCK} flag set (see @ref{Session initialization}). + +@subsubsection Datagram TLS protocol +When in non-blocking mode the function, the @funcref{gnutls_init} function +must be called with the @code{GNUTLS_NONBLOCK} flag set (see @ref{Session initialization}). + +In constrast with the TLS protocol, the pull timeout function is required, +but will only be called with a timeout of zero. In that case it should indicate +whether there are data to be received or not. When not using the default pull function, +then @funcref{gnutls_transport_set_pull_timeout_function} should be called. + Although in the TLS protocol implementation each call to receive or send function implies to restoring the same function that was interrupted, in the DTLS protocol this requirement isn't true. @@ -775,13 +792,11 @@ a received message and thus @funcref{gnutls_record_get_direction} must be called to decide which direction to check prior to restoring a function call. @showfuncdesc{gnutls_record_get_direction} -Moreover, to prevent blocking from DTLS' retransmission timers to block a -handshake, the @funcref{gnutls_init} function should be called with the -@code{GNUTLS_NONBLOCK} flag set (see @ref{Session initialization}). In that -case, in order to be able to use the DTLS handshake timers, the function -@funcref{gnutls_dtls_get_timeout} should be used to estimate when to call -@funcref{gnutls_handshake} if no packets have been received. - +When calling @funcref{gnutls_handshake} through a multi-plexer, +to be able to handle properly the DTLS handshake retransmission timers, +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 DTLS sessions @subsection DTLS sessions |