From: Nikos Mavrogiannopoulos Date: Sat, 13 Aug 2011 07:42:33 +0000 (+0200) Subject: documentation updates X-Git-Tag: gnutls_3_0_1~13^2~9 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bab1df49567bfa91d19cc3fd9d1f332252e0ac91;p=thirdparty%2Fgnutls.git documentation updates --- diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 637365e410..a00ded33fb 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -137,10 +137,12 @@ current session using @funcref{gnutls_credentials_set} (see @ref{Authentication 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 -call to @funcref{gnutls_transport_set_ptr} would be sufficient to +call to @funcref{gnutls_transport_set_ptr2} would be sufficient to specify the socket descriptor. -@showfuncdesc{gnutls_transport_set_ptr} +@showfuncdesc{gnutls_transport_set_ptr2} + +@showfuncA{gnutls_transport_set_ptr} If however another transport layer than TCP is selected, then the following functions have to be specified. @@ -174,7 +176,31 @@ has been used. In both cases the following function can be used to verify the peer's certificate (see @ref{Certificate authentication} for more information). -@showfuncA{gnutls_certificate_verify_peers2} +@showfuncA{gnutls_certificate_verify_peers2} + + +@subsection Data transfer and termination +Once the handshake is complete and peer's identity +has been verified data can be exchanged. The available +functions resemble the POSIX @code{recv} and @code{send} +functions. + +@showfuncdesc{gnutls_record_send} +@showfuncdesc{gnutls_record_recv} + +In DTLS it is adviceable to use the extended receive +function shown below, because it allows the extraction +of the sequence number. This is required in DTLS because +messages may arrive out of order. + +@showfuncdesc{gnutls_record_recv_seq} + +A helper function is available to check whether data +to be read are pending in a @acronym{GnuTLS} session. +This is the equivalent in POSIX systems to using @code{select} +for data waiting to be read by @code{recv}. + +@showfuncdesc{gnutls_record_check_pending} Once a TLS or DTLS session is no longer needed, it is recommended to use @funcref{gnutls_bye} to terminate the @@ -209,8 +235,8 @@ and proceed to a proper handshake. @showfuncdesc{gnutls_dtls_prestate_set} -All the above apply to server side only. The client side cookie handling -is done in @funcref{gnutls_handshake}. However both client and server +Note that the above apply to server side only. The client side cookie handling +is part of @funcref{gnutls_handshake}. However both client and server side should set the correct maximum transfer unit for the layer underneath @acronym{GnuTLS}. This would allow proper fragmentation of DTLS messages. diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index 7ab0361cb0..7575ab719c 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -111,7 +111,7 @@ will use the Berkeley sockets. The record protocol is the secure communications provider. Its purpose is to encrypt, authenticate and ---optionally--- compress packets. -@showfuncdesc{gnutls_record_send} +@showfuncA{gnutls_record_send} The record layer functions can be called at any time after the handshake process is finished, when there is need to receive @@ -132,10 +132,7 @@ The record protocol initially starts with NULL parameters, which means no encryption, and no MAC is used. Encryption and authentication begin just after the handshake protocol has finished. -@showfuncdesc{gnutls_record_recv} -@showfuncdesc{gnutls_record_recv_seq} -@showfuncdesc{gnutls_record_check_pending} -@c @showfuncdesc{gnutls_record_get_direction} +@showfuncD{gnutls_record_recv,gnutls_record_recv_seq,gnutls_record_check_pending,gnutls_record_get_direction} @menu * Encryption algorithms used in the record layer:: diff --git a/doc/cha-library.texi b/doc/cha-library.texi index 1347460847..23020c4538 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -195,7 +195,7 @@ int main() @section Callback functions @cindex Callback functions -There are several cases where @acronym{GnuTLS} may need some out of +There are several cases where @acronym{GnuTLS} may need out of band input from your program. This is now implemented using some callback functions, which your program is expected to register. diff --git a/lib/gnutls_buffers.c b/lib/gnutls_buffers.c index d7a5d63864..5478b3ffa4 100644 --- a/lib/gnutls_buffers.c +++ b/lib/gnutls_buffers.c @@ -87,7 +87,7 @@ _gnutls_record_buffer_put (gnutls_session_t session, * This function checks if there are any data to receive in the gnutls * buffers. * - * Returns: the size of that data or 0. + * Returns: The size of that data or 0. **/ size_t gnutls_record_check_pending (gnutls_session_t session) diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c index 46c42bfd7e..6c1f72e4ea 100644 --- a/lib/gnutls_record.c +++ b/lib/gnutls_record.c @@ -65,7 +65,7 @@ struct tls_record_st { * * Get TLS version, a #gnutls_protocol_t value. * - * Returns: the version of the currently used protocol. + * Returns: The version of the currently used protocol. **/ gnutls_protocol_t gnutls_protocol_get_version (gnutls_session_t session) @@ -143,7 +143,7 @@ gnutls_transport_set_ptr2 (gnutls_session_t session, * PUSH and PULL). This must have been set using * gnutls_transport_set_ptr(). * - * Returns: first argument of the transport function. + * Returns: The first argument of the transport function. **/ gnutls_transport_ptr_t gnutls_transport_get_ptr (gnutls_session_t session) @@ -1200,7 +1200,7 @@ _gnutls_recv_int (gnutls_session_t session, content_type_t type, * you could provide a %NULL pointer for data, and 0 for * size. cf. gnutls_record_get_direction(). * - * Returns: the number of bytes sent, or a negative error code. The + * Returns: The number of bytes sent, or a negative error code. The * number of bytes sent might be less than @data_size. The maximum * number of bytes this function can send in a single call depends * on the negotiated maximum record size. @@ -1237,7 +1237,7 @@ gnutls_record_send (gnutls_session_t session, const void *data, * initiated a handshake. In that case the server can only initiate a * handshake or terminate the connection. * - * Returns: the number of bytes received and zero on EOF (for stream + * Returns: The number of bytes received and zero on EOF (for stream * connections). A negative error code is returned in case of an error. * The number of bytes received might be less than the requested @data_size. **/ @@ -1258,12 +1258,10 @@ gnutls_record_recv (gnutls_session_t session, void *data, size_t data_size) * This function is the same as gnutls_record_recv(), except that * it returns in addition to data, the sequence number of the data. * This is useful in DTLS where record packets might be received - * out-of-order. - * In DTLS the least significant 48-bits are a unique sequence - * number, per handshake. If your application is using TLS re-handshakes - * then the full 64-bits should be used as a unique sequence. + * out-of-order. The returned 8-byte sequence number should be + * treated as a unique message identification. * - * Returns: the number of bytes received and zero on EOF. A negative + * Returns: The number of bytes received and zero on EOF. A negative * error code is returned in case of an error. The number of bytes * received might be less than @data_size. *