Reformat paragraphs.

1 files changed, 155 insertions, 134 deletions

diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 913f8f91f6..2ecde1e306 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -386,12 +386,12 @@ widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library,
 to ease integration with existing applications.
 
 @acronym{GnuTLS} consists of three independent parts, namely the ``TLS
-protocol part'', the ``Certificate part'', and the ``Cryptographic backend''
-part.  The `TLS protocol part' is the actual protocol implementation,
-and is entirely implemented within the @acronym{GnuTLS} library.  The
-`Certificate part' consists of the certificate parsing, and
-verification functions which is partially implemented in the
-@acronym{GnuTLS} library.  The
+protocol part'', the ``Certificate part'', and the ``Cryptographic
+backend'' part.  The `TLS protocol part' is the actual protocol
+implementation, and is entirely implemented within the
+@acronym{GnuTLS} library.  The `Certificate part' consists of the
+certificate parsing, and verification functions which is partially
+implemented in the @acronym{GnuTLS} library.  The
 @acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}},
 a library which offers @acronym{ASN.1} parsing capabilities, is used
 for the @acronym{X.509} certificate parsing functions.  A smaller
@@ -400,8 +400,9 @@ version of
 is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}.
 The ``Cryptographic backend'' is provided by the
 @acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}}
-library@footnote{On current versions of GnuTLS it is possible
-to override the default crypto backend. Check @pxref{Cryptographic Backend} for details}.
+library@footnote{On current versions of GnuTLS it is possible to
+override the default crypto backend. Check @pxref{Cryptographic
+Backend} for details}.
 
 In order to ease integration in embedded systems, parts of the
 @acronym{GnuTLS} library can be disabled at compile time. That way a
@@ -426,10 +427,10 @@ having seen the examples (@pxref{examples}).
 As shown in the figure, there is a read-only global state that is
 initialized once by the global initialization function.  This global
 structure, among others, contains the memory allocation functions
-used, and some structures needed for the @acronym{ASN.1} parser.  This structure
-is never modified by any @acronym{GnuTLS} function, except for the
-deinitialization function which frees all memory allocated in the
-global structure and is called after the program has permanently
+used, and some structures needed for the @acronym{ASN.1} parser.  This
+structure is never modified by any @acronym{GnuTLS} function, except
+for the deinitialization function which frees all memory allocated in
+the global structure and is called after the program has permanently
 finished using @acronym{GnuTLS}.
 
 The credentials structure is used by some authentication methods, such
@@ -464,8 +465,8 @@ resumed one, and will share the same session ID with the previous one.
 @node Error handling
 @section Error Handling
 
-In @acronym{GnuTLS} most functions return an integer type as a result.  In
-almost all cases a zero or a positive number means success, and a
+In @acronym{GnuTLS} most functions return an integer type as a result.
+In almost all cases a zero or a positive number means success, and a
 negative number indicates failure, or a situation that some action has
 to be taken. Thus negative error codes may be fatal or not.
 
@@ -496,9 +497,9 @@ behavior the @ref{gnutls_global_set_mem_functions} function is
 available which can be used to set other memory handlers than the
 defaults.
 
-The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has such
-secure memory allocation functions available. These should be used in
-cases where even the system's swap memory is not considered
+The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has
+such secure memory allocation functions available. These should be
+used in cases where even the system's swap memory is not considered
 secure. See the documentation of @acronym{Libgcrypt} for more
 information.
 
@@ -779,9 +780,10 @@ encrypted packet.
 
 @end enumerate
 
-Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346} which is implemented
-in @acronym{GnuTLS}. For a detailed discussion see the archives of the
-TLS Working Group mailing list and the paper @xcite{CBCATT}.
+Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346}
+which is implemented in @acronym{GnuTLS}. For a detailed discussion
+see the archives of the TLS Working Group mailing list and the paper
+@xcite{CBCATT}.
 
 @node The TLS Alert Protocol
 @section The TLS Alert Protocol
@@ -890,21 +892,20 @@ are shown in @ref{ciphersuites}.
 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
