Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 2 May 2013 14:22:16 +0000 (UTC)
From:      Dru Lavigne <dru@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-projects@freebsd.org
Subject:   svn commit: r41541 - projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security
Message-ID:  <201305021422.r42EMGne080645@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: dru
Date: Thu May  2 14:22:15 2013
New Revision: 41541
URL: http://svnweb.freebsd.org/changeset/doc/41541

Log:
  This patch addresses the following in the second half of this chapter:
  
  - you
  
  - &os;
  
  - some acronym tags
  
  - the remaining command/application tags that should be man page entities
  
  - some grammar fixes
  
  Approved by:  bcr (mentor)

Modified:
  projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml

Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml	Thu May  2 13:02:26 2013	(r41540)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/handbook/security/chapter.xml	Thu May  2 14:22:15 2013	(r41541)
@@ -53,7 +53,7 @@
 
       <listitem>
 	<para>How to configure <acronym>TCP</acronym> Wrappers for use
-	  with <application>inetd</application>.</para>
+	  with &man.inetd.8;.</para>
       </listitem>
 
       <listitem>
@@ -257,7 +257,7 @@
       <title>Securing the <username>root</username> Account</title>
 
       <indexterm>
-	<primary><command>su</command></primary>
+	<primary>&man.su.1;</primary>
       </indexterm>
 
       <para>Most
@@ -355,7 +355,7 @@
 	<primary>sandboxes</primary>
       </indexterm>
       <indexterm>
-	<primary><application>sshd</application></primary>
+	<primary>&man.sshd.8;</primary>
       </indexterm>
 
       <para>The prudent sysadmin only enables required services
@@ -365,12 +365,12 @@
 	<username>root</username> as many daemons can be run as a
 	separate service account or can be started in a
 	<firstterm>sandbox</firstterm>.  Do not activate insecure
-	services such as <application>telnetd</application> or
-	<application>rlogind</application>.</para>
+	services such as &man.telnetd.8; or
+	&man.rlogind.8;.</para>
 
       <para>Another potential security hole is SUID-root and SGID
 	binaries.  Most of these binaries, such as
-	<application>rlogin</application>, reside in <filename
+	&man.rlogin.1;, reside in <filename
 	  class="directory">/bin</filename>, <filename
 	  class="directory">/sbin</filename>, <filename
 	  class="directory">/usr/bin</filename>, or <filename
@@ -434,7 +434,7 @@
 	systems that do not provide or use DHCP.</para>
 
       <indexterm>
-	<primary><command>sysctl</command></primary>
+	<primary>&man.sysctl.8;</primary>
       </indexterm>
 
       <para>Even if <devicename>bpf</devicename> is disabled,
@@ -525,7 +525,7 @@
       <para>The best way to detect an intrusion is to look for
 	modified, missing, or unexpected files.  The best way to look
 	for modified files is from another, often centralized,
-	limited-access system.  Writing your security scripts on the
+	limited-access system.  Writing security scripts on the
 	extra-security limited-access system makes them mostly
 	invisible
 	to potential attackers.  In order to take maximum advantage,
@@ -657,7 +657,7 @@
 	&man.inetd.8; carefully and pay specific attention to
 	<option>-c</option>, <option>-C</option>, and
 	<option>-R</option>.  Spoofed IP attacks will circumvent
-	<option>-C</option> to <application>inetd</application>, so
+	<option>-C</option> to &man.inetd.8;, so
 	typically a combination of options must be used.  Some
 	standalone servers have self-fork-limitation
 	parameters.</para>
@@ -681,7 +681,7 @@
 	reasonable <literal>MaxDaemonChildren</literal> to prevent
 	cascade failures.</para>
 
-      <para><application>Syslogd</application> can be attacked
+      <para>&man.syslogd.8; can be attacked
 	directly and it is strongly recommended to use
 	<option>-s</option> whenever possible, and
 	<option>-a</option> otherwise.</para>
@@ -722,10 +722,10 @@
 	with ICMP responses.  This type of attack can crash the
 	server by running it out of memory, especially if the server
 	cannot drain the ICMP responses it generates fast enough.  Use
-	the <application>sysctl</application> variable
+	the &man.sysctl.8; variable
 	<literal>net.inet.icmp.icmplim</literal> to limit these
 	attacks.  The last major class of springboard attacks is
-	related to certain internal <application>inetd</application>
+	related to certain internal &man.inetd.8;
 	services such as the UDP echo service.  An attacker spoofs a
 	UDP packet with a source address of server A's echo port
 	and a destination address of server B's echo port, where
@@ -744,7 +744,7 @@
 	parameters.  A spoofed packet attack that uses a random source
 	IP will cause the kernel to generate a temporary cached route
 	in the route table, viewable with <command>netstat -rna |
-	fgrep W3</command>.  These routes typically timeout in 1600
+	  fgrep W3</command>.  These routes typically timeout in 1600
 	seconds or so.  If the kernel detects that the cached route
 	table has gotten too big, it will dynamically reduce the
 	<varname>rtexpire</varname> but will never decrease it to less
@@ -774,15 +774,15 @@
     </sect2>
 
     <sect2>
-      <title>Access Issues with Kerberos and SSH</title>
+      <title>Access Issues with Kerberos and &man.ssh.1;</title>
 
-      <indexterm><primary><command>ssh</command></primary></indexterm>
+      <indexterm><primary>&man.ssh.1;</primary></indexterm>
 
       <para>There are a few issues with both Kerberos and
 	&man.ssh.1; that need to be addressed if
 	they are used.  Kerberos is an excellent authentication
-	protocol, but there are bugs in the kerberized
-	&man.telnet.1; and &man.rlogin.1; applications that make them
+	protocol, but there are bugs in the kerberized versions of
+	&man.telnet.1; and &man.rlogin.1; that make them
 	unsuitable for dealing with binary streams.  By default,
 	Kerberos does not encrypt a session unless
 	<option>-x</option> is used whereas  &man.ssh.1;
@@ -801,13 +801,14 @@
 
       <para>It is recommended that &man.ssh.1; is
 	used in combination with Kerberos whenever possible for staff
-	logins and  &man.ssh.1; can be compiled with
+	logins and &man.ssh.1; can be compiled with
 	Kerberos support.  This reduces reliance on potentially
-	exposed ssh keys while protecting passwords via Kerberos.
+	exposed <acronym>SSH</acronym> keys while protecting
+	passwords via Kerberos.
 	Keys should only be used for automated tasks from secure
 	machines as this is something that Kerberos is unsuited to.
 	It is recommended to either turn off key-forwarding in the
-	<application>ssh</application> configuration, or to make use
+	<acronym>SSH</acronym> configuration, or to make use
 	of <literal>from=IP/DOMAIN</literal> in
 	<filename>authorized_keys</filename> to make the key only
 	usable to entities logging in from specific machines.</para>
@@ -971,7 +972,7 @@
       <title>Secure Connection Initialization</title>
 
       <para>To initialize <acronym>OPIE</acronym> for the first time,
-	execute <command>opiepasswd</command>:</para>
+	execute &man.opiepasswd.1;:</para>
 
       <screen>&prompt.user; <userinput>opiepasswd -c</userinput>
 [grimreaper] ~ $ opiepasswd -f -c
@@ -1173,7 +1174,7 @@ Enter secret pass phrase: <userinput>&lt
       <title>Initial Configuration</title>
 
       <para>To enable <acronym>TCP</acronym> Wrappers in &os;, ensure
-	the <application>inetd</application> server is started from
+	the &man.inetd.8; server is started from
 	<filename>/etc/rc.conf</filename> with
 	<option>-Ww</option>.  Then, properly configure
 	<filename>/etc/hosts.allow</filename>.</para>
@@ -1189,7 +1190,7 @@ Enter secret pass phrase: <userinput>&lt
 	are set to either be permitted or blocked depending on the
 	options in <filename>/etc/hosts.allow</filename>.  The default
 	configuration in &os; is to allow a connection to every daemon
-	started with <application>inetd</application>.</para>
+	started with &man.inetd.8;.</para>
 
       <para>Basic configuration usually takes the form of
 	<literal>daemon : address : action</literal>, where
@@ -1213,7 +1214,7 @@ Enter secret pass phrase: <userinput>&lt
       <programlisting># This line is required for POP3 connections:
 qpopper : ALL : allow</programlisting>
 
-      <para>After adding this line, <application>inetd</application>
+      <para>After adding this line, &man.inetd.8;
 	needs to be restarted:</para>
 
 	<screen>&prompt.root; <userinput>service inetd restart</userinput></screen>
@@ -1575,7 +1576,7 @@ Verifying password - Password: <userinpu
 	services.  While there will not be any kerberized daemons
 	running at this point, it is possible to confirm that
 	the <acronym>KDC</acronym> is functioning by obtaining and
-	listing a ticket for the principal (user) that you just
+	listing a ticket for the principal (user) that was just
 	created from the command-line of the <acronym>KDC</acronym>
 	itself:</para>
 
@@ -2134,31 +2135,31 @@ kadmind5_server_enable="YES"</programlis
       <secondary>OpenSSL</secondary>
     </indexterm>
 
-    <para>One feature that many users overlook is the
-      <application>OpenSSL</application> toolkit included in &os;.
-      <application>OpenSSL</application> provides an encryption
-      transport layer on top of the normal communications layer;
-      thus allowing it to be intertwined with many network
+    <para>The
+      <application>OpenSSL</application> toolkit is included in &os;.
+      It provides an encryption
+      transport layer on top of the normal communications layer,
+      allowing it to be intertwined with many network
       applications and services.</para>
 
     <para>Some uses of <application>OpenSSL</application> may
-      include encrypted authentication of mail clients, web based
-      transactions such as credit card payments and more.  Many
+      include encrypted authentication of mail clients and web based
+      transactions such as credit card payments.  Many
       ports such as
       <filename role="package">www/apache22</filename>, and
-      <filename role="package">mail/claws-mail</filename> will offer
+      <filename role="package">mail/claws-mail</filename> offer
       compilation support for building with
       <application>OpenSSL</application>.</para>
 
     <note>
-      <para>In most cases the Ports Collection will attempt to build
+      <para>In most cases, the Ports Collection will attempt to build
 	the <filename role="package">security/openssl</filename>
-	port unless the <makevar>WITH_OPENSSL_BASE</makevar> make
-	variable is explicitly set to <quote>yes</quote>.</para>
+	port unless <makevar>WITH_OPENSSL_BASE</makevar>
+	is explicitly set to <quote>yes</quote>.</para>
     </note>
 
     <para>The version of <application>OpenSSL</application> included
-      in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3),
+      in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3) and
       Transport Layer Security v1 (TLSv1) network security protocols
       and can be used as a general cryptographic library.</para>
 
@@ -2168,7 +2169,7 @@ kadmind5_server_enable="YES"</programlis
 	due to United States patents.  To use it, the license should
 	be reviewed and, if the restrictions are acceptable, the
 	<makevar>MAKE_IDEA</makevar> variable must be set in
-	<filename>make.conf</filename>.</para>
+	<filename>/etc/make.conf</filename>.</para>
     </note>
 
     <para>One of the most common uses of
@@ -2176,15 +2177,14 @@ kadmind5_server_enable="YES"</programlis
       for use with software applications.  These certificates ensure
       that the credentials of the company or individual are valid
       and not fraudulent.  If the certificate in question has not
-      been verified by one of the several <quote>Certificate
-      Authorities</quote>, or <acronym>CA</acronym>s, a warning is
-      usually produced.  A Certificate Authority is a company, such
+      been verified by a <quote>Certificate
+      Authority</quote> (<acronym>CA</acronym>), a warning is
+      produced.  A <acronym>CA</acronym> is a company, such
       as <ulink url="http://www.verisign.com">VeriSign</ulink>,
-      which will sign certificates in order to validate credentials
+      signs certificates in order to validate the credentials
       of individuals or companies.  This process has a cost
-      associated with it and is definitely not a requirement for
-      using certificates; however, it can put some of the more
-      paranoid users at ease.</para>
+      associated with it and is not a requirement for
+      using certificates; however, it can put users at ease.</para>
 
     <sect2>
       <title>Generating Certificates</title>
@@ -2226,22 +2226,23 @@ An optional company name []:<userinput><
       <para>Notice the response directly after the
 	<quote>Common Name</quote> prompt shows a domain name.  This
 	prompt requires a server name to be entered for verification
-	purposes; placing anything but a domain name would yield a
-	useless certificate.  Other options, for instance expire
-	time, alternate encryption algorithms, etc. are available.
-	A complete list may be obtained by viewing the
-	&man.openssl.1; manual page.</para>
-
-      <para>Two files should now exist in the directory in which the
-	aforementioned command was issued.  The certificate request,
-	<filename>req.pem</filename>, may be sent to a certificate
-	authority who will validate the credentials that you
-	entered, sign the request and return the certificate to you.
-	The second file created will be named
+	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
+	command was issued.  The certificate request,
+	<filename>req.pem</filename>, may 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
 	<filename>cert.pem</filename> and is the private key for the
-	certificate and should be protected at all costs; if this
+	certificate and should be protected at all costs.  If this
 	falls in the hands of others it can be used to impersonate
-	you (or your server).</para>
+	the user or the server.</para>
 
       <para>In cases where a signature from a <acronym>CA</acronym>
 	is not required, a self signed certificate can be created.
@@ -2263,30 +2264,31 @@ An optional company name []:<userinput><
 	<filename>new.crt</filename>.  These should be placed in a
 	directory, preferably under
 	<filename class="directory">/etc</filename>, which is readable
-	only by <username>root</username>.  Permissions of 0700 should
-	be fine for this and they can be set with the
-	<command>chmod</command> utility.</para>
+	only by <username>root</username>.  Permissions of 0700 are
+	appropriate and can be set using
+	&man.chmod.1;.</para>
     </sect2>
 
     <sect2>
-      <title>Using Certificates, an Example</title>
+      <title>Using Certificates</title>
 
-      <para>So what can these files do?  A good use would be to
+      <para>One use for a certificate is to
 	encrypt connections to the
 	<application>Sendmail</application> <acronym>MTA</acronym>.
-	This would dissolve the use of clear text authentication for
+	This prevents the use of clear text authentication for
 	users who send mail via the local
 	<acronym>MTA</acronym>.</para>
 
       <note>
-	<para>This is not the best use in the world as some
-	  <acronym>MUA</acronym>s will present the user with an
-	  error if they have not installed the certificate locally.
+	<para>Some
+	  <acronym>MUA</acronym>s will display
+	  error if the user has not installed the certificate locally.
 	  Refer to the documentation included with the software for
 	  more information on certificate installation.</para>
       </note>
 
-      <para>The following lines should be placed inside the local
+      <para>To configure <application>Sendmail</application>, the
+	following lines should be placed in the local
 	<filename>.mc</filename> file:</para>
 
       <programlisting>dnl SSL Options
