Finish editorial review of OpenSSL chapter.

Update instructions and examples.

Sponsored by:	iXsystems

en_US.ISO8859-1/books/handbook/security/chapter.xml

@@ -1781,17 +1781,6 @@ kadmind5_server_enable="YES"</programlisting>
       and Transport Layer Security v1 (TLSv1) network security
       protocols and can be used as a general cryptographic
       library.</para>
-<!--
-This patent expired in 2012, is the note still needed?
-    <note>
-      <para>While <application>OpenSSL</application> supports the
-	<acronym>IDEA</acronym> algorithm, it is disabled by default
-	due to United States patents.  To use it, the license should
-	be reviewed and, if the restrictions are acceptable, the
-	<varname>MAKE_IDEA</varname> variable must be set in
-	<filename>/etc/make.conf</filename>.</para>
-    </note>
-    -->
 
     <para><application>OpenSSL</application> is often used to encrypt
       authentication of mail clients and to secure web based
@@ -1833,8 +1822,15 @@ This patent expired in 2012, is the note still needed?
 	<secondary>certificate generation</secondary>
       </indexterm>
 
-      <para>To generate a certificate, the following command is
+      <para>To generate a certificate that will be signed by an
-	available:</para>
+	external <acronym>CA</acronym>, issue the following command and
+	input the information requested at the prompts.  This input
+	information will be written to the certificate.  At the
+	<literal>Common Name</literal> prompt, input the fully
+	qualified name for the system that will use the certificate.
+	If this name does not match the server, the application verifying the
+	certificate will issue a warning to the user, rendering the
+	verification provided by the certificate as useless.</para>
 
       <screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput>
 Generating a 1024 bit RSA private key
@@ -1861,100 +1857,120 @@ Please enter the following 'extra' attributes
 to be sent with your certificate request
 A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput>
 An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen>
-
+	
-      <para>Notice the response directly after the <quote>Common
+      <para>Other options, such as the expire
-	  Name</quote> prompt shows a domain name.  This prompt
+	time and alternate encryption algorithms, are available when
-	requires a server name to be entered for verification
+	creating a certificate.  A
-	purposes and placing anything but a domain name yields a
-	useless certificate.  Other options, such as the expire
-	time and alternate encryption algorithms, are available.  A
 	complete list of options is described in
 	&man.openssl.1;.</para>
 
-      <para>Two files should now exist in the directory in which this
+      <para>This command will create two files in the current directory.
-	command was issued.  The certificate request,
+	The certificate request,
-	<filename>req.pem</filename>, may be sent to a
+	<filename>req.pem</filename>, can be sent to a
 	<acronym>CA</acronym> who will validate the entered
 	credentials, sign the request, and return the signed
-	certificate.  The second file is named
+	certificate.  The second file,
-	<filename>cert.pem</filename> and is the private key for the
+	<filename>cert.pem</filename>, is the private key for the
-	certificate and should be protected at all costs.  If this
+	certificate and should be stored in a secure location.  If this
-	falls in the hands of others it can be used to impersonate
+	falls in the hands of others, it can be used to impersonate
 	the user or the server.</para>
 
-      <para>In cases where a signature from a <acronym>CA</acronym>
+      <para>Alternately, if a signature from a <acronym>CA</acronym>
-	is not required, a self signed certificate can be created.
+	is not required, a self-signed certificate can be created.
 	First, generate the <acronym>RSA</acronym> key:</para>
 
-      <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out myRSA.key 1024</userinput></screen>
+      <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out myRSA.key 1024</userinput>
+0 semi-random bytes loaded
+Generating DSA parameters, 1024 bit long prime
+This could take some time
+.............+........+...........+...+....+........+.....+++++++++++++++++++++++++++++++++++++++++++++++++++*
+..........+.+...........+....+........+.................+.+++++++++++++++++++++++++++++++++++++++++++++++++++*</screen>
 
-      <para>Next, generate the <acronym>CA</acronym> key:</para>
+      <para>Next, generate the <acronym>CA</acronym> key.  When
+	prompted, enter a passphrase between 4 to 1023 characters.
+	Remember this passphrase as it is needed whenever the key is
+	used to sign a certificate.</para>
 
-      <screen>&prompt.root; <userinput>openssl gendsa -des3 -out myca.key myRSA.key</userinput></screen>
+      <screen>&prompt.root; <userinput>openssl gendsa -des3 -out myca.key myRSA.key</userinput>
+Generating DSA key, 1024 bits
+Enter PEM pass phrase:
+Verifying - Enter PEM pass phrase:</screen>
 
-      <para>Use this key to create the certificate:</para>
+      <para>Use this key to create a self-signed certificate.  When
+	prompted, enter the passphrase.  Then follow the usual prompts
+	for creating a certificate:</para>
 
-      <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key myca.key -out new.crt</userinput></screen>
+      <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key myca.key -out new.crt</userinput>
+Enter pass phrase for myca.key:
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput>
+State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput>
+Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput>
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput>
+Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput>
+Common Name (e.g. server FQDN or YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput>
+Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput></screen>
 
-      <para>Two new files should appear in the directory: a
+      <para>This will create two new files in the current directory: a
 	certificate authority signature file,
-	<filename>myca.key</filename> and the certificate itself,
+	<filename>myca.key</filename>, and the certificate itself,
 	<filename>new.crt</filename>.  These should be placed in a
 	directory, preferably under <filename>/etc</filename>, which
 	is readable only by <systemitem
-	  class="username">root</systemitem>.  Permissions of 0700 are
+	  class="username">root</systemitem>.  Permissions of <literal>0700</literal> are
-	appropriate and can be set using &man.chmod.1;.</para>
+	appropriate for these files and can be set using <command>chmod</command>.</para>
     </sect2>
 
     <sect2>
       <title>Using Certificates</title>
 
       <para>One use for a certificate is to encrypt connections to the
-	<application>Sendmail</application> <acronym>MTA</acronym>.
+	<application>Sendmail</application> mail server in order to
-	This prevents the use of clear text authentication for users
+	prevent the use of clear text authentication.</para>
-	who send mail via the local <acronym>MTA</acronym>.</para>
 
       <note>
-	<para>Some <acronym>MUA</acronym>s will display error if the
+	<para>Some mail clients will display an error if the
-	  user has not installed the certificate locally.  Refer to
+	  user has not installed a local copy of the certificate.  Refer to
 	  the documentation included with the software for more
 	  information on certificate installation.</para>
       </note>
 
-      <para>To configure <application>Sendmail</application>, the
+      <para>To configure <application>Sendmail</application>, add the
-	following lines should be placed in the local
+	following lines to
-	<filename>.mc</filename> file:</para>
+	<filename>/etc/rc.conf</filename>:</para>
 
-      <programlisting>dnl SSL Options
+      <programlisting>sendmail_enable="YES"
-define(`confCACERT_PATH',`/etc/certs')dnl
+sendmail_cert_create="YES"
-define(`confCACERT',`/etc/certs/new.crt')dnl
+sendmail_cert_cn="<replaceable>localhost.example.org</replaceable>"</programlisting>
-define(`confSERVER_CERT',`/etc/certs/new.crt')dnl
-define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
-define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>
 
-      <para>In this example,  <filename>/etc/certs/</filename>
+      <para>This will automatically create a self-signed certificate,
-	stores the certificate and key files locally.  After saving
+	<filename>/etc/mail/certs/host.cert</filename>, a signing key,
-	the edits, rebuild the local <filename>.cf</filename> file by
+	<filename>/etc/mail/certs/host.key</filename>, and a
-	typing
+	<acronym>CA</acronym> certificate,
-	<command>make install</command>
+	<filename>/etc/mail/certs/cacert.pem</filename>.  The
-	within <filename>/etc/mail</filename>.
+	certificate will use the <literal>Common Name</literal>
-	Follow that up with <command>make
+	specified in <option>sendmail_cert_cn</option>.
-	  restart</command> which should
+	After saving
-	start the <application>Sendmail</application> daemon.</para>
+	the edits, restart <application>Sendmail</application>:</para>
+
+      <screen>&prompt.root; <userinput>service sendmail restart</userinput></screen>
 
       <para>If all went well, there will be no error messages in
-	<filename>/var/log/maillog</filename> and
+	<filename>/var/log/maillog</filename>.  For a simple test,
-	<application>Sendmail</application> will show up in the
+	connect to the mail server's listening port using
-	process list.</para>
+	<command>telnet</command>:</para>
-
-      <para>For a simple test, connect to the mail server using
-	&man.telnet.1;:</para>
 
       <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput>
 Trying 192.0.34.166...
-Connected to <systemitem class="fqdomainname">example.com</systemitem>.
+Connected to example.com.
 Escape character is '^]'.
-220 <systemitem class="fqdomainname">example.com</systemitem> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT)
+220 example.com ESMTP Sendmail 8.14.7/8.14.7; Fri, 18 Apr 2014 11:50:32 -0400 (EDT)
 <userinput>ehlo <replaceable>example.com</replaceable></userinput>
 250-example.com Hello example.com [192.0.34.166], pleased to meet you
 250-ENHANCEDSTATUSCODES
@@ -1968,10 +1984,10 @@ Escape character is '^]'.
 250-DELIVERBY
 250 HELP
 <userinput>quit</userinput>
-221 2.0.0 <systemitem class="fqdomainname">example.com</systemitem> closing connection
+221 2.0.0 example.com closing connection
 Connection closed by foreign host.</screen>
 
-      <para>If the <quote>STARTTLS</quote> line appears in the
+      <para>If the <literal>STARTTLS</literal> line appears in the
 	output, everything is working correctly.</para>
     </sect2>
   </sect1>