-@ref{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
+@ref{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
 @itemize
 @item @ref{gnutls_certificate_set_x509_trust_file}
 @item @ref{gnutls_certificate_set_x509_trust_mem}
 @end itemize
 
-Sending of the names of the CAs can be controlled using 
-@ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, 
-may send a certificate, signed by one of the server's acceptable 
-signers. 
+Sending of the names of the CAs can be controlled using
+@ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may
+send a certificate, signed by one of the server's acceptable signers.
 
 @subsection Resuming Sessions
 @anchor{resume}
@@ -930,8 +931,8 @@ 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. See the functions:
+the burden of resuming to the client. I.e., copy and keep the
+necessary parameters. See the functions:
 
 @itemize
 
@@ -1027,11 +1028,13 @@ resume functions, @ref{resume}.
 @section Selecting Cryptographic Key Sizes
 @cindex key sizes
 
-In TLS, since a lot of algorithms are involved, it is not easy to set a consistent security level.
-For this reason this section will present some correspondance between key sizes of symmetric algorithms
-and public key algorithms based on the most conservative values of @xcite{SELKEY}. 
-Those can be used to generate certificates with appropriate key sizes as well
-as parameters for Diffie-Hellman and SRP authentication.
+In TLS, since a lot of algorithms are involved, it is not easy to set
+a consistent security level.  For this reason this section will
+present some correspondance between key sizes of symmetric algorithms
+and public key algorithms based on the most conservative values of
+@xcite{SELKEY}.  Those can be used to generate certificates with
+appropriate key sizes as well as parameters for Diffie-Hellman and SRP
+authentication.
 
 @multitable @columnfractions .15 .20 .20 .20
 
@@ -1070,20 +1073,25 @@ as parameters for Diffie-Hellman and SRP authentication.
 @tab 3214
 @tab 244
 
-@item 2050 
+@item 2050
 @tab 109
 @tab 4047
 @tab 272
 
 @end multitable
 
-The first column provides an estimation of the year until these parameters
-are considered safe and the rest of the columns list the parameters for the
-various algorithms.
+The first column provides an estimation of the year until these
+parameters are considered safe and the rest of the columns list the
+parameters for the various algorithms.
 
-Note however that the values suggested here are nothing more than an educated
-guess that is valid today. There are no guarrantees that an algorithm will remain unbreakable or that these values will remain constant in time. There could be scientific breakthroughs that cannot be predicted or total failure of the current public key systems by quantum computers. On the other hand though the cryptosystems
-used in TLS are selected in a conservative way and such catastrophic breakthroughs or failures are believed to be unlikely.
+Note however that the values suggested here are nothing more than an
+educated guess that is valid today. There are no guarrantees that an
+algorithm will remain unbreakable or that these values will remain
+constant in time. There could be scientific breakthroughs that cannot
+be predicted or total failure of the current public key systems by
+quantum computers. On the other hand though the cryptosystems used in
+TLS are selected in a conservative way and such catastrophic
+breakthroughs or failures are believed to be unlikely.
 
 NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
 table that extends beyond the key sizes given above.
@@ -1335,9 +1343,9 @@ slower@footnote{It really depends on the group used.  Primes with
 lesser bits are always faster, but also easier to break.  Values less
 than 768 should not be used today} than plain RSA and require Diffie
 Hellman parameters to be generated and associated with a credentials
-structure, by the server.  The @code{RSA-EXPORT} method also requires 512 bit RSA
-parameters, that should also be generated and associated with the
-credentials structure.  See the functions:
+structure, by the server.  The @code{RSA-EXPORT} method also requires
+512 bit RSA parameters, that should also be generated and associated
+with the credentials structure.  See the functions:
 
 @itemize
 
@@ -1351,10 +1359,10 @@ credentials structure.  See the functions:
 
 @end itemize
 
-Sometimes in order to avoid bottlenecks in programs it is usefull to store
-and read parameters from formats that can be generated by external programs such
-as @code{certtool}. This is possible with @acronym{GnuTLS} by using the following
-functions:
+Sometimes in order to avoid bottlenecks in programs it is usefull to
+store and read parameters from formats that can be generated by
+external programs such as @code{certtool}. This is possible with
+@acronym{GnuTLS} by using the following functions:
 
 @itemize
 
@@ -1380,7 +1388,8 @@ The certificate must allow the key to be used for encryption.
 @item RSA_EXPORT:
 The RSA algorithm is used to encrypt a key and send it to the peer.
 In the EXPORT algorithm, the server signs temporary RSA parameters of
-512 bits --- which are considered weak --- and sends them to the client.
+512 bits --- which are considered weak --- and sends them to the
+client.
 
 @item DHE_RSA:
 The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters
@@ -1411,8 +1420,8 @@ do not use anonymous authentication.  Available key exchange methods
 are shown below.
 
 Note that the key exchange methods for anonymous authentication
-require Diffie-Hellman parameters to be generated by the server and associated with
-an anonymous credentials structure.
+require Diffie-Hellman parameters to be generated by the server and
+associated with an anonymous credentials structure.
 
 Supported anonymous key exchange algorithms:
 
@@ -1444,11 +1453,12 @@ protection is similar to the one used traditionally in the @emph{UNIX}
 harm to the system security if they were revealed.  The @acronym{SRP}
 needs instead of the plain password something called a verifier, which
 is calculated using the user's password, and if stolen cannot be used
-to impersonate the user. Check @xcite{TOMSRP} for a detailed description
-of the @acronym{SRP} protocol and the Stanford @acronym{SRP}
-libraries, which includes a PAM module that synchronizes the system's
-users passwords with the @acronym{SRP} password files. That way
-@acronym{SRP} authentication could be used for all the system's users.
+to impersonate the user. Check @xcite{TOMSRP} for a detailed
+description of the @acronym{SRP} protocol and the Stanford
+@acronym{SRP} libraries, which includes a PAM module that synchronizes
+the system's users passwords with the @acronym{SRP} password
+files. That way @acronym{SRP} authentication could be used for all the
+system's users.
 
 The implementation in @acronym{GnuTLS} is based on paper
 @xcite{TLSSRP}.  The supported @acronym{SRP} key exchange methods are:
@@ -1515,8 +1525,9 @@ also included.  @xref{srptool}, for more information.
 @cindex @acronym{PSK} authentication
 
 Authentication using Pre-shared keys is a method to authenticate using
-usernames and binary keys. This protocol avoids making use of public key infrastructure
-and expensive calculations, thus it is suitable for constraint clients.
+usernames and binary keys. This protocol avoids making use of public
+key infrastructure and expensive calculations, thus it is suitable for
+constraint clients.
 
 The implementation in @acronym{GnuTLS} is based on paper
 @xcite{TLSPSK}.  The supported @acronym{PSK} key exchange methods are:
@@ -1527,26 +1538,27 @@ The implementation in @acronym{GnuTLS} is based on paper
 Authentication using the @acronym{PSK} protocol.
 
 @item DHE-PSK:
-Authentication using the @acronym{PSK} protocol and Diffie-Hellman key exchange.
-This method offers perfect forward secrecy.
+Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
+exchange.  This method offers perfect forward secrecy.
 
 @end table
 
 Clients supporting @acronym{PSK} should supply the username and key
-before the connection to the client credentials by calling
-the function @ref{gnutls_psk_set_client_credentials}.
-Alternatively they could specify a callback function by using the
-function @ref{gnutls_psk_set_client_credentials_function}.
-This has the advantage that the callback will be called only if @acronym{PSK}
-has been negotiated.
+before the connection to the client credentials by calling the
+function @ref{gnutls_psk_set_client_credentials}.  Alternatively they
+could specify a callback function by using the function
+@ref{gnutls_psk_set_client_credentials_function}.  This has the
+advantage that the callback will be called only if @acronym{PSK} has
+been negotiated.
 
 In server side the default behaviour of @acronym{GnuTLS} is to read
-the usernames and @acronym{PSK} keys from a password file. The password file
-should contain usernames and keys in hexadecimal format. The name of the password
-file can be stored to the credentials structure by calling
-@ref{gnutls_psk_set_server_credentials_file}.  If a different
-password file format is to be used, then the function
-@ref{gnutls_psk_set_server_credentials_function}, should be used instead.
+the usernames and @acronym{PSK} keys from a password file. The
+password file should contain usernames and keys in hexadecimal
+format. The name of the password file can be stored to the credentials
+structure by calling @ref{gnutls_psk_set_server_credentials_file}.  If
+a different password file format is to be used, then the function
+@ref{gnutls_psk_set_server_credentials_function}, should be used
+instead.
 
 The server can help the client chose a suitable username and password,
 by sending a hint.  In the server, specify the hint by calling
@@ -1783,7 +1795,8 @@ Indicates whether this is a CA certificate or not, and specify the
 maximum path lengths of certificate chains.
 
 @item CRL distribution points (2.5.29.31):
-This extension is set by the CA, in order to inform about the issued CRLs.
+This extension is set by the CA, in order to inform about the issued
+CRLs.
 
 @item Proxy Certification Information (1.3.6.1.5.5.7.1.14):
 Proxy Certificates includes this extension that contains the OID of
@@ -1793,25 +1806,26 @@ lengths of proxy chains.  Proxy Certificates are specified in
 
 @end table
 
-In @acronym{GnuTLS} the @acronym{X.509} certificate structures are handled using
-the @code{gnutls_x509_crt_t} type and the corresponding private keys
-with the @code{gnutls_x509_privkey_t} type.  All the available
-functions for @acronym{X.509} certificate handling have their prototypes in
-@file{gnutls/x509.h}. An example program to demonstrate the @acronym{X.509}
-parsing capabilities can be found at section @ref{ex:x509-info}.
+In @acronym{GnuTLS} the @acronym{X.509} certificate structures are
+handled using the @code{gnutls_x509_crt_t} type and the corresponding
+private keys with the @code{gnutls_x509_privkey_t} type.  All the
+available functions for @acronym{X.509} certificate handling have
+their prototypes in @file{gnutls/x509.h}. An example program to
+demonstrate the @acronym{X.509} parsing capabilities can be found at
+section @ref{ex:x509-info}.
 
 @node Verifying X.509 certificate paths
 @subsection Verifying @acronym{X.509} Certificate Paths
 @cindex Verifying certificate paths
 
-Verifying certificate paths is important in @acronym{X.509} authentication. For
-this purpose the function @ref{gnutls_x509_crt_verify} is
-provided. The output of this function is the bitwise OR of the
-elements of the @code{gnutls_certificate_status_t} enumeration.  A
-detailed description of these elements can be found in figure below.
-The function @ref{gnutls_certificate_verify_peers2} is equivalent to
-the previous one, and will verify the peer's certificate in a TLS
-session.
+Verifying certificate paths is important in @acronym{X.509}
+authentication. For this purpose the function
+@ref{gnutls_x509_crt_verify} is provided. The output of this function
+is the bitwise OR of the elements of the
+@code{gnutls_certificate_status_t} enumeration.  A detailed
+description of these elements can be found in figure below.  The
+function @ref{gnutls_certificate_verify_peers2} is equivalent to the
+previous one, and will verify the peer's certificate in a TLS session.
 
 @table @code
 
@@ -1880,8 +1894,8 @@ Allow certificates to be signed using the broken MD5 algorithm.
 Although the verification of a certificate path indicates that the
 certificate is signed by trusted authority, does not reveal anything
 about the peer's identity. It is required to verify if the
-certificate's owner is the one you expect. For more information consult @xcite{RFC2818} 
-and section @ref{ex:verify} for an example.
+certificate's owner is the one you expect. For more information
+consult @xcite{RFC2818} and section @ref{ex:verify} for an example.
 
 @node PKCS #10 certificate requests
 @subsection @acronym{PKCS} #10 Certificate Requests
@@ -1965,13 +1979,13 @@ GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is
 recommended.
 
 There is one verification function in @acronym{GnuTLS}, the
-@ref{gnutls_openpgp_crt_verify_ring}.
-This checks an @acronym{OpenPGP} key against a given set of public keys (keyring) and
+@ref{gnutls_openpgp_crt_verify_ring}.  This checks an
+@acronym{OpenPGP} key against a given set of public keys (keyring) and
 returns the key status. The key verification status is the same as in
-@acronym{X.509} certificates, although the meaning and interpretation are
-different. For example an @acronym{OpenPGP} key may be valid, if the
-self signature is ok, even if no signers were found.  The meaning of
-verification status is shown in the figure below.  
+@acronym{X.509} certificates, although the meaning and interpretation
+are different. For example an @acronym{OpenPGP} key may be valid, if
+the self signature is ok, even if no signers were found.  The meaning
+of verification status is shown in the figure below.
 
 @table @code
 
@@ -1986,8 +2000,8 @@ The key has been revoked by its owner.
 The key was not signed by a known signer.
 
 @item GNUTLS_CERT_INSECURE_ALGORITHM:
-The certificate was signed using an insecure algorithm such as MD2 or MD5.
-These algorithms have been broken and should not be trusted.
+The certificate was signed using an insecure algorithm such as MD2 or
+MD5.  These algorithms have been broken and should not be trusted.
 
 @end table
 
@@ -3784,26 +3798,31 @@ certificate ciphersuite.
 
 @node TLS Authentication Methods
 @section TLS Authentication Methods
-In @acronym{GnuTLS} authentication methods can be implemented quite easily.
-Since the required changes to add a new authentication method affect only the
-handshake protocol, a simple interface is used. An authentication method needs
-only to implement the functions as seen in the figure below.
+In @acronym{GnuTLS} authentication methods can be implemented quite
+easily.  Since the required changes to add a new authentication method
+affect only the handshake protocol, a simple interface is used. An
+authentication method needs only to implement the functions as seen in
+the figure below.
 
 @image{gnutls-mod_auth_st,12cm}
 
-The functions that need to be implemented are the ones responsible for interpreting
-the handshake protocol messages. It is common for such functions to read data from
-one or more @code{credentials_t} structures@footnote{such as the @code{gnutls_certificate_credentials_t} structures} and write data, such as certificates, usernames etc. to @code{auth_info_t} structures.
+The functions that need to be implemented are the ones responsible for
+interpreting the handshake protocol messages. It is common for such
+functions to read data from one or more @code{credentials_t}
+structures@footnote{such as the
+@code{gnutls_certificate_credentials_t} structures} and write data,
+such as certificates, usernames etc. to @code{auth_info_t} structures.
 
-Simple examples of existing authentication methods can be seen in @code{auth_psk.c}
-for PSK ciphersuites and @code{auth_srp.c} for SRP ciphersuites. After implementing these functions
-the structure holding its pointers has to be registered in @code{gnutls_algorithms.c}
-in the @code{_gnutls_kx_algorithms} structure.
+Simple examples of existing authentication methods can be seen in
+@code{auth_psk.c} for PSK ciphersuites and @code{auth_srp.c} for SRP
+ciphersuites. After implementing these functions the structure holding
+its pointers has to be registered in @code{gnutls_algorithms.c} in the
+@code{_gnutls_kx_algorithms} structure.
 
 @node TLS Extension Handling
 @section TLS Extension Handling
-As with authentication methods, the TLS extensions handlers can be implemented
-using the following interface.
+As with authentication methods, the TLS extensions handlers can be
+implemented using the following interface.
 
 @image{gnutls-extensions_st,12cm}
 
@@ -3811,10 +3830,10 @@ Here there are two functions, one for receiving the extension data
 and one for sending. These functions have to check internally whether
 they operate in client or server side. 
 
-A simple example of an extension handler can be seen in @code{ext_srp.c}
-After implementing these functions, together with the extension number they
-handle, they have to be registered in @code{gnutls_extensions.c} in the 
-@code{_gnutls_extensions} structure.
+A simple example of an extension handler can be seen in
+@code{ext_srp.c} After implementing these functions, together with the
+extension number they handle, they have to be registered in
+@code{gnutls_extensions.c} in the @code{_gnutls_extensions} structure.
 
 @subsection Adding a New TLS Extension
 
@@ -3996,17 +4015,19 @@ is summarized in the following diagram.
 
 @node Cryptographic Backend
 @section Cryptographic Backend
-Several new systems provide hardware assisted cryptographic algorithm implementations
-that offer implementations some orders of magnitude faster than the software. For this
-reason in current releases of GnuTLS it is possible to override parts of the crypto
-backend or the whole. It is possible to override them both at runtime and compile time, however
-here we will discuss the runtime possibility. The API available for this functionality
-is in @code{gnutls/crypto.h} header file.
+Several new systems provide hardware assisted cryptographic algorithm
+implementations that offer implementations some orders of magnitude
+faster than the software. For this reason in current releases of
+GnuTLS it is possible to override parts of the crypto backend or the
+whole. It is possible to override them both at runtime and compile
+time, however here we will discuss the runtime possibility. The API
+available for this functionality is in @code{gnutls/crypto.h} header
+file.
 
 @subsection Override specific algorithms
-When an optimized implementation of a single algorithm is available, say a
-hardware assisted version of @acronym{AES-CBC} then the following functions
-can be used to register those algorithms.
+When an optimized implementation of a single algorithm is available,
+say a hardware assisted version of @acronym{AES-CBC} then the
+following functions can be used to register those algorithms.
 
 @itemize
 
@@ -4021,13 +4042,13 @@ To register a digest (hash) algorithm.
 
 @end itemize
 
-Those registration functions will only replace the specified algorithm and leave the
-rest of subsystem intact.
+Those registration functions will only replace the specified algorithm
+and leave the rest of subsystem intact.
 
 @subsection Override parts of the backend
-In some systems, such as embedded ones, it might be desirable to override big parts
-of the cryptographic backend, or even all of them. For this reason the following
-functions are provided.
+In some systems, such as embedded ones, it might be desirable to
+override big parts of the cryptographic backend, or even all of
+them. For this reason the following functions are provided.
 
 @itemize
 
@@ -4047,9 +4068,9 @@ To override the random number generator backend.
 To override the big number number operations backend.
 
 @item @ref{gnutls_crypto_pk_register2}
-To override the public key encryption backend. This is tight to the big number
-operations so either both of them should be updated or care must be taken to
-use the same format.
+To override the public key encryption backend. This is tight to the
+big number operations so either both of them should be updated or care
+must be taken to use the same format.
 
 @end itemize