manual.texi begin to clean up the SSL section

Docs/manual.texi

@@ -1760,8 +1760,8 @@ applications. Using the embedded MySQL server library, one can
 embed MySQL Server into various applications and electronics devices, where
 the end user has no knowledge of there actually being an underlying
 database. Embedded MySQL Server is ideal for use behind
-the scenes in internet appliances, public kiosks, turnkey
-hardware/software combination units, high performance internet
+the scenes in Internet appliances, public kiosks, turnkey
+hardware/software combination units, high performance Internet
 servers, self-contained databases distributed on CD-ROM, etc.
 
 Many users of @code{libmysqld} will benefit from the MySQL
@@ -17403,51 +17403,52 @@ file.
 @node Secure basics, Secure requirements, Secure connections, Secure connections
 @subsubsection Basics
 
+Beginning with version 4.0.0,
 MySQL has support for SSL encrypted connections. To understand how MySQL
-uses SSL, we need to explain some basics about SSL and X509. People who
-are already aware of it can skip this part.
+uses SSL, it's necessary to explain some basic SSL and X509 concepts. People
+who are already familiar with them can skip this part.
 
-By default, MySQL uses unencrypted connections between client and
+By default, MySQL uses unencrypted connections between the client and the
 server. This means that someone could watch all your traffic and look at
-the data being sent/received.  Actually, they could even change the data
+the data being sent or received.  They could even change the data
 while it is in transit between client and server. Sometimes you need to
-move really secret data over public networks and in such a case using an
-unencrypted connection is unacceptable.
+move information over public networks in a secure fashion; in such cases,
+using an unencrypted connection is unacceptable.
 
-SSL is a protocol which uses different encryption algorithms to ensure
-that data which comes from public network can be trusted. It has
+SSL is a protocol that uses different encryption algorithms to ensure
+that data received over a public network can be trusted. It has
 mechanisms to detect any change, loss or replay of data. SSL also
-incorpores algorithms to recognise and provide identity verification
+incorporates algorithms to recognise and provide identity verification
 using the X509 standard.
 
 @cindex What is encryption
 Encryption is the way to make any kind of data unreadable. In fact,
 today's practice requires many additional security elements from
 encryption algorithms.  They should resist many kind of known attacks
-like just messing with order of encrypted messages or replaying data
+like just messing with the order of encrypted messages or replaying data
 twice.
 
 @cindex What is X509/Certificate?
-X509 is a standard that makes it possible to identify someone in the
+X509 is a standard that makes it possible to identify someone on the
 Internet.  It is most commonly used in e-commerce applications. In basic
-terms, there should be some company called "Certificate Authority" which
+terms, there should be some company (called a ``Certificate Authority'') that
 assigns electronic certificates to anyone who needs them. Certificates
-rely on asymmetric encryption algorithms which have two encryption keys
-- public and secret. A certificate owner can prove his identity by
-showing his certificate to other party. A certificate consists of his
-owner's public key. Any data encrypted with this public key can only be
-decrypted using the corresponding secret key, which is held by the owner
+rely on asymmetric encryption algorithms that have two encryption keys
+(a public key and a secret key). A certificate owner can prove his identity by
+showing his certificate to other party. A certificate consists of its
+owner's public key. Any data encrypted with this public key can be
+decrypted only using the corresponding secret key, which is held by the owner
 of the certificate.
 
-MySQL doesn't use encrypted on connections by default, because this
+MySQL doesn't use encrypted connections by default, because doing so
 would make the client/server protocol much slower. Any kind of
-additional functionality requires computer to do additional work and
-encrypting data is CPU-intensive operation require time and can delay
+additional functionality requires the computer to do additional work and
+encrypting data is a CPU-intensive operation that requires time and can delay
 MySQL main tasks. By default MySQL is tuned to be fast as possible.
 
-If you need more information about SSL/X509/encryption, you should use
-your favourite internet search engine and search for keywords you are
-interested in.
+If you need more information about SSL, X509, or encryption, you should use
+your favourite Internet search engine and search for keywords in which you are
+interested.
 
 @node Secure requirements, Secure GRANT, Secure basics, Secure connections
 @subsubsection Requirements
