Make a few formatting fixes:

- Remove unnecessary .Ar macros.
- Change "https" to "HTTPS" to be consistent with other man pages.
- Add "(CSR)" to the first instance of "Certificate Signing Request."
- Convert one .Ar to .Em in the HISTORY section since the intent of that
  .Ar was to emphasize a point.
- Fix the punctuation in one sentence.

feedback/ok jmc

1 files changed, 55 insertions, 126 deletions

diff --git a/share/man/man8/ssl.8 b/share/man/man8/ssl.8
index 003ca7e89b6..7fdd89187dc 100644
--- a/share/man/man8/ssl.8
+++ b/share/man/man8/ssl.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ssl.8,v 1.51 2012/06/19 02:34:53 lteo Exp $
+.\"	$OpenBSD: ssl.8,v 1.52 2012/11/06 04:16:10 lteo Exp $
 .\"
 .\" Copyright (c) 1999 Theo de Raadt, Bob Beck
 .\" All rights reserved.
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 19 2012 $
+.Dd $Mdocdate: November 6 2012 $
 .Dt SSL 8
 .Os
 .Sh NAME
@@ -35,19 +35,10 @@ the OpenSSL libssl and libcrypto libraries.
 This document is intended as an overview of what the libraries do,
 and what uses them.
 .Pp
-The SSL libraries (libssl and libcrypto) implement the
-.Ar SSL version 2 ,
-.Ar SSL version 3 ,
-and
-.Ar TLS version 1
-protocols.
-.Ar SSL version 2
-and
-.Ar 3
-are most
-commonly used by the
-.Ar https
-protocol for encrypted web transactions, as can be done with
+The SSL libraries (libssl and libcrypto) implement the SSL version 2,
+SSL version 3, and TLS version 1 protocols.
+SSL version 2 and 3 are most commonly used by the HTTPS protocol for
+encrypted web transactions, as can be done with
 .Xr httpd 8 .
 The libcrypto library is also used by various programs such as
 .Xr ssh 1 ,
@@ -63,9 +54,8 @@ libcrypto and libssl.
 If the
 .Xr arandom 4
 device does not exist or is not readable, many of the routines will fail.
-This is most commonly seen by users as the
-.Ar RSA
-routines failing in applications such as
+This is most commonly seen by users as the RSA routines failing in
+applications such as
 .Xr ssh 1
 and
 .Xr httpd 8 .
@@ -83,32 +73,25 @@ See
 .Xr openssl 1
 for more information on how to use different sources of random data.
 .Sh SERVER CERTIFICATES
-The most common uses of
-.Ar SSL/TLS
-will require you to generate a server certificate, which is provided by your
-host as evidence of its identity when clients make new connections.
+The most common uses of SSL/TLS will require you to generate a server
+certificate, which is provided by your host as evidence of its identity
+when clients make new connections.
 The certificates reside in the
 .Pa /etc/ssl
 directory, with the keys in the
 .Pa /etc/ssl/private
 directory.
 .Pp
-Private keys can be encrypted using
-.Ar AES
-and a passphrase to protect their integrity should the encrypted file
-be disclosed.
+Private keys can be encrypted using AES and a passphrase to protect their
+integrity should the encrypted file be disclosed.
 However, it is important to note that encrypted server keys mean that the
 passphrase needs to be typed in every time the server is started.
 If a passphrase is not used, you will need to be absolutely sure your
 key file is kept secure.
 .Sh GENERATING RSA SERVER CERTIFICATES FOR WEB SERVERS
-To support
-.Ar https
-transactions in
+To support HTTPS transactions in
 .Xr httpd 8
-you will need to generate an
-.Ar RSA
-certificate.
+you will need to generate an RSA certificate.
 .Bd -literal -offset indent
 # openssl genrsa -out /etc/ssl/private/server.key 2048
 .Ed
@@ -119,12 +102,8 @@ have to type in when starting servers
 # openssl genrsa -aes256 -out /etc/ssl/private/server.key 2048
 .Ed
 .Pp
-The next step is to generate a
-.Ar Certificate Signing Request
-which is used
-to get a
-.Ar Certificate Authority (CA)
-to sign your certificate.
+The next step is to generate a Certificate Signing Request (CSR) which is
+used to get a Certificate Authority (CA) to sign your certificate.
 To do this use the command:
 .Bd -literal -offset indent
 # openssl req -new -key /etc/ssl/private/server.key \e
@@ -133,9 +112,7 @@ To do this use the command:
 .Pp
 This
 .Pa server.csr
-file can then be given to a
-.Ar Certificate Authority
-who will sign the key.
+file can then be given to a Certificate Authority who will sign the key.
 .Pp
 You can also sign the key yourself, using the command:
 .Bd -literal -offset indent
@@ -153,9 +130,7 @@ in place, you should be able to start
 .Xr httpd 8
 with the
 .Ar -DSSL
-flag, enabling
-.Ar https
-transactions with your machine on port 443.
+flag, enabling HTTPS transactions with your machine on port 443.
 .Pp
 You will most likely want to generate a self-signed certificate in the
 manner above along with your certificate signing request to test your
@@ -168,20 +143,14 @@ with the certificate signed by your Certificate Authority, and then
 restarting
 .Xr httpd 8 .
 .Sh GENERATING DSA SERVER CERTIFICATES
-Generating a
-.Ar DSA
-certificate involves several steps.
-First, generate parameters for
-.Ar DSA
-keys.
+Generating a DSA certificate involves several steps.
+First, generate parameters for DSA keys.
 The following command will generate 1024-bit keys:
 .Bd -literal -offset indent
 # openssl dsaparam 1024 -out dsa1024.pem
 .Ed
 .Pp
-Once you have the
-.Ar DSA
-parameters generated, you can generate a certificate
+Once you have the DSA parameters generated, you can generate a certificate
 and unencrypted private key using the command:
 .Bd -literal -offset indent
 # openssl req -x509 -nodes -newkey dsa:dsa1024.pem \e
@@ -206,8 +175,7 @@ See
 .Xr starttls 8
 for information on configuring
 .Xr sendmail 8
-to use
-.Ar SSL/TLS .
+to use SSL/TLS.
 .Sh SEE ALSO
 .Xr openssl 1 ,
 .Xr ssh 1 ,
@@ -223,81 +191,48 @@ to use
 Prior to Sept 21, 2000,
 there were problems shipping fully functional implementations of these
 protocols, as such shipment would include shipping
-.Ar into
+.Em into
 the United States.
-.Ar RSA Data Security Inc (RSADSI)
-held the patent on the
-.Ar RSA
-algorithm in the United States, and because of this, free
-implementations of
-.Ar RSA
-were difficult to distribute and propagate.
-(The
-.Ar RSA
-patent was probably more effective at preventing the adoption of
-widespread international integrated crypto than the much maligned
-ITAR restrictions were).
+RSA Data Security Inc (RSADSI) held the patent on the RSA algorithm in the
+United States, and because of this, free implementations of RSA were
+difficult to distribute and propagate.
+(The RSA patent was probably more effective at preventing the adoption of
+widespread international integrated crypto than the much maligned ITAR
+restrictions were.)
 Prior to
 .Ox 2.8 ,
-these libraries shipped without the
-.Ar RSA
-algorithm -- all such functions
+these libraries shipped without the RSA algorithm -- all such functions
 were stubbed to fail.
-Since
-.Ar RSA
-is a key component of
-.Ar SSL version 2 ,
-this
-meant that
-.Ar SSL version 2
-would not work at all.
-.Ar SSL version 3
-and
-.Ar TLS version 1
-allow for the exchange of keys via mechanisms that do not
-involve
-.Ar RSA ,
-and would work with the shipped version of the libraries,
-assuming both ends could agree to a cipher suite and key exchange that
-did not involve RSA.
+Since RSA is a key component of SSL version 2, this meant that SSL version
+2 would not work at all.
+SSL version 3 and TLS version 1 allow for the exchange of keys via
+mechanisms that do not involve RSA, and would work with the shipped version
+of the libraries, assuming both ends could agree to a cipher suite and key
+exchange that did not involve RSA.
 Likewise, the SSH1 protocol in
 .Xr ssh 1
 uses RSA, so it was similarly encumbered.
 .Pp
-For instance, another typical alternative is
-.Ar DSA ,
-which is not encumbered by commercial patents (and lawyers).
+For instance, another typical alternative is DSA, which is not encumbered
+by commercial patents (and lawyers).
 .Pp
-The
-.Ar https
-protocol used by web browsers (in modern incarnations)
-allows for the use of
-.Ar SSL version 3
-and
-.Ar TLS version 1 ,
-which in theory allows for encrypted web transactions without using
-.Ar RSA .
-Unfortunately, all the popular web browsers
-buy their cryptographic code from
-.Ar RSADSI .
-Predictably,
-.Ar RSADSI
-would prefer that web browsers used their patented algorithm, and thus
-their libraries do not implement any
-.Ar non-RSA
-cipher and keying combination.
-The result of this was that while the
-.Ar https
-protocol allowed for many cipher suites that did not require the use
-of patented algorithms, it was very difficult to use these with the
-popular commercially available software.
+The HTTPS protocol used by web browsers (in modern incarnations) allows for
+the use of SSL version 3 and TLS version 1, which in theory allows for
+encrypted web transactions without using RSA.
+Unfortunately, all the popular web browsers buy their cryptographic code
+from RSADSI.
+Predictably, RSADSI would prefer that web browsers used their patented
+algorithm, and thus their libraries do not implement any non-RSA cipher and
+keying combination.
+The result of this was that while the HTTPS protocol allowed for many
+cipher suites that did not require the use of patented algorithms, it was
+very difficult to use these with the popular commercially available
+software.
 Prior to version 2.8,
 .Ox
-allowed users to download
-.Ar RSA
-enabled versions of the shared libssl and libcrypto libraries
-which allowed users to enable full function without recompiling
-the applications.
+allowed users to download RSA enabled versions of the shared libssl and
+libcrypto libraries which allowed users to enable full function without
+recompiling the applications.
 This method is now no longer needed, as the fully functional
 libraries ship with the system.
 However, this entire debacle is worth remembering when choosing
@@ -306,10 +241,4 @@ software and vendors.
 This document first appeared in
 .Ox 2.5 .
 .Sh BUGS
-The world needs more
-.Ar DSA
-capable
-.Ar SSL
-and
-.Ar SSH
-services.
+The world needs more DSA capable SSL and SSH services.