Cleaning up some awkward phrasings.

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

5 files changed, 28 insertions, 27 deletions

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
index 4079985307..da1a1141f5 100644
--- a/doc/cha-auth.texi
+++ b/doc/cha-auth.texi
@@ -33,7 +33,7 @@ methods in @acronym{GnuTLS} in various scenarios.
 
 @subsection Two peers with an out-of-band channel
 
-Let's consider two peers need to communicate over an untrusted channel
+Let's consider two peers who need to communicate over an untrusted channel
 (the Internet), but have an out-of-band channel available. The latter
 channel is considered safe from eavesdropping and message modification and thus
 can be used for an initial bootstrapping of the protocol. The options 
@@ -44,7 +44,7 @@ client communicate a shared randomly generated key over the trusted
 channel and use it to negotiate further sessions over the untrusted channel.
 
 @item Passwords (see @ref{SRP authentication}). The client communicates
-to the server his username and password of choice and uses it to
+to the server its username and password of choice and uses it to
 negotiate further sessions over the untrusted channel.
 
 @item Public keys (see @ref{Certificate authentication}). The client 
@@ -101,7 +101,7 @@ the client provided over the initial server-authenticated channel. The
 available options are:
 @itemize
 @item Passwords (see @ref{SRP authentication}). The client communicates
-to the server his username and password of choice on the initial
+to the server its username and password of choice on the initial
 server-authenticated connection and uses it to negotiate further sessions. 
 This is possible because the SRP protocol allows for the server to be 
 authenticated using a certificate and the client using the
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index ac0def0100..10a74776b7 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -654,7 +654,7 @@ used to preprocess the input to the signature algorithm. This works as
 long as it is difficult enough to generate two different messages with
 the same hash algorithm output. In that case the same signature could
 be used as a proof for both messages. Nobody wants to sign an innocent
-message of donating 1 euro to Greenpeace and find out that he
+message of donating 1 euro to Greenpeace and find out that they
 donated 1.000.000 euros to Bad Inc.
 
 For a hash algorithm to be called cryptographic the following three
diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index a6482a8a4c..e3708ba064 100644
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -146,14 +146,14 @@ revocation checking, however, several problems with CRLs have been
 identified @xcite{RIVESTCRL}.
 
 The Online Certificate Status Protocol, or @acronym{OCSP} @xcite{RFC2560}, 
-is a widely implemented protocol to perform certificate revocation status
+is a widely implemented protocol which performs certificate revocation status
 checking.  An application that wish to verify the
 identity of a peer will verify the certificate against a set of
 trusted certificates and then check whether the certificate is listed
 in a CRL and/or perform an OCSP check for the certificate.
 
 Note that in the context of a TLS session the server may provide an
-OCSP response that will used during the TLS certificate verification 
+OCSP response that will be used during the TLS certificate verification
 (see @funcref{gnutls_certificate_verify_peers2}).
 You may obtain this response using @funcref{gnutls_ocsp_status_request_get}.
 
@@ -169,8 +169,8 @@ extracts this information from a certificate.
 
 There are several functions in GnuTLS for creating and manipulating
 OCSP requests and responses.  The general idea is that a client
-application create an OCSP request object, store some information
-about the certificate to check in the request, and then export the
+application creates an OCSP request object, stores some information
+about the certificate to check in the request, and then exports the
 request in DER format.  The request will then need to be sent to the
 OCSP responder, which needs to be done by the application (GnuTLS does
 not send and receive OCSP packets).  Normally an OCSP response is
diff --git a/doc/cha-errors.texi b/doc/cha-errors.texi
index 0948d0552d..1154c01236 100644
--- a/doc/cha-errors.texi
+++ b/doc/cha-errors.texi
@@ -3,7 +3,7 @@
 @cindex error codes
 
 The error codes used throughout the library are described below.  The
-return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and
+return code @code{GNUTLS_E_SUCCESS} indicates a successful operation, and
 is guaranteed to have the value 0, so you can use it in logical
 expressions.
 
