From: Nikos Mavrogiannopoulos Date: Sat, 26 Nov 2011 09:31:44 +0000 (+0100) Subject: documentation updates. X-Git-Tag: gnutls_3_0_9~40 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5cbd39faca0e1d1c40d69eda063d3002bad58f64;p=thirdparty%2Fgnutls.git documentation updates. --- diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 1c73f4ba44..70543121e0 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -301,38 +301,40 @@ current session using @funcref{gnutls_credentials_set}. @node Certificate credentials @subsection Certificates +@subsubheading Server certificate authentication When using certificates the server is required to have at least one -certificate and private key pair. A client may or may not have such a -pair. +certificate and private key pair. Clients may not hold such +a pair, but a server could require it. On this section we discuss +general issues applying to both client and server certificates. The next +section will elaborate on issues arising from client authentication only. @showfuncB{gnutls_certificate_allocate_credentials,gnutls_certificate_free_credentials} -After the credentials structures are initialized using the functions -above, the certificate and key pair should be loaded. This should -occur before any @acronym{TLS} session is initialized. +After the credentials structures are initialized, the certificate +and key pair must be loaded. This occurs before any @acronym{TLS} +session is initialized, and the same structures are reused for multiple sessions. Depending on the certificate type different loading functions -are available, and are shown below. -In the @acronym{X.509} case, the functions will -also accept and use a certificate list that leads to a trusted -authority. The certificate list must be ordered in such way that every +are available, as shown below. +For @acronym{X.509} certificates, the functions will +accept and use a certificate chain that leads to a trusted +authority. The certificate chain must be ordered in such way that every certificate certifies the one before it. The trusted authority's -certificate need not to be included, since the peer should possess it +certificate need not to be included since the peer should possess it already. @showfuncC{gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_file} @showfuncD{gnutls_certificate_set_openpgp_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_key} -As an alternative to loading from files, a callback may be used so that the -server or the client can specify the certificate and the key at the handshake time. +As an alternative to loading from files or buffers, a callback may be used for the +server or the client to specify the certificate and the key at the handshake time. In that case a certificate should be selected according the peer's signature algorithm preferences. To get those preferences use @funcref{gnutls_sign_algorithm_get_requested}. Both functions are shown below. @showfuncB{gnutls_certificate_set_retrieve_function,gnutls_sign_algorithm_get_requested} - Certificate verification is possible by loading the trusted authorities into the credentials structure by using the following functions, applicable to X.509 and OpenPGP certificates. @@ -372,6 +374,24 @@ for the acceptable security levels.} than the elliptic curves counterpart requires parameters to be generated and associated with a credentials structure by the server (see @ref{Parameter generation}). + +@subsubheading Client certificate authentication + +If a certificate is to be requested from the client during the handshake, the server +will send a certificate request message. This behavior is controlled @funcref{gnutls_certificate_server_set_request}. +The request contains a list of the acceptable by the server certificate signers. This list +is constructed using the trusted certificate authorities of the server. +In cases where the server supports a large number of certificate authorities +it makes sense not to advertise all of the names to save bandwidth. That can +be controlled using the function @funcref{gnutls_certificate_send_x509_rdn_sequence}. +This however will have the side-effect of not restricting the client to certificates +signed by server's acceptable signers. + +@showfuncdesc{gnutls_certificate_server_set_request} + +@showfuncdesc{gnutls_certificate_send_x509_rdn_sequence} + + @node SRP credentials @subsection SRP @@ -606,8 +626,8 @@ messages may arrive out of order. The @funcref{gnutls_record_check_pending} helper function is available to allow checking whether data are available to be read in a @acronym{GnuTLS} session -buffers. Note that this function complements but does not replace @code{select()}, -i.e., @funcref{gnutls_record_check_pending} reports no data to be read, @code{select()} +buffers. Note that this function complements but does not replace @funcintref{select}, +i.e., @funcref{gnutls_record_check_pending} reports no data to be read, @funcintref{select} should be called to check for data in the network buffers. @showfuncdesc{gnutls_record_check_pending} @@ -806,12 +826,64 @@ will allow V1 CAs in chains. @section Advanced and other topics @menu +* Session resumption:: * Parameter generation:: * Keying Material Exporters:: * Channel Bindings:: +* Interoperability:: * Compatibility with the OpenSSL library:: @end menu +@node Session resumption +@subsection Session resumption +@cindex resuming sessions +@cindex session resumption + +@subsubheading Client side + +To reduce time and roundtrips spent in a handshake the client can +utilize session resumption. This requires the client to retrieve and store +the session parameters. On new sessions to the same server the parameters must +be re-associated with sessions using @funcref{gnutls_session_set_data}. + +@showfuncC{gnutls_session_get_data,gnutls_session_get_id,gnutls_session_set_data} + +Keep in mind that sessions might be expired after some time, +and it may be normal for a server not to resume a session +even it was requested. That is to prevent temporal session keys +from becoming long-term keys. Also note that as a client you must enable, using the +priority functions, at least the algorithms used in the last session. + +It is highly recommended clients to enable the session ticket extension using +@funcref{gnutls_session_ticket_enable_client} in order to allow resumption with +servers that do not store any state. + +@showfuncA{gnutls_session_ticket_enable_client} + + +@subsubheading Server side + +In order to support resumption a server might do it either by storing +the session security parameters in a local database or by using session +tickets (see @ref{Session tickets}) to delegate storage to the client. Because +session tickets might not be supported by all clients, servers +might combine the two methods. + +A storing server needs to specify callback functions to store, retrieve and delete session data. These can be +registered with the functions below. The stored sessions in the database can be checked using @funcref{gnutls_db_check_entry} +for expiration. + +@showfuncD{gnutls_db_set_retrieve_function,gnutls_db_set_store_function,gnutls_db_set_ptr,gnutls_db_set_remove_function} +@showfuncA{gnutls_db_check_entry} + +A server utilizing tickets should use +@funcref{gnutls_session_ticket_key_generate} to generate a ticket encryption key and +call @funcref{gnutls_session_ticket_enable_server} to enable the extension. + +@showfuncA{gnutls_session_ticket_enable_server} +@showfuncdesc{gnutls_session_ticket_key_generate} + + @node Parameter generation @subsection Parameter generation @cindex parameter generation @@ -922,6 +994,32 @@ Note that it must be run after a successful TLS handshake. @} @end smallexample +@node Interoperability +@subsection Interoperability + +The @acronym{TLS} protocols support many ciphersuites, extensions and version +numbers. As a result, few implementations are +not able to properly interoperate once faced with extensions or version protocols +they do not support and understand. The @acronym{TLS} protocol allows for a +graceful downgrade to the commonly supported options, but practice shows +it is not always implemented correctly. + +Because there is no way to achieve maximum interoperability with broken peers +without sacrificing security, @acronym{GnuTLS} ignores such peers by default. +This might not be acceptable in cases where maximum compatibility +is required. Thus we allow enabling compatibility with broken peers using +priority strings (see @ref{Priority Strings}). An example priority string that +is known to provide wide compatibility even with broken peers +is shown below: +@verbatim +NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT +@end verbatim +This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and +will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol +options that are known to cause compatibility problems. Note however that +there are known attacks against those protocol versions and +this mode trades security for compatibility. + @node Compatibility with the OpenSSL library @subsection Compatibility with the OpenSSL library @cindex OpenSSL diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index 9bc63a0eea..5f5f77d1ec 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -304,7 +304,6 @@ the handshake protocol, i.e., the ciphersuite negotiation. * Authentication:: TLS authentication. * Client Authentication:: Requesting a certificate from the client. * Resuming Sessions:: Reusing previously established keys. -* Interoperability:: About interoperability with other implementations. @end menu @@ -454,92 +453,27 @@ with the credential types is shown in @ref{tab:key-exchange-cred}. In the case of ciphersuites that use certificate authentication, the authentication of the client is optional in @acronym{TLS}. A server may request a certificate from the client using the -@funcref{gnutls_certificate_server_set_request} function. If a certificate -is to be requested from the client during the handshake, the server -will send a certificate request message that contains a list of -acceptable certificate signers. In @acronym{GnuTLS} the certificate -signers list is constructed using the trusted certificate authorities -by the server. That is the ones set using the following functions. - -@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_trust_mem} - -@showfuncdesc{gnutls_certificate_server_set_request} - -In cases where the server supports a large number of certificate authorities -it makes sense not to advertise all of the names to save bandwidth. That can -be controlled using the function @funcref{gnutls_certificate_send_x509_rdn_sequence}. -This however will have the side-effect of not restricting the client to certificates -signed by server's acceptable signers. - -@showfuncdesc{gnutls_certificate_send_x509_rdn_sequence} +@funcref{gnutls_certificate_server_set_request} function. We elaborate +in @ref{Certificate credentials}. @node Resuming Sessions @subsection Resuming sessions @anchor{resume} @cindex resuming sessions -@cindex session resuming +@cindex session resumption The TLS handshake process performs expensive calculations and a busy server might easily be put under load. To -reduce the load, clients may use session resumption. Session -resumption is a feature of the @acronym{TLS} protocol which allows a +reduce the load, session resumption may be used. This +is a feature of the @acronym{TLS} protocol which allows a client to connect to a server after a successful handshake, without the expensive calculations. This is achieved by re-using the previously -established keys. @acronym{GnuTLS} supports this feature, and the -example in @ref{ex:resume-client} illustrates a typical use of it. - -Keep in mind that sessions might be expired after some time, -thus it may be normal for a server not to resume a session -even if you requested that. That is to prevent temporal session keys -from becoming long-term keys. Also note that as a client you must enable, using the -priority functions, at least the algorithms used in the last session. - -The resuming capability, mostly in the server side, is one of the -problems of a thread-safe TLS implementations. The problem is that all -threads must share information in order to be able to resume -sessions. The gnutls approach is, in case of a client, to leave all -the burden of resuming to the client, i.e., copy and keep the -necessary parameters. The relevant functions are listed below. - -@showfuncC{gnutls_session_get_data,gnutls_session_get_id,gnutls_session_set_data} - -Server side is different. A server needs to specify callback -functions which store, retrieve and delete session data. These can be -registered with the functions shown below. - -@showfuncD{gnutls_db_set_retrieve_function,gnutls_db_set_store_function,gnutls_db_set_ptr,gnutls_db_set_remove_function} - -It might also be useful to be able to check for expired sessions in -order to remove them, and save space. The function -@funcref{gnutls_db_check_entry} is provided for that reason. - -@showfuncA{gnutls_db_check_entry} - -@node Interoperability -@subsection Interoperability - -The @acronym{TLS} protocols support many ciphersuites, extensions and version -numbers. As a result, few implementations are -not able to properly interoperate once faced with extensions or version protocols -they do not support and understand. The @acronym{TLS} protocol allows for a -graceful downgrade to the commonly supported options, but practice shows -it is not always implemented correctly. - -Because there is no way to achieve maximum interoperability with broken peers -without sacrificing security, @acronym{GnuTLS} ignores such peers by default. -This might not be acceptable in cases where maximum compatibility -is required. Thus we allow enabling compatibility with broken peers using -priority strings (see @ref{Priority Strings}). An example priority string that -is known to provide wide compatibility even with broken peers -is shown below: -@verbatim -NORMAL:-VERS-TLS-ALL:+VERS-TLS1.0:+VERS-SSL3.0:%COMPAT -@end verbatim -This priority string will only enable SSL 3.0 and TLS 1.0 as protocols and -will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol -options that are known to cause compatibility problems. Note however that -there are known attacks against those protocol versions and -this mode trades security for compatibility. +established keys, meaning the server needs to store the state of established +connections (unless session tickets are used -- @ref{Session tickets}). + +Session resumption is an integral part of @acronym{GnuTLS}, and +@ref{Session resumption} and @ref{ex:resume-client} illustrate typical +uses of it. @node TLS Extensions @section TLS extensions @@ -603,19 +537,14 @@ client. @cindex session tickets @cindex tickets -To resume a TLS session the server normally store some state. This -complicates deployment, and typical situations the client can cache -information and send it to the server instead. The Session Ticket +To resume a TLS session the server normally store session parameters. This +complicates deployment, and could be avoiding by delegating the storage +to the client. Because session parameters are sensitive they are encrypted +and authenticated with a key only known to the server and then sent to the +client. The Session Ticket extension implements this idea, and it is documented in RFC 5077 @xcite{TLSTKT}. -Clients can enable support for TLS tickets with -@funcref{gnutls_session_ticket_enable_client} and servers use -@funcref{gnutls_session_ticket_key_generate} to generate a key and -@funcref{gnutls_session_ticket_enable_server} to enable the extension. -Clients resume sessions using the normal session resumption procedure (see @ref{resume}). - -@showfuncC{gnutls_session_ticket_key_generate,gnutls_session_ticket_enable_server,gnutls_session_ticket_enable_client} @node Safe renegotiation @subsection Safe renegotiation diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex index de5cda8caa..b2d1d5a2e9 100755 --- a/doc/scripts/mytexi2latex +++ b/doc/scripts/mytexi2latex @@ -78,7 +78,7 @@ my $match = "[\\w\\d-\\.\\/\\@\\:\_\\\\\#]"; my $spacematch = "[\\s\\w\\d-\\.\\/\\@\\#\\:]"; my $mathmatch = "[\\s\\w\\d-\\.\\/\\:\\(\\)\\+\\/\\^\\'\\=\{\}\\\\\\,]"; my $underscorematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\~]"; -my $codematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%\\,]"; +my $codematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%\\#\\,]"; my $extcodematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%\\,\\{\\}]"; my ($line, $prev_mode); my ($verbatim, $label); @@ -222,8 +222,8 @@ multitable: } } - $line =~ s/\@subsubheading (.+)/\\paragraph{$1}/g; - $line =~ s/\@subheading (.+)/\\subsection{$1}/g; + $line =~ s/\@subsubheading (.+)/\\subsubsection\*{$1}/g; + $line =~ s/\@subheading (.+)/\\subsection\*{$1}/g; if ($line =~ s/\@section (.+)/\\section{$1}/g) { if ($label ne '') {