@@ -2296,24 +2298,24 @@ define(`confSERVER_CERT',`/etc/certs/new
 define(`confSERVER_KEY',`/etc/certs/myca.key')dnl
 define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting>
 
-      <para>Where <filename class="directory">/etc/certs/</filename>
-	is the directory to be used for storing the certificate and
-	key files locally.  The last few requirements are a rebuild
-	of the local <filename>.cf</filename> file.  This is easily
-	achieved by typing <command>make
-	  <maketarget>install</maketarget></command> within the
-	<filename class="directory">/etc/mail</filename> directory.
+      <para>In this example,  <filename
+	  class="directory">/etc/certs/</filename>
+	stores the certificate and
+	key files locally.  After saving the edits, rebuild
+	the local <filename>.cf</filename> file by typing
+	<command>make <maketarget>install</maketarget></command>
+	within <filename class="directory">/etc/mail</filename>.
 	Follow that up with <command>make
 	  <maketarget>restart</maketarget></command> which should
 	start the <application>Sendmail</application> daemon.</para>
 
-      <para>If all went well there will be no error messages in the
-	<filename>/var/log/maillog</filename> file and
+      <para>If all went well, there will be no error messages in
+	<filename>/var/log/maillog</filename> and
 	<application>Sendmail</application> will show up in the
 	process list.</para>
 
-      <para>For a simple test, simply connect to the mail server
-	using the &man.telnet.1; utility:</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...
@@ -2337,7 +2339,7 @@ Escape character is '^]'.
 Connection closed by foreign host.</screen>
 
       <para>If the <quote>STARTTLS</quote> line appears in the
-	output then everything is working correctly.</para>
+	output, everything is working correctly.</para>
     </sect2>
   </sect1>
 
@@ -2355,15 +2357,12 @@ Connection closed by foreign host.</scre
       </authorgroup>
     </sect1info>
 
-    <title>VPN over IPsec</title>
+    <title><acronym>VPN</acronym> over IPsec</title>
 
     <indexterm>
       <primary>IPsec</primary>
     </indexterm>
 
-    <para>Creating a VPN between two networks, separated by the
-      Internet, using FreeBSD gateways.</para>
-
     <sect2>
       <sect2info>
 	<authorgroup>
@@ -2380,18 +2379,19 @@ Connection closed by foreign host.</scre
 
       <title>Understanding IPsec</title>
 
-      <para>This section will guide you through the process of
-	setting up IPsec.  In order to set up IPsec, it is necessary
-	that you are familiar with the concepts of building a custom
+      <para>This section demonstrates the process of
+	setting up IPsec.  It assumes
+	familiarity with the concepts of building a custom
 	kernel (see <xref linkend="kernelconfig"/>).</para>
 
       <para><emphasis>IPsec</emphasis> is a protocol which sits on
-	top of the Internet Protocol (IP) layer.  It allows two or
-	more hosts to communicate in a secure manner (hence the
-	name).  The FreeBSD IPsec <quote>network stack</quote> is
+	top of the Internet Protocol (<acronym>IP</acronym>) layer.
+	It allows two or
+	more hosts to communicate in a secure manner.
+	The &os; IPsec <quote>network stack</quote> is
 	based on the <ulink url="http://www.kame.net/">KAME</ulink>;
-	implementation, which has support for both protocol
-	families, IPv4 and IPv6.</para>
+	implementation, which has support for both IPv4 and
+	IPv6.</para>
 
       <indexterm>
 	<primary>IPsec</primary>
@@ -2408,16 +2408,18 @@ Connection closed by foreign host.</scre
       <itemizedlist>
 	<listitem>
 	  <para><emphasis>Encapsulated Security Payload
-	      ESP)</emphasis>, protects the IP packet data from
-	    third party interference, by encrypting the contents
-	    using symmetric cryptography algorithms (like Blowfish,
-	    3DES).</para>
+	      <acronym>ESP</acronym>)</emphasis>: this protocol
+	    protects the IP packet data from
+	    third party interference by encrypting the contents
+	    using symmetric cryptography algorithms such as Blowfish
+	    and 3DES.</para>
 	</listitem>
 
 	<listitem>
-	  <para><emphasis>Authentication Header (AH)</emphasis>,
+	  <para><emphasis>Authentication Header
+	    (<acronym>AH</acronym>)</emphasis>: this protocol
 	    protects the IP packet header from third party
-	    interference and spoofing, by computing a cryptographic
+	    interference and spoofing by computing a cryptographic
 	    checksum and hashing the IP packet header fields with a
 	    secure hashing function.  This is then followed by an
 	    additional header that contains the hash, to allow the
@@ -2439,18 +2441,17 @@ Connection closed by foreign host.</scre
       </indexterm>
 
       <para>IPsec can either be used to directly encrypt the traffic
-	between two hosts (known as <emphasis>Transport
-	  Mode</emphasis>); or to build <quote>virtual
-	  tunnels</quote> between two subnets, which could be used for
-	secure communication between two corporate networks (known
-	as <emphasis>Tunnel Mode</emphasis>).  The latter is more
+	between two hosts using <emphasis>Transport
+	  Mode</emphasis> or to build <quote>virtual
+	  tunnels</quote> using
+	<emphasis>Tunnel Mode</emphasis>.  The latter mode is more
 	commonly known as a <emphasis>Virtual Private Network
-	(VPN)</emphasis>.  The &man.ipsec.4; manual page should be
-	consulted for detailed information on the IPsec subsystem in
-	FreeBSD.</para>
+	(<acronym>VPN</acronym>)</emphasis>.  Consult &man.ipsec.4;
+	for detailed information on the IPsec subsystem in
+	&os;.</para>
 
-      <para>To add IPsec support to your kernel, add the following
-	options to your kernel configuration file:</para>
+      <para>To add IPsec support to the kernel, add the following
+	options to the custom kernel configuration file:</para>
 
       <indexterm>
 	<primary>kernel options</primary>
@@ -2474,40 +2475,30 @@ options   IPSEC_DEBUG  #debug for IP sec
     </sect2>
 
     <sect2>
-      <title>The Problem</title>
-
-      <para>There is no standard for what constitutes a VPN.  VPNs
-	can be implemented using a number of different technologies,
-	each of which have their own strengths and weaknesses.  This
-	section presents a scenario, and the strategies used for
-	implementing a VPN for this scenario.</para>
-    </sect2>
-
-    <sect2>
-      <title>The Scenario: Two networks, one home based and one
-	corporate based.  Both are connected to the Internet, and
-	expected, via this <acronym>VPN</acronym> to behave as
-	one.</title>
+      <title><acronym>VPN</acronym> Between a Home and Corporate
+	Network</title>
 
       <indexterm>
 	<primary>VPN</primary>
 	<secondary>creating</secondary>
       </indexterm>
 
-      <para>The premise is as follows:</para>
+      <para>There is no standard for what constitutes a
+	<acronym>VPN</acronym>.  <acronym>VPN</acronym>s can be
+	implemented using a number of different technologies, each
+	of which has their own strengths and weaknesses.  This
+	section presents the strategies used for implementing a
+	<acronym>VPN</acronym> for the following scenario:</para>
 
       <itemizedlist>
 	<listitem>
-	  <para>You have at least two sites</para>
-	</listitem>
-
-	<listitem>
-	  <para>Both sites are using IP internally</para>
+	  <para>There are at least two sites where each site is using
+	    IP internally.</para>
 	</listitem>
 
 	<listitem>
-	  <para>Both sites are connected to the Internet, through a
-	    gateway that is running FreeBSD.</para>
+	  <para>Both sites are connected to the Internet through a
+	    gateway that is running &os;.</para>
 	</listitem>
 
 	<listitem>
@@ -2517,15 +2508,15 @@ options   IPSEC_DEBUG  #debug for IP sec
 
 	<listitem>
 	  <para>The internal addresses of the two networks can be
-	    public or private IP addresses, it does not matter.
-	    They just may not collide; e.g.: may not both use
+	    either public or private IP addresses.  However, the
+	    address space must not collide.  For example, both
+	    networks cannot use
 	    <hostid role="ipaddr">192.168.1.x</hostid>.</para>
 	</listitem>
       </itemizedlist>
-    </sect2>
 
-    <sect2>
-      <sect2info>
+    <sect3>
+      <sect3info>
 	<authorgroup>
 	  <author>
 	    <firstname>Tom</firstname>
@@ -2536,23 +2527,24 @@ options   IPSEC_DEBUG  #debug for IP sec
 	    <contrib>Written by </contrib>
 	  </author>
 	</authorgroup>
-      </sect2info>
+      </sect3info>
 
       <title>Configuring IPsec on &os;</title>
 
-      <para>To begin, the
+      <para>To begin,
 	<filename role="package">security/ipsec-tools</filename>
-	must be installed from the Ports Collection.  This third
-	party software package provides a number of applications
-	which will help support the configuration.</para>
+	must be installed from the Ports Collection.  This
+	software provides a number of applications
+	which support the configuration.</para>
 
       <para>The next requirement is to create two &man.gif.4;
 	pseudo-devices which will be used to tunnel packets and
 	allow both networks to communicate properly.  As
 	<username>root</username>, run the following commands,
-	replacing the <replaceable>internal</replaceable> and
-	<replaceable>external</replaceable> items with the real
-	internal and external gateways:</para>
+	replacing <replaceable>internal</replaceable> and
+	<replaceable>external</replaceable> with the real IP
+	addresses of the
+	internal and external interfaces of the two gateways:</para>
 
       <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput></screen>
 
@@ -2560,18 +2552,19 @@ options   IPSEC_DEBUG  #debug for IP sec
 
       <screen>&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>external1 external2</replaceable></userinput></screen>
 
-      <para>For example, the corporate <acronym>LAN</acronym>'s
-	public <acronym>IP</acronym> is
-	<hostid role="ipaddr">172.16.5.4</hostid> having a private
-	<acronym>IP</acronym> of
+      <para>In this example, the corporate <acronym>LAN</acronym>'s
+	external <acronym>IP</acronym> address is
+	<hostid role="ipaddr">172.16.5.4</hostid> and its internal
+	<acronym>IP</acronym> address is
 	<hostid role="ipaddr">10.246.38.1</hostid>.  The home
-	<acronym>LAN</acronym>'s public <acronym>IP</acronym> is
-	<hostid role="ipaddr">192.168.1.12</hostid> with an internal
-	private <acronym>IP</acronym> of
+	<acronym>LAN</acronym>'s external <acronym>IP</acronym>
+	address is
+	<hostid role="ipaddr">192.168.1.12</hostid> and its internal
+	private <acronym>IP</acronym> address is
 	<hostid role="ipaddr">10.0.0.5</hostid>.</para>
 
-      <para>This may seem confusing, so review the following example
-	output from the &man.ifconfig.8; command:</para>
+      <para>If this is confusing, review the following example output
+	from &man.ifconfig.8;:</para>
 
       <programlisting>Gateway 1:
 
@@ -2587,9 +2580,8 @@ tunnel inet 192.168.1.12 --&gt; 172.16.5
 inet 10.0.0.5 --&gt; 10.246.38.1 netmask 0xffffff00
 inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4</programlisting>
 
-      <para>Once complete, both private <acronym>IP</acronym>s
-	should be reachable using the &man.ping.8; command like
-	the following output suggests:</para>
+      <para>Once complete, both internal <acronym>IP</acronym>
+	addresses should be reachable using &man.ping.8;:</para>
 
       <programlisting>priv-net# ping 10.0.0.5
 PING 10.0.0.5 (10.0.0.5): 56 data bytes