diff --git a/doc/sec-tls-app.texi b/doc/sec-tls-app.texi
index 89a10e7039..a67207dde3 100644
--- a/doc/sec-tls-app.texi
+++ b/doc/sec-tls-app.texi
@@ -1,7 +1,7 @@
 @node How to use TLS in application protocols
 @section How to use @acronym{TLS} in application protocols
 
-This chapter is intended to provide some hints on how to use the
+This chapter is intended to provide some hints on how to use
 @acronym{TLS} over simple custom made application protocols.  The
 discussion below mainly refers to the @acronym{TCP/IP} transport layer
 but may be extended to other ones too.
@@ -15,15 +15,15 @@ but may be extended to other ones too.
 @subsection Separate ports
 
 Traditionally @acronym{SSL} was used in application protocols by
-assigning a new port number for the secure services. That way two
-separate ports were assigned, one for the non secure sessions, and one
-for the secured ones. This has the benefit that if a user requests a
-secure session then the client will try to connect to the secure port
-and fail otherwise. The only possible attack with this method is a
-denial of service one. The most famous example of this method is the
-famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @xcite{RFC2818}.
-
-Despite its wide use, this method is not as good as it seems.  This
+assigning a new port number for the secure services. By doing this two
+separate ports were assigned, one for the non-secure sessions, and one
+for the secure sessions. This method ensures that if a user requests a
+secure session then the client will attempt to connect to the secure port
+and fail otherwise. The only possible attack with this method is to perform
+a denial of service attack. The most famous example of this method is
+``HTTP over TLS'' or @acronym{HTTPS} protocol @xcite{RFC2818}.
+
+Despite its wide use, this method has several issues. This
 approach starts the @acronym{TLS} Handshake procedure just after the
 client connects on the ---so called--- secure port.  That way the
 @acronym{TLS} protocol does not know anything about the client, and
@@ -36,7 +36,7 @@ cannot possibly know which certificate to use.
 Other than that it requires two separate ports to run a single
 service, which is unnecessary complication. Due to the fact that there
 is a limitation on the available privileged ports, this approach was
-soon obsoleted.
+soon deprecated in favor of upward negotiation.
 
 @node Upward negotiation
 @subsection Upward negotiation
@@ -49,7 +49,7 @@ have a ``STARTTLS'' request, whose purpose it to start the TLS
 protocols just after the client requests it.  This approach
 does not require any extra port to be reserved.
 There is even an extension to HTTP protocol to support 
-that method @xcite{RFC2817}.
+this method @xcite{RFC2817}.
 
 The tricky part, in this method, is that the ``STARTTLS'' request is
 sent in the clear, thus is vulnerable to modifications.  A typical
@@ -73,7 +73,7 @@ SERVER: OK
 CLIENT: HERE ARE SOME CONFIDENTIAL DATA
 @end quotation
 
-And see an example of a conversation where someone is acting
+And an example of a conversation where someone is acting
 in between:
 
 @quotation
@@ -92,12 +92,13 @@ SERVER: SORRY I DON'T HAVE THIS CAPABILITY
 CLIENT: HERE ARE SOME CONFIDENTIAL DATA
 @end quotation
 
-As you can see above the client was fooled, and was dummy enough to
-send the confidential data in the clear.
+As you can see above the client was fooled, and was na@"ive enough to
+send the confidential data in the clear, despite the server telling the
+client that it does not support ``STARTTLS''.
 
-How to avoid the above attack? As you may have already noticed this
-one is easy to avoid. The client has to ask the user before it
-connects whether the user requests @acronym{TLS} or not. If the user
+How do we avoid the above attack? As you may have already noticed this
+situation is easy to avoid.  The client has to ask the user before it
+connects whether the user requests @acronym{TLS} or not.  If the user
 answered that he certainly wants the secure layer the last
 conversation should be: