Attachment #72565 for bug #105456

View | Details | Raw Unified | Return to bug 105456
Collapse All | Expand All




      </listitem>

      <listitem>
	<para>How to configure IPsec and create a 
	  <acronym role="Virual Private Network">VPN</acronym> between
	  &os;/&windows; machines. </para>
      </listitem>
     
      <listitem>
	<para>How to configure and use <application>OpenSSH</application>
	  , &os;'s <acronym role="Secure Shell">SSH</acronym> implementation.
	  </para>
      </listitem>

      <listitem>
	<para>What file system <acronym role="Access Control Lists">ACL</acronym>s
	  are and how to use them.</para>
      </listitem>

      <listitem>

      inter-networked, security becomes an even bigger issue.</para>

    <para>System security also pertains to dealing with various forms of
      attacks, including attacks that attempt to crash, or otherwise make a
      system unusable, but do not attempt to compromise the
      <username>root</username> account (<quote>break root</quote>).
      Security concerns can be split up into several categories:</para>
      can be split up into several categories:</para>

    <orderedlist>
      <listitem>
	<para>Denial of service (DoS) attacks.</para>
      </listitem>

      <listitem>

    <indexterm><primary>Denial of Service (DoS)</primary></indexterm>

    <para>A denial of service attack is an action that deprives the
      machine of needed resources.  Typically, <acronym>DoS</acronym> attacks
      are brute-force mechanisms that attempt to crash or otherwise make a
      machine unusable by overwhelming its servers or network stack.  Some
      <acronym>DoS</acronym> attacks try to take advantage of bugs in the
      networking stack to crash a machine with a single packet.  The latter
      can only be fixed by applying a bug fix to the kernel.  Attacks on
      servers can often be fixed by properly specifying options to limit the
      load the servers incur on the system under adverse conditions.
      Brute-force network attacks are harder to deal with.  A
      spoofed-packet attack, for example, is nearly impossible to stop,
      short of cutting your system off from the Internet.  It may not be

      <secondary>account compromises</secondary>
    </indexterm>

    <para>A user account compromise is even more common than a
      <acronym>DoS</acronym> attack.  Many sysadmins still run standard 
      <application>telnetd</application>, <application>rlogind</application>,
      <application>rshd</application>,
      and <application>ftpd</application> servers on their machines.

      a suid-root program that allows the attacker to break
      <username>root</username> once he has broken into a user's account.
      If an attacker has found a way to break <username>root</username>
      on a machine, the attacker may have the need
      to install a backdoor.  Many of the <username>root</username> holes
      found and closed to date involve a considerable amount of work
      by the attacker to cleanup after himself, so most attackers install

       <application>bold</application> text to refer to an
       application, and a <command>monospaced</command> font to refer
       to specific commands.  Protocols will use a normal font.  This
       typographical distinction is useful for instances such as SSH,
       since it is a protocol as well as command.</para>
       a protocol as well as command.</para>
    </note>

    <para>The sections that follow will cover the methods of securing your

	<groupname>wheel</groupname> group are allowed to
	<command>su</command> to <username>root</username>.
	You should never give staff
	members native <groupname>wheel</groupname> access by putting them in
	the <groupname>wheel</groupname> group in their password entry.  Staff
	accounts should be placed in a <groupname>staff</groupname> group, and
	then added to the <groupname>wheel</groupname> group via the
	<filename>/etc/group</filename> file.  Only those staff members

	have sufficient control, then you may win out and be able to secure
	the user accounts properly.  If not, you simply have to be more
	vigilant in your monitoring of those accounts.  Use of
	SSH and Kerberos for user accounts is
	more problematic, due to the extra administration and technical
	support required, but still a very good solution compared to a
	encrypted password file.</para>

      <title>Securing the Password File</title>

      <para>The only sure fire way is to star out as many
	passwords as you can and use SSH or
	Kerberos for access to those accounts.  Even though the encrypted
	password file (<filename>/etc/spwd.db</filename>) can only be read
	by <username>root</username>, it may be possible for an intruder

	have to give the limited-access box significant access to the
	other machines in the business, usually either by doing a
	read-only NFS export of the other machines to the limited-access
	box, or by setting up SSH key-pairs to
	allow the limited-access box to use <application>ssh</application> to
	access the other machines.  Except for its network traffic, NFS is the
	least visible method &mdash; allowing you to monitor the
	file systems on each client box virtually undetected.  If your
	limited-access server is connected to the client boxes through a

	hub, or through several layers of routing, the NFS method may be
	too insecure (network-wise) and using
	ssh may be the better choice even with
	the audit-trail tracks that SSH lays.</para>
	lays.</para>

      <para>Once you have given a limited-access box at least read access to the
	client systems it is supposed to monitor, you must write scripts


      <para>When using ssh rather than NFS,
	writing the security script is much more difficult.   You
	essentially have to <command>scp</command> the scripts to the client
	box in order to
	run them, making them visible, and for safety you also need to
	<command>scp</command> the binaries (such as find) that those
	scripts use.  The <application>ssh</application> client on the
	client box may already be compromised.  All in all, using
	SSH may be necessary when running over
	insecure links, but it is also a lot harder to deal with.</para>

      <para>A good security script will also check for changes to user and

      <title>Denial of Service Attacks</title>
      <indexterm><primary>Denial of Service (DoS)</primary></indexterm>

      <para>This section covers Denial of Service attacks.  A
        <acronym role="Denial of Service">DoS</acronym> attack is typically
	a packet attack.  While there is not much you can do
	about modern spoofed packet attacks that saturate your network,
	you can generally limit the damage by ensuring that the attacks
	cannot take down your servers by:</para>

	</listitem>
      </orderedlist>

      <para>A common <acronym>DoS</acronym> attack scenario is attacking a
        forking server and making it spawning so many child processes that the
	host system eventually runs out of memory, file descriptors, etc. and
	then grinds to a halt.  The <application>inetd</application>
	application (see &man.inetd.8;) has several
	options to limit this sort of attack.  It should be noted that
	while it is possible to prevent a machine from going down, it is
	not generally possible to prevent a service from being disrupted
	by the attack.  Read the <application>inetd</application> manual
	page &man.inetd.8; carefully and pay
	specific attention to the <option>-c</option>, <option>-C</option>,
	and <option>-R</option> options.  Note that spoofed-IP attacks
	will circumvent the <option>-C</option> option to 

      <para>It is a very good idea to protect internal services from
	external access by firewalling them off at your border routers.
	The idea here is to prevent saturation attacks from outside your
	<acronym>LAN</acronym>, not so much to protect internal services from
	network-based <username>root</username> compromise.
	Always configure an exclusive firewall, i.e.,
	<quote>firewall everything <emphasis>except</emphasis> ports A, B,
	C, D, and M-Z</quote>.  This way you can firewall off all of your

	without compromising your low ports.  Also take note that &os;
	allows you to control the range of port numbers used for dynamic
	binding, via the various <varname>net.inet.ip.portrange</varname>
	<command>sysctl</command>s (<command>sysctl -a | fgrep
	portrange</command>), which can also ease the complexity of your
	firewall's configuration.  For example, you might use a normal
	first/last range of 4000 to 5000, and a hiport range of 49152 to

	(except for certain specific Internet-accessible ports, of
	course).</para>

      <para>Another common <acronym>DoS</acronym> attack is called a 
        springboard attack &mdash; to attack a server in a manner that causes
	the server to generate responses which overloads the server, the local
	network, or some other machine.  The most common attack of this
	nature is the <emphasis>ICMP ping broadcast attack</emphasis>.
	The attacker spoofs ping packets sent to your LAN's broadcast

	trick on several dozen broadcast addresses over several dozen
	different networks at once.  Broadcast attacks of over a hundred
	and twenty megabits have been measured.  A second common
	springboard attack is against the
	<acronym role="Internet Control Message Protocol">ICMP</acronym> error
	reporting system. By constructing packets that generate
	<acronym>ICMP</acronym> error responses, an attacker can saturate a
	server's incoming network and cause the server to saturate its outgoing
	network with ICMP responses. This type of attack can also 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 <literal>net.inet.icmp.icmplim</literal> to limit these attacks.
	The last major class of springboard

	route cache.  Refer to the <varname>net.inet.ip.rtexpire</varname>,
	<varname>rtminexpire</varname>, and <varname>rtmaxcache</varname>
	<command>sysctl</command> parameters.  A spoofed packet attack
	that uses a random source IP address 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 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 than <varname>rtminexpire</varname>.  There are two 
	problems:</para>
	

      <indexterm><primary>KerberosIV</primary></indexterm>

      <para>There are a few issues with both Kerberos and
	SSH that need to be addressed if
	you intend to use them.  Kerberos 5 is an excellent
	authentication protocol, but there are bugs in the kerberized
	<application>telnet</application> and
	<application>rlogin</application> applications that make them
	unsuitable for dealing with binary streams.  Also, by default
	Kerberos does not encrypt a session unless you use the
	<option>-x</option> option.  SSH encrypts everything by default.</para>
	encrypts everything by default.</para>

      <para>SSH works quite well in every
	respect except that it forwards encryption keys by default.  What
	this means is that if you have a secure workstation holding keys
	that give you access to the rest of the system, and you

	access to any other machine that your keys unlock.</para>

      <para>We recommend that you use ssh in
	combination with Kerberos whenever possible for staff logins.  The
	<application>ssh</application> client and server can be compiled with
	Kerberos support.  This reduces your reliance on potentially exposed
	SSH keys while at the same time protecting passwords via Kerberos.
	SSH keys should only be used for automated tasks from secure machines
	keys should only be used for automated tasks from secure machines
	(something that Kerberos is unsuited to do).  We also recommend that
	you either turn off key-forwarding in the
	<application>ssh</application> configuration, or that you make use
	of the <literal>from=IP/DOMAIN</literal> option that
	<application>ssh</application> allows in its
	<filename>authorized_keys</filename> file to make the key only
	usable to entities logging in from specific machines.</para>
    </sect2>

      space of possible passwords.</para>

    <para>Unfortunately the only secure way to encrypt passwords when
      &unix; came into being was based on
      <acronym role="Data Encryption Standard">DES</acronym>, the Data
      Encryption Standard.  This was not such a problem for users resident in
      the US, but since the source code for <acronym>DES</acronym> could not be 
      exported outside the US, &os; had to find a way to both comply with 
      US law and retain compatibility with all the other &unix;
      variants that still used <acronym>DES</acronym>.</para>

    <para>The solution was to divide up the encryption libraries 
      so that US users could install the <acronym>DES</acronym> libraries and
      use <acronym>DES</acronym> but international users still had an
      encryption method that could be exported abroad.  This is how &os; came
      to use <acronym role="Message Digest 5">MD5</acronym> as its default
      encryption method.  <acronym>MD5</acronym> is believed to be more secure
      than <acronym>DES</acronym>, so installing <acronym>DES</acronym> is
      offered primarily for compatibility reasons.</para>

    <sect2>
      <title>Recognizing Your Crypt Mechanism</title>

      <para>Currently the library supports <acronym>DES</acronym>,
      <acronym>MD5</acronym> and Blowfish hash
	functions.  By default &os; uses <acronym>MD5</acronym> to encrypt
	passwords.</para>

      <para>It is pretty easy to identify which encryption method 
	&os; is set up to use.  Examining the encrypted passwords in
	the <filename>/etc/master.passwd</filename> file is one way.
	Passwords encrypted with the <acronym>MD5</acronym> hash are longer
	than those encrypted with the <acronym>DES</acronym> hash and also
	begin with the characters <literal>&dollar;1&dollar;</literal>.  
	Passwords starting with <literal>&dollar;2a&dollar;</literal> are
	encrypted with the Blowfish hash function.  <acronym>DES</acronym>
	password strings do not have any particular identifying characteristics,
	but they are shorter than <acronym>MD5</acronym> passwords, and are
	coded in a 64-character alphabet which does not include the
	<literal>&dollar;</literal> character, so a relatively short string
	which does not begin with a dollar sign is very likely a
	<acronym>DES</acronym> password.</para>

      <para>The password format used for new passwords is controlled
	by the <literal>passwd_format</literal> login capability in
	<filename>/etc/login.conf</filename>, which takes values of
	<literal>des</literal>, <literal>md5</literal> or
	<literal>blf</literal>.  See the &man.login.conf.5; manual page
	for more information on login capabilities.</para>

    </sect2>
  </sect1>

      <secondary>one-time passwords</secondary>
    </indexterm>

    <para>By default, &os; includes support for
      <acronym role="One-Time Passwords In Everything">OPIE</acronym>
      (One-time Passwords In Everything), which uses the
      <acronym>MD5</acronym> hash by default.</para>

    <para>There are three different sorts of passwords which we will discuss
      below.  The first is your usual &unix; style or
      Kerberos password; we will call this a <quote>&unix; password</quote>.
      The second sort is the one-time password which is generated by the 
      <acronym>OPIE</acronym> &man.opiekey.1; program and accepted by the
      &man.opiepasswd.1; program and the login prompt; we will
      and the login prompt; we will
      call this a <quote>one-time password</quote>.  The final sort of
      password is the secret password which you give to the
      <command>opiekey</command> program (and


    <para>The secret password does not have anything to do with your &unix;
      password; they can be the same but this is not recommended.
      <acronym>OPIE</acronym> secret passwords are not limited to 8 characters
      like old &unix; passwords<footnote><para>Under &os; the standard login
      password may be up to 128 characters in length.</para></footnote>,
      they can be as long as you like.  Passwords of six or
      seven word long phrases are fairly common.  For the most part, the
      <acronym>OPIE</acronym> system operates completely independently of the
      &unix; password system.</para>

    <para>Besides the password, there are two other pieces of data that
      are important to <acronym>OPIE</acronym>.  One is what is known as the
      <quote>seed</quote> or <quote>key</quote>, consisting of two letters
      and five digits.  The other is what is called the <quote>iteration
      count</quote>, a number between 1 and 100.  <acronym>OPIE</acronym> 
      creates the one-time password by concatenating the seed and the secret 
      password, then applying the <acronym>MD5</acronym> hash as many times as
      specified by the iteration count and turning the result into six short 
      English words. These six English words are your one-time password.  The
      authentication system (primarily 
      <acronym role="Pluggable Authentication Modules">PAM</acronym>)
      keeps track of the last one-time password used, and the user is
      authenticated if the hash of the user-provided password is equal to
      the previous password.  Because a one-way hash is used it is
      impossible to generate future one-time passwords if a successfully
      used password is captured; the iteration count is decremented after
      each successful login to keep the user and the login program in
      sync.  When the iteration count gets down to 1, <acronym>OPIE</acronym>
      must be reinitialized.</para>

    <para>There are a few programs involved in each system
      which we will discuss below.  The

      count, a seed, and a secret password, and generates a one-time
      password or a consecutive list of one-time passwords.  The
      <command>opiepasswd</command>
      program is used to initialize <acronym>OPIE</acronym>,
      and to change passwords, iteration counts, or seeds; it
      takes either a secret passphrase, or an iteration count,
      seed, and a one-time password.  The


    <sect2>
      <title>Secure Connection Initialization</title>
      <para>To initialize <acronym>OPIE</acronym> for the first time, execute
        the <command>opiepasswd</command> command:</para>

      <screen>&prompt.user; <userinput>opiepasswd -c</userinput>
[grimreaper] ~ $ opiepasswd -f -c

    <sect2>
      <title>Generating a Single One-time Password</title>

      <para>Once you have initialized OPIE and login, you will be
	presented with a prompt like this:</para>

<screen>&prompt.user; <userinput>telnet example.com</userinput>

otp-md5 498 gr4269 ext
Password: </screen>

      <para>As a side note, the <acronym>OPIE</acronym> prompts have a useful
        feature (not shown here): if you press <keycap>Return</keycap>
	at the password prompt, the
	prompter will turn echo on, so you can see what you are
	typing.  This can be extremely useful if you are attempting to

    <sect2>
      <title>Restricting Use of &unix; Passwords</title>

      <para><acronym>OPIE</acronym> can restrict the use of &unix; passwords
        based on the IP address of a login session.  The relevant file
	is <filename>/etc/opieaccess</filename>, which is present by default.
	Please check &man.opieaccess.5;
	for more information on this file and which security considerations

    <title>TCP Wrappers</title>

    <para>Anyone familiar with &man.inetd.8; has probably heard
      of <acronym role="Transport Control Protocol">TCP</acronym>
      Wrappers at some point.  But few
      individuals seem to fully comprehend its usefulness in a
      network environment.  It seems that everyone wants to
      install a firewall to handle network connections.  While a

        during the era of restrictive export controls on cryptographic
        code from the USA.</para>

      <para>Alternatively, the 
        <acronym role="Massachusetts Insitute of Technology">MIT</acronym>
	implementation of Kerberos is available from the Ports Collection as
        <filename role="package">security/krb5</filename>.</para>
    </sect2>


Apr 30 11:23:22  Apr 30 19:23:22  krbtgt.EXAMPLE.COM@EXAMPLE.COM</screen>

      <para>Now try changing the password using &man.passwd.1; to
	check if the <application>kpasswd</application> daemon can get
	authorization to the Kerberos database:</para>

      <screen>&prompt.user; <userinput>passwd</userinput>

	programs that implement the program
	(<application>Kerberos</application> telnet, for example).  The
	current version of the protocol is version 5, described in
	<acronym role="Request For Comments">RFC</acronym>&nbsp;1510.</para>

      <para>Several free implementations of this protocol are available,
	covering a wide range of operating systems.  The Massachusetts

	<secondary>Key Distribution Center</secondary>
      </indexterm>

      <para>The Key Distribution Center 
        <acronym role="Key Distribution Center">KDC</acronym>) is the
	centralized authentication service that
	<application>Kerberos</application> provides &mdash; it is the
	computer that issues <application>Kerberos</application> tickets.

	      immediately upon running <command>kinit</command> &mdash;
	      even before you type your password!  The explanation is
	      that the <application>Kerberos</application> server freely
	      transmits a
	      <acronym role="Ticket Granting Ticket">TGT</acronym> (Ticket
	      Granting Ticket) to any unauthorized request;  however, every
	      <acronym>TGT</acronym> is encrypted in a key derived from
	      the user's password.  Therefore, when a user types their
	      password it is not being sent to the <acronym>KDC</acronym>,

	</sect3>

	<sect3>
	  <title>The <acronym>KDC</acronym> is a single point of failure</title>

	  <para>By design, the <acronym>KDC</acronym> must be as secure as
	    the master password database is contained on it.  The

	  <listitem>
	  <para><ulink
	    url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html">
	    The <application>Kerberos</application> <acronym>FAQ</acronym>
	    </ulink></para>
	</listitem>

	<listitem>

	</listitem>

	<listitem>
	  <para><ulink
	  url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">
	    <acronym>RFC</acronym> 1510, The <application>Kerberos</application>
	    Network Authentication Service (V5)</ulink></para>
	</listitem>

	<listitem>

    </note>

    <para>The version of <application>OpenSSL</application> included
      in &os; supports Secure Sockets Layer v2/v3 (
      <acronym role="Secure Sockets Layer">SSL</acronym>v2/
      <acronym>SSL</acronym>v3), Transport Layer Security v1 
      (<acronym role="Transport Layer Security">TLS</acronym>v1) network 
      security protocols and can be used as a general cryptographic library.
      </para>

    <note>
      <para>While <application>OpenSSL</application> supports the

      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 role="Certificate Authorities">CA</acronym>s, a warning is
      usually produced.  A Certificate Authority is a company, such as
      <ulink url="http://www.verisign.com">VeriSign</ulink>, which will
      sign certificates in order to validate credentials of individuals
      or companies.  This process has a cost associated with it and
      is definitely not a requirement for using certificates; however,


      <para>So what can these files do?  A good use would be to
	encrypt connections to the <application>Sendmail</application>
	<acronym role="Mail Transport Agent">MTA</acronym>.  This would
	dissolve 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

    </indexterm>

    <title>VPN over IPsec</title>
    <para>Creating a <acronym role="Virtual Private Network">VPN</acronym>
      between two networks, separated by the
      Internet, using FreeBSD gateways.</para>
 
    <sect2>

      <title>Understanding IPsec</title>

      <para>This section will guide you through the process of setting
	up <acronym role="IP Security">IPsec</acronym>, and to use it in an
	environment which consists of
	FreeBSD and <application>&microsoft.windows; 2000/XP</application>
	machines, to make them communicate securely.  In order to set up
	<acronym>IPsec</acronym>, it is necessary that you are familiar 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 
	(<acronym role="Internet Protocol"IP</acronym>) layer.  It allows two
	or more hosts to communicate in a secure manner (hence the name).  The
	FreeBSD <acronym>IPsec</acronym> <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>

      <note>
        <para>FreeBSD contains a <quote>hardware
        accelerated</quote> <acroonym>IPsec</acronym> stack, known as
	<quote>Fast IPsec</quote>, that was obtained from OpenBSD.  It employs
        cryptographic hardware (whenever possible) via the
        &man.crypto.4; subsystem to optimize the performance of
	<acronym>IPsec.</acronym>
        This subsystem is new, and does not support all the features
        that are available in the KAME version of <acronym>IPsec</acronym>.
	However, in order to enable hardware-accelerated
	<acronym>IPsec</acronym>, the following
        kernel option has to be added to your kernel configuration
        file:</para>



        <para> Note, that it is not currently possible to use the
	  <quote>Fast IPsec</quote> subsystem in lieu of the KAME
	  implementation of <acronym>IPsec</acronym>.  Consult the
	  &man.fast.ipsec.4; manual page for more information.</para>
      </note>

      <note>

	<secondary>AH</secondary>
      </indexterm>

      <para><acronym>IPsec</acronym> consists of two sub-protocols:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>Encapsulated Security Payload
	    (<acronym role="Encapsulated Security Payload">ESP</acronym>)
	    </emphasis>, protects the <acronym>IP</acronym> packet data from
	    third party interference, by encrypting the contents using
	    symmetric cryptography algorithms (like Blowfish,
	    <acronym>3DES</acronym>).</para>
        </listitem>
        <listitem>
          <para><emphasis>Authentication Header
	    (<acronym role="Authentication Header">AH</acronym>)</emphasis>,
	    protects the <acronym>IP</acronym> packet header from third party
	    interference and spoofing, by computing a cryptographic checksum
	    and hashing the <acronym>IP</acronym> packet header fields with a
	    secure hashing function.  This is then followed by an additional
	    header that contains the hash, to allow the information in the
	    packet to be authenticated.</para>
        </listitem>
      </itemizedlist>

	<see>VPN</see>
      </indexterm>

      <para><acronym>IPsec</acronym> 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 commonly
	known as a <emphasis>Virtual Private Network (<acronym>VPN</acronym>)
	</emphasis>. The &man.ipsec.4; manual page should be consulted for
	detailed information on the <acronym>IPsec</acronym> subsystem in
	&os;.</para>
      
      <para>To add <acronym>IPsec</acronym> support to your kernel, add the
        following options to your kernel configuration file:</para>

      <indexterm>
	<primary>kernel options</primary>

    <sect2>
      <title>The Problem</title>
 
      <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 have their own strengths and weaknesses.  This section
	presents a scenario, and the strategies used for implementing a
	<acronym>VPN</acronym> for this scenario.</para>
    </sect2>
    
    <sect2> 

          <para>You have at least two sites</para>
        </listitem>
        <listitem>
          <para>Both sites are using <acronym>IP</acronym> internally</para>
        </listitem>
        <listitem>
          <para>Both sites are connected to the Internet, through a
            gateway that is running FreeBSD.</para>
        </listitem>
        <listitem>
          <para>The gateway on each network has at least one public 
	    <acronym>IP</acronym>address.</para>
        </listitem>
        <listitem>
          <para>The internal addresses of the two networks can be
            public or private <acronym>IP</acronym> addresses, it does not
	    matter.  You can be running 
	    <acronym role="Network Address Translation">NAT</acronym> on the
	    gateway machine if necessary.</para>
        </listitem>
        <listitem>
          <para>The internal <acronym>IP</acronym> addresses of the two
	    networks <emphasis>do not collide</emphasis>.  While I expect it
	    is theoretically possible to use a combination of
	    <acronym>VPN</acronym> technology and <acronym>NAT</acronym>
	    to get this to work, I expect it to be a
            configuration nightmare.</para>
        </listitem>
      </itemizedlist>
      
      <para>If you find that you are trying to connect two networks,
        both of which, internally, use the same private <acronym>IP</acronym>
	address range (e.g. both of them use <hostid
        role="ipaddr">192.168.1.x</hostid>), then one of the networks will
        have to be renumbered.</para>
 

	</textobject>
      </mediaobject>
 
      <para>Notice the two public <acronym>IP</acronym> addresses.  I will use
        the letters to
        refer to them in the rest of this article.  Anywhere you see those
        letters in this article, replace them with your own public IP
        addresses.  Note also that internally, the two gateway
        machines have <hostid role="ipaddr">.1</hostid> <acronym>IP</acronym>
	addresses, and that the two networks have different private
	<acronym>IP</acronym> addresses  
	(<hostid role="ipaddr">192.168.1.x</hostid> and 
	<hostid role="ipaddr">192.168.2.x</hostid> respectively).  All the
        machines on the private networks have been configured to use the
        <hostid role="ipaddr">.1</hostid> machine as their default
        gateway.</para>

      <para>And the whole thing has to be secure.  This means that
        traffic between the two networks has to be encrypted.</para>
 
      <para>Creating a <acronym>VPN</acronym> between these two networks is a
        multi-step process.  The stages are as follows:</para>
 
      <orderedlist>
        <listitem>

        <listitem>
          <para>Configure additional software on the FreeBSD gateways,
            to allow &windows; machines to see one another across the
            <acronym>VPN</acronym>.</para>
        </listitem>
      </orderedlist>


        the public IP addresses, and two for the private IP
        addresses.</para>
 
      <para>Support for the <devicename>gif</devicename> device must be
        compiled in to the &os; kernel on both machines.  You can do this by
	adding the line:</para>
 
      <programlisting>device gif</programlisting>
 

        then compile, install, and reboot as normal.</para>
 
      <para>Configuring the tunnel is a two step process.  First the
        tunnel must be told what the outside (or public) <acronym>IP</acronym>
	addresses are, using &man.ifconfig.8;.  Then the private 
	<acronym>IP</acronym> addresses must be
        configured using &man.ifconfig.8;.</para>
 
      <para>On the gateway machine on network #1 you would run the

      </screen>

      <para>On the other gateway machine you run the same commands,
        but with the order of the <acronym>IP</acronym> addresses reversed.
	</para>

      <screen>&prompt.root; <userinput>ifconfig <replaceable>gif0</replaceable> create</userinput>