@@ -2629,8 +2621,8 @@ round-trip min/avg/max/stddev = 28.106/9
 
       <para>At this point, internal machines should be reachable
 	from each gateway as well as from machines behind the
-	gateways.  This is easily determined from the following
-	example:</para>
+	gateways.  Again, use &man.ping.8; to
+	confirm:</para>
 
       <programlisting>corp-net# ping 10.0.0.8
 PING 10.0.0.8 (10.0.0.8): 56 data bytes
@@ -2655,12 +2647,13 @@ PING 10.246.38.1 (10.246.38.107): 56 dat
 round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms</programlisting>
 
       <para>Setting up the tunnels is the easy part.  Configuring
-	a secure link is a much more in depth process.  The
+	a secure link is a more in depth process.  The
 	following configuration uses pre-shared
-	(<acronym>PSK</acronym>) <acronym>RSA</acronym> keys.  Aside
-	from the <acronym>IP</acronym> addresses, both
-	<filename>/usr/local/etc/racoon/racoon.conf</filename> files
-	will be identical and look similar to</para>
+	(<acronym>PSK</acronym>) <acronym>RSA</acronym> keys.  Other than
+	the <acronym>IP</acronym> addresses, the
+	<filename>/usr/local/etc/racoon/racoon.conf</filename> on
+	both gateways
+	will be identical and look similar to:</para>
 
       <programlisting>path    pre_shared_key  "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file
 log     debug;	#log verbosity setting: set to 'notify' when testing and debugging is complete
@@ -2720,19 +2713,18 @@ sainfo  (address 10.246.38.0/24 any addr
         compression_algorithm   deflate;
 }</programlisting>
 
-      <para>Explaining every available option, along with those
-	listed in these examples is beyond the scope of this
-	document.  There is plenty of relevant information in the
-	<application>racoon</application> configuration manual
-	page.</para>
-
-      <para>The <acronym>SPD</acronym> policies need to be
-	configured so &os; and <application>racoon</application> is
-	able to encrypt and decrypt network traffic between
+      <para>For descriptions of each available option, refer to the
+	manual
+	page for <filename>racoon.conf</filename>.</para>
+
+      <para>The Security Policy Database (<acronym>SPD</acronym>)
+	needs to be configured so that &os; and
+	<application>racoon</application> are
+	able to encrypt and decrypt network traffic between the
 	hosts.</para>
 
-      <para>This task may be undertaken with a simple shell script
-	similar to the following which is on the corporate gateway.
+      <para>This can be achieved with a shell script,
+	similar to the following, on the corporate gateway.
 	This file will be used during system initialization and
 	should be saved as
 	<filename>/usr/local/etc/racoon/setkey.conf</filename>.</para>
@@ -2767,12 +2759,12 @@ Foreground mode.
 	another console and use &man.tcpdump.1; to view network
 	traffic using the following command.  Replace
 	<literal>em0</literal> with the network interface card as
-	required.</para>
+	required:</para>
 
       <screen>&prompt.root; <userinput>tcpdump -i em0 host <replaceable>172.16.5.4 and dst 192.168.1.12</replaceable></userinput></screen>
 
       <para>Data similar to the following should appear on the
-	console.  If not, there is an issue, and debugging the
+	console.  If not, there is an issue and debugging the
 	returned data will be required.</para>
 
       <programlisting>01:47:32.021683 IP corporatenetwork.com &gt; 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa)
@@ -2781,9 +2773,9 @@ Foreground mode.
 
       <para>At this point, both networks should be available and
 	seem to be part of the same network.  Most likely both
-	networks are protected by a firewall, as they should be.  To
+	networks are protected by a firewall.  To
 	allow traffic to flow between them, rules need to be added
-	to pass packets back and forth.  For the &man.ipfw.8;
+	to pass packets.  For the &man.ipfw.8;
 	firewall, add the following lines to the firewall
 	configuration file:</para>
 
@@ -2819,7 +2811,8 @@ pass out quick on gif0 from any to any</
 ipsec_program="/usr/local/sbin/setkey"
 ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot
 racoon_enable="yes"</programlisting>
-    </sect2>
+    </sect3>
+  </sect2>
   </sect1>
 
   <sect1 id="openssh">
@@ -2844,65 +2837,63 @@ racoon_enable="yes"</programlisting>
 
     <para><application>OpenSSH</application> is a set of network
       connectivity tools used to access remote machines securely.
-      It can be used as a direct replacement for
-      <command>rlogin</command>, <command>rsh</command>,
-      <command>rcp</command>, and <command>telnet</command>.
       Additionally, TCP/IP connections can be tunneled/forwarded
-      securely through SSH.  <application>OpenSSH</application>
+      securely through <acronym>SSH</acronym> connections. 
+      <application>OpenSSH</application>
       encrypts all traffic to effectively eliminate eavesdropping,
       connection hijacking, and other network-level attacks.</para>
 
     <para><application>OpenSSH</application> is maintained by the
-      OpenBSD project, and is based upon SSH v1.2.12 with all the
-      recent bug fixes and updates.  It is compatible with both SSH
-      protocols 1 and 2.</para>
+      OpenBSD project and is installed by default in &os;.  It is
+      compatible with both <acronym>SSH</acronym> version
+      1 and 2 protocols.</para>
 
     <sect2>