@@ -17462,10 +17463,12 @@ Install the OpenSSL library. We have tested MySQL with OpenSSL 0.9.6.
 Configure MySQL with @code{--with-vio --with-openssl}.
 @item
 If you are using an old MySQL installation, you have to update your
-@code{mysql.user} table with some new columns. You can do this by
+@code{mysql.user} table with some new SSL-related columns. You can do this by
 running the @code{mysql_fix_privilege_tables.sh} script.
+This is necessary if your grant tables date from a version prior to MySQL
+4.0.0.
 @item
-You can check if a running mysqld server supports OpenSSL by
+You can check if a running @code{mysqld} server supports OpenSSL by
 examining if @code{SHOW VARIABLES LIKE 'have_openssl'} returns @code{YES}.
 @end enumerate
 
@@ -17485,8 +17488,8 @@ There are different possibilities to limit connections:
 
 @itemize @bullet
 @item
-Without any SSL/X509 options, all kind of encrypted/unencrypted
-connections are allowed if username and password are valid.
+Without any SSL or X509 options, all kind of encrypted/unencrypted
+connections are allowed if the username and password are valid.
 
 @item
 @code{REQUIRE SSL} option limits the server to allow only SSL
@@ -17499,7 +17502,7 @@ mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
 @end example
 
 @item
-@code{REQUIRE X509} means that client should have valid certificate
+@code{REQUIRE X509} means that the client should have a valid certificate
 but we do not care about the exact certificate, issuer or subject.
 The only restriction is that it should be possible to verify its
 signature with one of the CA certificates.
@@ -17510,10 +17513,10 @@ mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
 @end example
 
 @item
-@code{REQUIRE ISSUER issuer} makes connection more restrictive: now
-client must present a valid X509 certificate issued by CA "issuer".
-Using X509 certificates always implies encryption, so the option "SSL"
-is not neccessary anymore.
+@code{REQUIRE ISSUER "issuer"} places a restriction on connection attempts:
+The client must present a valid X509 certificate issued by CA @code{"issuer"}.
+Using X509 certificates always implies encryption, so the @code{SSL} option
+is unneccessary.
 
 @example
 mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
@@ -17523,10 +17526,10 @@ mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
 @end example
 
 @item
-@code{REQUIRE SUBJECT subject} requires clients to have valid X509
-certificate with subject "subject" on it. If client have valid
-certificate but having different "subject" then the connection is
-still not allowed.
+@code{REQUIRE SUBJECT "subject"} requires clients to have valid X509
+certificate with subject @code{"subject"} on it. If the client presents a
+certificate that is valid but has a different @code{"subject"}, the connection
+is disallowed.
 
 @example
 mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
@@ -17537,7 +17540,7 @@ mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
 @end example
 
 @item
-@code{REQUIRE CIPHER cipher} is needed to assure enough strong ciphers
+@code{REQUIRE CIPHER "cipher"} is needed to assure enough strong ciphers
 and keylengths will be used. SSL itself can be weak if old algorithms
 with short encryption keys are used. Using this option, we can ask for
 some exact cipher method to allow a connection.
@@ -17548,7 +17551,8 @@ mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
     -> REQUIRE CIPHER "EDH-RSA-DES-CBC3-SHA";
 @end example
 
-Also it is allowed to combine these options with each other like this:
+The @code{SUBJECT}, @code{ISSUER}, and @code{CIPHER} options can be
+combined in the @code{REQUIRE} clause like this:
 
 @example
 mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
@@ -17561,8 +17565,8 @@ mysql> GRANT ALL PRIVILEGES ON test.* TO root@@localhost
     -> AND CIPHER "EDH-RSA-DES-CBC3-SHA";
 @end example
 
-But it is not allowed to use any option twice. Only different
-options can be mixed.
+The order of the options does not matter, but no option can be specified
+twice.
 @end itemize