&prompt.root; <userinput>ifconfig <replaceable>gif0</replaceable> tunnel <replaceable>W.X.Y.Z</replaceable> <replaceable>A.B.C.D</replaceable></userinput>

        shortly.</para>
 
      <para>It is likely that you are running a firewall on both
        machines.  This will need to be circumvented for your 
	<acronym>VPN</acronym> traffic.  You might want to allow all traffic
	between both networks, or you might want to include firewall rules
	that protect both ends of the <acronym>VPN</acronym> from one
	another.</para>
 
      <para>It greatly simplifies testing if you configure the
        firewall to allow all traffic through the <acronym>VPN</acronym>.
	You can always tighten things up later.  If you are using &man.ipfw.8;
	on the gateway machines then a command like</para>

      <programlisting>ipfw add 1 allow ip from any to any via gif0</programlisting>
 

        VPN, without affecting your other firewall rules.  Obviously
        you will need to run this command on both gateway hosts.</para>
 
      <para>This is sufficient to allow each gateway machine to
        <command>ping</command> the other.  On
	<hostid role="ipaddr">192.168.1.1</hostid>, you should be able to run
	</para>
 
      <programlisting>ping 192.168.2.1</programlisting>
 

        thing on the other gateway machine.</para>
 
      <para>However, you will not be able to reach internal machines
        on either network yet.  This is because of the routing &mdash;
        although the gateway machines know how to reach one another,
        they do not know how to reach the network behind each one.</para>
 

        <hostid role="ipaddr">192.168.1.x</hostid> addresses
        instead.</para>
 
      <para><acronym>IP</acronym> traffic from hosts on one network will now
        be able to reach hosts on the other network.</para>
 
      <para>That has now created two thirds of a <acronym>VPN</acronym> between
        the two networks, in as much as it is <quote>virtual</quote> and it is
	a <quote>network</quote>.  It is not private yet.  You can test
        this using &man.ping.8; and &man.tcpdump.1;.  Log in to the
        gateway host and run</para>
 