-      <title>Advantages of Using OpenSSH</title>
-
-      <para>Normally, when using &man.telnet.1; or &man.rlogin.1;,
-	data is sent over the network in a clear, un-encrypted form.
-	Network sniffers anywhere in between the client and server
-	can steal your user/password information or data transferred
-	in your session.  <application>OpenSSH</application> offers
+      <title>Advantages of Using
+	<application>OpenSSH</application></title>
+
+      <para>When
+	data is sent over the network in an unencrypted form,
+	network sniffers anywhere in between the client and server
+	can steal user/password information or data transferred
+	during the session.  <application>OpenSSH</application> offers
 	a variety of authentication and encryption methods to
 	prevent this from happening.</para>
     </sect2>
 
     <sect2>
-      <title>Enabling <application>sshd</application></title>
+      <title>Enabling &man.sshd.8;</title>
 
       <indexterm>
 	<primary>OpenSSH</primary>
 	<secondary>enabling</secondary>
       </indexterm>
 
-      <para>The <application>sshd</application> is an option
-	presented during a <literal>Standard</literal> install of
-	&os;.  To see if <application>sshd</application> is enabled,
-	check the <filename>rc.conf</filename> file for:</para>
+      <para>To see if &man.sshd.8; is enabled,
+	check <filename>/etc/rc.conf</filename> for this line:</para>
 
       <programlisting>sshd_enable="YES"</programlisting>
 
-      <para>This will load &man.sshd.8;, the daemon program for
-	<application>OpenSSH</application>, the next time your
+      <para>This will start &man.sshd.8;, the daemon program for
+	<application>OpenSSH</application>, the next time the
 	system initializes.  Alternatively, it is possible to use
 	&man.service.8; to
-	start <application>OpenSSH</application>:</para>
+	start <application>OpenSSH</application> now:</para>
 
       <screen>&prompt.root; <userinput>service sshd start</userinput></screen>
     </sect2>
 
     <sect2>
-      <title>SSH Client</title>
+      <title>&man.ssh.1; Client</title>
 
       <indexterm>
 	<primary>OpenSSH</primary>
 	<secondary>client</secondary>
       </indexterm>
 
-      <para>The &man.ssh.1; utility works similarly to
-	&man.rlogin.1;.</para>
+      <para>To use &man.ssh.1; to connect to a system running
+	&man.sshd.8;, specify the username and host to log
+	into:</para>
 
       <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput>
 Host key not found from the list of known hosts.
@@ -2910,22 +2901,19 @@ Are you sure you want to continue connec
 Host 'example.com' added to the list of known hosts.
 user@example.com's password: <userinput>*******</userinput></screen>
 
-      <para>The login will continue just as it would have if a
-	session was created using <command>rlogin</command> or
-	<command>telnet</command>.  SSH utilizes a key fingerprint
-	system for verifying the authenticity of the server when the
-	client connects.  The user is prompted to enter
-	<literal>yes</literal> only when connecting for the first
-	time.  Future attempts to login are all verified against the
-	saved fingerprint key.  The SSH client will alert you if the
+      <para><acronym>SSH</acronym> utilizes a key fingerprint
+	system to verify the authenticity of the server when the
+	client connects.  The user is prompted to type
+	<literal>yes</literal> when connecting for the first
+	time.  Future attempts to login are verified against the
+	saved fingerprint key and the &man.ssh.1; client will display
+	an alert if the
 	saved fingerprint differs from the received fingerprint on
 	future login attempts.  The fingerprints are saved in
-	<filename>~/.ssh/known_hosts</filename>, or
-	<filename>~/.ssh/known_hosts2</filename> for SSH v2
-	fingerprints.</para>
+	<filename>~/.ssh/known_hosts</filename>.</para>
 
-      <para>By default, recent versions of the
-	<application>OpenSSH</application> servers only accept SSH
+      <para>By default, recent versions of &man.sshd.8; only accept
+	<acronym>SSH</acronym>
 	v2 connections.  The client will use version 2 if possible
 	and will fall back to version 1.  The client can also be
 	forced to use one or the other by passing it the
@@ -2943,11 +2931,11 @@ user@example.com's password: <userinput>
 	<secondary>secure copy</secondary>
       </indexterm>
       <indexterm>
-	<primary><command>scp</command></primary>
+	<primary>&man.scp.1;</primary>
       </indexterm>
 
-      <para>The &man.scp.1; command works similarly to &man.rcp.1;;
-	it copies a file to or from a remote machine, except in a
+      <para>Use &man.scp.1; to
+	copy a file to or from a remote machine in a
 	secure fashion.</para>
 
       <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput>
@@ -2961,10 +2949,12 @@ COPYRIGHT            100% |*************
 	here.</para>
 
       <para>The arguments passed to &man.scp.1; are similar to
-	&man.cp.1;, with the file or files in the first argument,
+	&man.cp.1;, with the file or files to copy in the first
+	argument,
 	and the destination in the second.  Since the file is
-	fetched over the network, through SSH, one or more of the
-	file arguments takes on the form
+	fetched over the network, through an <acronym>SSH</acronym>,
+	connection, one or more of the
+	file arguments takes the form
 	<option>user@host:&lt;path_to_remote_file&gt;</option>.</para>
     </sect2>
 
@@ -2978,24 +2968,20 @@ COPYRIGHT            100% |*************
 
       <para>The system-wide configuration files for both the
 	<application>OpenSSH</application> daemon and client reside