16:10:26.029112 192.168.1.1 &gt; 192.168.2.1: icmp: echo reply
      </programlisting>
 
      <para>As you can see, the <acronym>ICMP</acronym> messages are going
        back and forth unencrypted.  If you had used the <option>-s</option>
	parameter to &man.tcpdump.1; to grab more bytes of data from the
	packets you would see more information.</para>
 
      <para>Obviously this is unacceptable.  The next section will
        discuss securing the link between the two networks so that it

    <sect3>
      <title>Step 2: Securing the link</title>
 
      <para>To secure the link we will be using <acronym>IPsec</acronym>.
        <acronym>IPsec</acronym> provides
        a mechanism for two hosts to agree on an encryption key, and to
        then use this key in order to encrypt data between the two
        hosts.</para>

        <listitem>
          <para>There must be a mechanism for specifying which traffic
            should be encrypted.  Obviously, you do not want to encrypt
            all your outgoing traffic &mdash; you only want to encrypt the
            traffic that is part of the <acronym>VPN</acronym>.  The rules
	    that you put in place to determine what traffic will be encrypted
	    are called <quote>security policies</quote>.</para>
         </listitem>
       </orderedlist>
 

         maintained by the kernel, and can be modified by userland
         programs.  However, before you can do this you must configure the
         kernel to support IPsec and the Encapsulated Security Payload
         (<acronym>ESP</acronym>) protocol.  This is done by configuring a
	 kernel with:</para>
 
       <indexterm>
	 <primary>kernel options</primary>

         associations.  You can configure them by hand between two hosts,
         which entails choosing the encryption algorithm, encryption keys,
         and so forth, or you can use daemons that implement the Internet
         Key Exchange protocol 
	 (<acronym role="Internet Key Exchange">IKE</acronym>) to do this
	 for you.</para>
 
       <para>I recommend the latter.  Apart from anything else, it is
         easier to set up.</para>

       <para>There are a number of choices for daemons to manage
         security associations with FreeBSD.  This article will describe
         how to use one of these, racoon&nbsp;&mdash; which is available from
	 <filename role="package">security/ipsec-tools</filename> in the &os;
	 Ports Collection.</para>
 
       <indexterm>
	 <primary>racoon</primary>
       </indexterm>

       <para>The <application>racoon</application> software must be run on 
         both gateway hosts.  On each host it is configured with the 
	 <acronym>IP</acronym> address of the other end of the
	 <acronym>VPN</acronym>, and a secret key (which you choose, and
	 must be the same on both gateways).</para>
 
       <para>The two daemons then contact one another, confirm that they
         are who they say they are (by using the secret key that you
         configured).  The daemons then generate a new secret key, and use
         this to encrypt the traffic over the <acronym>VPN</acronym>.  They
	 periodically
         change this secret, so that even if an attacker were to crack one
         of the keys (which is as theoretically close to unfeasible as it
         gets) it will not do them much good &mdash; by the time they have
	 cracked the key the two daemons have chosen another one.</para>
 
       <para>The configuration file for racoon is stored in
         <filename>${PREFIX}/etc/racoon</filename>.  You should find a

         key</quote>.</para>
 
       <para>The default racoon configuration expects to find this in
         the file <filename>${PREFIX}/etc/racoon/psk.txt</filename>.  It is
	 important to note that the pre-shared key is <emphasis>not</emphasis>
	 the key that will be used to encrypt your traffic across the 
	 <acronym>VPN</acronym> link, it is simply a token
         that allows the key management daemons to trust one another.</para>

       <para><filename>psk.txt</filename> contains a line for each

 
       <programlisting>W.X.Y.Z            secret</programlisting>
 
       <para>That is, the <emphasis>public</emphasis> <acronym>IP</acronym>
         address of the remote end, whitespace, and a text string that
	 provides the secret. Obviously, you should not use 
	 <quote>secret</quote> as your key &mdash; the normal
         rules for choosing a password apply.</para>
 
       <para>On gateway host #2 the line would look like this</para>
 
       <programlisting>A.B.C.D            secret</programlisting>
 
       <para>That is, the public <acronym>IP</acronym> address of the remote
         end, and the
         same secret key.  <filename>psk.txt</filename> must be mode
         <literal>0600</literal> (i.e., only read/write to
         <username>root</username>) before racoon will run.</para>
 
       <para>You must run racoon on both gateway machines.  You will
         also need to add some firewall rules to allow the
	 <acronym>IKE</acronym> traffic,
         which is carried over <acronym>UDP</acronym> to the 
	 <acronym role="Internet Security Association Key Management
Protocol">ISAKMP</acronym> (Internet Security Association
         Key Management Protocol) port.  Again, this should be fairly early in
         your firewall ruleset.</para>
 

       <para>Once racoon is running you can try pinging one gateway host
         from the other.  The connection is still not encrypted, but
         racoon will then set up the security associations between the two
         hosts &mdash; this might take a moment, and you may see this as a
         short delay before the ping commands start responding.</para>
 
       <para>Once the security association has been set up you can

         link.</para>
 
       <para>Each IP packet that you send out has a header that contains
         data about the packet.  The header includes the
	 <acronym>IP</acronym> addresses of both the source and destination.
	 As we already know, private <acronym>IP</acronym>
         addresses, such as the <hostid role="ipaddr">192.168.x.y</hostid>
         range are not supposed to appear on the public Internet.
         Instead, they must first be encapsulated inside another packet.
         This packet must have the public source and destination
	 <acronym>IP</acronym>
         addresses substituted for the private addresses.</para>
 
       <para>So if your outgoing packet started looking like this:</para>

 
       <para>This encapsulation is carried out by the
         <devicename>gif</devicename> device.  As
         you can see, the packet now has real <acronym>IP<acronym> addresses
	 on the outside,
         and our original packet has been wrapped up as data inside the
         packet that will be put out on the Internet.</para>
 
       <para>Obviously, we want all traffic between the
         <acronym>VPN</acronym>s to be
         encrypted.  You might try putting this in to words, as:</para>

       <para><quote>If a packet leaves from <hostid

         filename that contains configuration instructions.</para>
 
       <para>The configuration on gateway host #1 (which has the public
         <acronym>IP</acronym> address <hostid role="ipaddr">A.B.C.D</hostid>)
         to force all outbound traffic to <hostid role="ipaddr">W.X.Y.Z</hostid>
	 to be encrypted is:</para>
 
       <programlisting>
spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P out ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;

         to add a rule to the secure policy database.  The rest of this
         line specifies which packets will match this policy.  <hostid
         role="ipaddr">A.B.C.D/32</hostid> and <hostid
         role="ipaddr">W.X.Y.Z/32</hostid> are the <acronym>IP</acronym>
	 addresses and
         netmasks that identify the network or hosts that this policy will
         apply to.  In this case, we want it to apply to traffic between
         these two hosts.  <option>ipencap</option> tells the kernel that

         <option>out</option> in this case, and the necessary reversal of
         the IP addresses.</para>
 
       <para>The other gateway host (which has the public
         <acronym>IP</acronym> address <hostid role="ipaddr">W.X.Y.Z</hostid>)
         will need similar rules.</para>
 
       <programlisting>spdadd W.X.Y.Z/32 A.B.C.D/32 ipencap -P out ipsec esp/tunnel/W.X.Y.Z-A.B.C.D/require;
spdadd A.B.C.D/32 W.X.Y.Z/32 ipencap -P in ipsec esp/tunnel/A.B.C.D-W.X.Y.Z/require;</programlisting>
 
       <para>Finally, you need to add firewall rules to allow 
         <acronym>ESP</acronym> and <acronym>IPENCAP</acronym> packets back
	 and forth.  These rules will need to be added to both hosts.</para>
 
       <programlisting>ipfw add 1 allow esp from A.B.C.D to W.X.Y.Z