-	within the <filename class="directory">/etc/ssh</filename>
-	directory.</para>
+	in <filename class="directory">/etc/ssh</filename>.</para>
 
       <para><filename>ssh_config</filename> configures the client
 	settings, while <filename>sshd_config</filename> configures
-	the daemon.</para>
-
-      <para>Additionally, the <option>sshd_program</option>
-	(<filename>/usr/sbin/sshd</filename> by default), and
-	<option>sshd_flags</option> <filename>rc.conf</filename>
-	options can provide more levels of configuration.</para>
+	the daemon.  Each file has its own manual page which describes
+	the available configuration options.</para>
     </sect2>
 
     <sect2 id="security-ssh-keygen">
-      <title><application>ssh-keygen</application></title>
+      <title>&man.ssh-keygen.1;</title>
 
       <para>Instead of using passwords, &man.ssh-keygen.1; can
-	be used to generate DSA or RSA keys to authenticate a
+	be used to generate <acronym>DSA</acronym> or
+	<acronym>RSA</acronym> keys to authenticate a
 	user:</para>
 
       <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput>
@@ -3014,7 +3000,7 @@ bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8
 	in <filename>~/.ssh/id_dsa</filename> or
 	<filename>~/.ssh/id_rsa</filename>, whereas the public key
 	is stored in <filename>~/.ssh/id_dsa.pub</filename> or
-	<filename>~/.ssh/id_rsa.pub</filename>, respectively for
+	<filename>~/.ssh/id_rsa.pub</filename>, respectively for the
 	<acronym>DSA</acronym> and <acronym>RSA</acronym> key types.
 	The public key must be placed in the
 	<filename>~/.ssh/authorized_keys</filename> file of the
@@ -3022,43 +3008,42 @@ bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8
 	<acronym>DSA</acronym> keys in order for the setup to
 	work.</para>
 
-      <para>This will allow connection to the remote machine based
-	upon SSH keys instead of passwords.</para>
+      <para>This setup allows connections to the remote machine based
+	upon <acronym>SSH</acronym> keys instead of passwords.</para>
 
       <para>If a passphrase is used in &man.ssh-keygen.1;, the user
-	will be prompted for a password each time in order to use
+	will be prompted for the passphrase each time in order to use
 	the private key.  &man.ssh-agent.1; can alleviate the strain
 	of repeatedly entering long passphrases, and is explored in
-	the <xref linkend="security-ssh-agent"/> section
-	below.</para>
+	<xref linkend="security-ssh-agent"/>.</para>
 
       <warning>
 	<para>The various options and files can be different
 	  according to the <application>OpenSSH</application>
-	  version you have on your system; to avoid problems you
-	  should consult the &man.ssh-keygen.1; manual page.</para>
+	  version.  To avoid problems,
+	  consult &man.ssh-keygen.1;.</para>
       </warning>
     </sect2>
 
     <sect2 id="security-ssh-agent">
-      <title><application>ssh-agent</application> and <application>ssh-add</application></title>
+      <title>&man.ssh-agent.1; and &man.ssh-add.1;</title>
 
-      <para>The &man.ssh-agent.1; and &man.ssh-add.1; utilities
-	provide methods for <application>SSH</application> keys to
-	be loaded into memory for use, without needing to type the
-	passphrase each time.</para>
-
-      <para>The &man.ssh-agent.1; utility will handle the
-	authentication using the private key(s) that are loaded into
-	it.  &man.ssh-agent.1; should be used to launch another
+      <para>To load <acronym>SSH</acronym>
+	keys into memory for use, without needing to type the
+	passphrase each time, use &man.ssh-agent.1; and
+	&man.ssh-add.1;.</para>
+
+      <para>Authentication is handled by &man.ssh-agent.1;, using the
+	private key(s) that are loaded into
+	it.  Then, &man.ssh-agent.1; should be used to launch another
 	application.  At the most basic level, it could spawn a
-	shell or at a more advanced level, a window manager.</para>
+	shell or a window manager.</para>
 
-      <para>To use &man.ssh-agent.1; in a shell, first it will need
-	to be spawned with a shell as an argument.  Secondly, the
-	identity needs to be added by running &man.ssh-add.1; and
+      <para>To use &man.ssh-agent.1; in a shell, start it
+	with a shell as an argument.  Next, add the identity
+	by running &man.ssh-add.1; and
 	providing it the passphrase for the private key.  Once these
-	steps have been completed the user will be able to
+	steps have been completed, the user will be able to
 	&man.ssh.1; to any host that has the corresponding public
 	key installed.  For example:</para>
 
@@ -3068,24 +3053,28 @@ Enter passphrase for /home/user/.ssh/id_
 Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa)
 &prompt.user;</screen>
 
-      <para>To use &man.ssh-agent.1; in X11, a call to
-	&man.ssh-agent.1; will need to be placed in
-	<filename>~/.xinitrc</filename>.  This will provide the
-	&man.ssh-agent.1; services to all programs launched in X11.
+      <para>To use &man.ssh-agent.1; in
+	<application>&xorg;</application>, a call to
+	&man.ssh-agent.1; needs to be placed in
+	<filename>~/.xinitrc</filename>.  This provides the
+	&man.ssh-agent.1; services to all programs launched in
+	<application>&xorg;</application>.

*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201305021422.r42EMGne080645>