ipfw add 1 allow esp from W.X.Y.Z to A.B.C.D

	  </textobject>
	</mediaobject>

       <para>When they are received by the far end of the
         <acronym>VPN</acronym> they will
         first be decrypted (using the security associations that have
         been negotiated by racoon).  Then they will enter the
         <devicename>gif</devicename> interface, which will unwrap

 
       <programlisting>XXX tcpdump output</programlisting>
 
       <para>Now, as you can see, &man.tcpdump.1; shows the
         <acronym>ESP</acronym> packets.  If
         you try to examine them with the <option>-s</option> option you will see
         (apparently) gibberish, because of the encryption.</para>
 
      <para>Congratulations.  You have just set up a <acronym>VPN</acronym>
        between two remote sites.</para>
 
      <itemizedlist>
        <title>Summary</title>

          <para>Install <filename
            role="package">security/ipsec-tools</filename>.  Edit
            <filename>${PREFIX}/etc/racoon/psk.txt</filename> on both
            gateway hosts, adding an entry for the remote host's
	    <acronym>IP</acronym>
            address and a secret key that they both know.  Make sure
            this file is mode 0600.</para>
        </listitem>

</programlisting>
        </listitem>
        <listitem>
          <para>Add firewall rules to allow <acronym>IKE</acronym>,
	    <acronym>ESP</acronym>, and <acronym>IPENCAP</acronym>
            traffic to both hosts:</para>
 
          <programlisting>

        </listitem>
      </itemizedlist>

      <para>The previous two steps should suffice to get the
       <acronym>VPN</acronym> up and
        running.  Machines on each network will be able to refer to one
        another using <acronym>IP</acornym> addresses, and all traffic across
	the link will be automatically and securely encrypted.</para>
    </sect3> 
    </sect2> 
  </sect1>

      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, <acronym>TCP/IP</acronym>
      connections can be tunneled/forwarded securely through <acronym
      role="Secure Shell">SSH</acronym>.
      <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 <acronym>SSH</acronym> protocols 1 and 2.</para>

    <sect2>
      <title>Advantages of Using OpenSSH</title>


      <para>The login will continue just as it would have if a session was
        created using <command>rlogin</command> or
        <command>telnet</command>.  <acronym>SSH</acronym> 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
	<acronym>SSH</acronym> client
        will alert you if the saved fingerprint differs from the
        received fingerprint on future login attempts.  The fingerprints
        are saved in <filename>~/.ssh/known_hosts</filename>, or

	fingerprints.</para>

      <para>By default, recent versions of the
        <application>OpenSSH</application> servers 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 <option>-1</option> or

      <para>The arguments passed to &man.scp.1; are similar
	to &man.cp.1;, with the file or files in the first
	argument, and the destination in the second.  Since the file is
	fetched over the network, through <acronym>SSH</acronym>, one or
	more of the file arguments takes on the form
	<option>user@host:&lt;path_to_remote_file&gt;</option>.</para>

    </sect2>

      <title>ssh-keygen</title>

      <para>Instead of using passwords, &man.ssh-keygen.1; can
        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>
Generating public/private dsa key pair.

        <filename>~/.ssh/id_rsa.pub</filename>, respectively for DSA and
        RSA key types.  The public key must be placed in
        <filename>~/.ssh/authorized_keys</filename> of the remote
        machine in order for the setup to work.  Similarly,
	<acronym>RSA</acronym> version 1 public keys should be placed in
        <filename>~/.ssh/authorized_keys</filename>.</para>

      <para>This will allow connection 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 the

      <title>ssh-agent and ssh-add</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>


        launch <application>XFCE</application>, every time X11 starts.
        Then once that is done and X11 has been restarted so that the
        changes can take effect, simply run &man.ssh-add.1; to load
        all of your <acronym>SSH</acronym> keys.</para>
    </sect2>

    <sect2 id="security-ssh-tunneling">

	  <listitem>
	    <para>Forces <command>ssh</command> to use version 2 of
	      the protocol. (Do not use if you are working with older
	      <acronym>SSH</acronym> servers)</para>
	  </listitem>
	</varlistentry>


	  <term><option>user@foo.example.com</option></term>

	  <listitem>
	    <para>The remote <acronym>SSH</acronym> server.</para>
	  </listitem>
	</varlistentry>
      </variablelist>


      <para>A <acronym>SSH</acronym> tunnel works by creating a listen socket
        om <hostid>localhost</hostid> on the specified port.
	It then forwards any connection received
	on the local host/port via the <acronym>SSH</acronym> connection to
	the specified remote host and port.</para>

      <para>In the example, port <replaceable>5023</replaceable> on
	<hostid>localhost</hostid> is being forwarded to port
	<replaceable>23</replaceable> on <hostid>localhost</hostid>
	of the remote machine.  Since <replaceable>23</replaceable> is 
	<application>telnet</application>,
	this would create a secure <application>telnet</application> session
	through an <acronym>SSH</acronym> tunnel.</para>

      <para>This can be used to wrap any number of insecure
        <acronym>TCP</acronym> protocols such as <acronym>SMTP</acronym>,
	<acronym>POP3</acronym>, <acronym>FTP</acronym>, etc.</para>

      <example>
	<title>Using <acronym>SSH</acronym> to Create a Secure Tunnel for
	  <acronym>SMTP</acronym></title>

        <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput>
user@mailserver.example.com's password: <userinput>*****</userinput>


        <para>This can be used in conjunction with an
          &man.ssh-keygen.1; and additional user accounts to create a
          more seamless/hassle-free <acronym>SSH</acronym> tunneling
	  environment.  Keys can be used in place of typing a password, an
	  the tunnels can be run as a separate user.</para>
      </example>

      <sect3>
	<title>Practical <acronym>SSH</acronym> Tunneling Examples</title>

	<sect4>
	  <title>Secure Access of a <acronym>POP3</acronym> Server</title>

	  <para>At work, there is an <acronym>SSH</acronym> server that accepts
	    connections from the outside.  On the same office network
	    resides a mail server running a <acronym>POP3</acronym> server.
	    The network,
	    or network path between your home and office may or may not
	    be completely trustable.  Because of this, you need to check
	    your e-mail in a secure manner.  The solution is to create
	    an <command>ssh</command> connection to your office's
	    <acronym>SSH</acronym> server, and tunnel
	    through to the mail server.</para>

	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput>
user@ssh-server.example.com's password: <userinput>******</userinput></screen>

	  <para>When the tunnel is up and running, you can point your
	    mail client to send <acronym>POP3</acronym> requests to
	    <hostid>localhost</hostid>
	    port 2110.  A connection here will be forwarded securely across
	    the tunnel to <hostid>mail.example.com</hostid>.</para>
	</sect4>

	<sect4>
	  <title>Bypassing a draconian Firewall</title>

	  <para>Some network administrators impose extremely draconian
	    firewall rules, filtering not only incoming connections,
	    but outgoing connections.  You may be only given access
	    to contact remote machines on ports 22 and 80 for
	    <acronym>SSH</acronym> and web surfing.</para>

	  <para>You may wish to access another (perhaps non-work
	    related) service, such as an Ogg Vorbis server to stream
	    music.  If this Ogg Vorbis server is streaming on some other
	    port than 22 or 80, you will not be able to access it.</para>

	  <para>The solution is to create an <acronym>SSH</acronym> connection
	    to a machine outside of your network's firewall, and use it to
	    tunnel to the Ogg Vorbis server.</para>

	  <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput>
user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen>


    <para>In conjunction with file system enhancements like snapshots, FreeBSD 5.0
      and later offers the security of File System Access Control Lists
      (<acronym role="Access Control Lists">ACLs</acronym>).</para>

    <para>Access Control Lists extend the standard &unix;
      permission model in a highly compatible (&posix;.1e) way.  This feature

Return to bug 105456