uml_netjig.8

openswan

.TH UML_NETJIG 8 "16 June 2002"
.SH NAME
uml_netjig \- User Mode Linux network testing jig
.SH SYNOPSIS
.na
.nh
.HP
.ft B
uml_netjig
[\-\-help]
[\-\-arpreply]
[\-\-debug]
[\-\-exitonempty]
[\-\-tcpdump]
[\-\-playpublic
\fIfilename\fP]
[\-\-playprivate]
\fIfilename\fP]
[\-\-recordpublic]
\fIfilename\fP]
[\-\-recordprivate]
\fIfilename\fP]
[\-\-unix
\fIdirname\fP]
[\-\-startup
\fIprogram\fP]
.ft R
.HP
.ft B
uml_netjig 
[\-\-cmdproto]
.ft R
.hy
.ad
.SH DESCRIPTION
.BR uml_netjig
is an descendant of the User-Mode-Linux projects ``uml_switch'') program. It
has been extended to facilitate automated testing of networking code found
in a User-Mode-Linux guest kernel.

.BR whack
is an auxiliary program to allow requests to be made to a running
.BR pluto .
.LP
.BR pluto
is used to automatically build shared ``security associations'' on a
system that has IPsec, the secure IP protocol.
In other words,
.BR pluto
can eliminate much of the work of manual keying.
The actual
secure transmission of packets is the responsibility of other parts of
the system (see
.BR KLIPS ,
the companion implementation of IPsec).
\fIipsec_auto\fP(8) provides a more convenient interface to
\fBpluto\fP and \fBwhack\fP.
.SS IKE's Job
.LP
A \fISecurity Association\fP (\fISA\fP) is an agreement between two network nodes on
how to process certain traffic between them.  This processing involves
encapsulation, authentication, encryption, or compression.
.LP
IKE can be deployed on a network node to negotiate Security
Associations for that node.  These IKE implementations can only
negotiate with other IKE implementations, so IKE must be on each node
that is to be an endpoint of an IKE-negotiated Security Association.
No other nodes need to be running IKE.
.LP
An IKE instance (i.e. an IKE implementation on a particular network
node) communicates with another IKE instance using UDP IP packets, so
there must be a route between the nodes in each direction.
.LP
The negotiation of Security Associations requires a number of choices
that involve tradeoffs between security, convenience, trust, and
efficiency.  These are policy issues and are normally specified to the
IKE instance by the system administrator.
.LP
IKE deals with two kinds of Security Associations.  The first part of
a negotiation between IKE instances is to build an ISAKMP SA.  An
ISAKMP SA is used to protect communication between the two IKEs.
IPsec SAs can then be built by the IKEs \- these are used to carry
protected IP traffic between the systems.
.LP
The negotiation of the ISAKMP SA is known as Phase 1.  In theory,
Phase 1 can be accomplished by a couple of different exchange types,
but we only implement one called Main Mode (we don't implement
Aggressive Mode).
.LP
Any negotiation under the protection of an ISAKMP SA, including the
negotiation of IPsec SAs, is part of Phase 2.  The exchange type
that we use to negotiate an IPsec SA is called Quick Mode.
.LP
IKE instances must be able to authenticate each other as part of their
negotiation of an ISAKMP SA.  This can be done by several mechanisms
described in the draft standards.
.LP
IKE negotiation can be initiated by any instance with any other.  If
both can find an agreeable set of characteristics for a Security
Association, and both recognize each others authenticity, they can set
up a Security Association.  The standards do not specify what causes
an IKE instance to initiate a negotiation.
.LP
In summary, an IKE instance is prepared to automate the management of
Security Associations in an IPsec environment, but a number of issues
are considered policy and are left in the system administrator's hands.
.SS Pluto
.LP
\fBpluto\fP is an implementation of IKE.  It runs as a daemon on a network
node.  Currently, this network node must be a LINUX system running the
\fBKLIPS\fP implementation of IPsec.
.LP
\fBpluto\fP only implements a subset of IKE.  This is enough for it to
interoperate with other instances of \fBpluto\fP, and many other IKE
implementations.  We are working on implementing more of IKE.
.LP
The policy for acceptable characteristics for Security Associations is
mostly hardwired into the code of \fBpluto\fP (spdb.c).  Eventually
this will be moved into a security policy database with reasonable
expressive power and more convenience.
.LP
\fBpluto\fP uses shared secrets or RSA signatures to authenticate
peers with whom it is negotiating.
.LP
\fBpluto\fP initiates negotiation of a Security Association when it is
manually prodded: the program \fBwhack\fP is run to trigger this.
It will also initiate a negotiation when \fBKLIPS\fP traps an outbound packet
for Opportunistic Encryption.
.LP
\fBpluto\fP implements ISAKMP SAs itself.  After it has negotiated the
characteristics of an IPsec SA, it directs \fBKLIPS\fP to implement it.
It also invokes a script to adjust any firewall and issue \fIroute\fP(8)
commands to direct IP packets through \fBKLIPS\fP.
.LP
When \fBpluto\fP shuts down, it closes all Security Associations.
.SS Before Running Pluto
.LP
\fBpluto\fP runs as a daemon with userid root.  Before running it, a few
things must be set up.
.LP
\fBpluto\fP requires \fBKLIPS\fP, the FreeS/WAN implementation of IPsec.
All of the components of \fBKLIPS\fP and \fBpluto\fP should be installed.
.LP
\fBpluto\fP supports multiple public networks (that is, networks
that are considered insecure and thus need to have their traffic
encrypted or authenticated).  It discovers the
public interfaces to use by looking at all interfaces that are
configured (the \fB\-\-interface\fP option can be used to limit
the interfaces considered).
It does this only when \fBwhack\fP tells it to \-\-listen,
so the interfaces must be configured by then.  Each interface with a name of the form
\fBipsec\fP[\fB0\fP-\fB9\fP] is taken as a \fBKLIPS\fP virtual public interface.
Another network interface with the same IP address (there should be only
one) is taken as the corresponding real public
interface.  \fIifconfig\fP(8) with the \fB\-a\fP flag will show
the name and status of each network interface.
.LP
\fBpluto\fP requires a database of preshared secrets and RSA private keys.
This is described in the
.IR ipsec.secrets (5).
\fBpluto\fP is told of RSA public keys via \fBwhack\fP commands.
If the connection is Opportunistic, and no RSA public key is known,
\fBpluto\fP will attempt to fetch RSA keys using the Domain Name System.
.SS Setting up \fBKLIPS\fP for \fBpluto\fP
.LP
The most basic network topology that \fBpluto\fP supports has two security
gateways negotiating on behalf of client subnets.  The diagram of RGB's
testbed is a good example (see \fIklips/doc/rgb_setup.txt\fP).
.LP
The file \fIINSTALL\fP in the base directory of this distribution
explains how to start setting up the whole system, including \fBKLIPS\fP.
.LP
Make sure that the security gateways have routes to each other.  This
is usually covered by the default route, but may require issuing
.IR route (8)
commands.  The route must go through a particular IP
interface (we will assume it is \fIeth0\fP, but it need not be).  The
interface that connects the security gateway to its client must be a
different one.
.LP
It is necessary to issue a
.IR ipsec_tncfg (8)
command on each gateway.  The required command is:

\ \ \ ipsec tncfg \-\-attach\ \-\-virtual\ ipsec0 \-\-physical\ eth0

A command to set up the ipsec0 virtual interface will also need to be
run.  It will have the same parameters as the command used to set up
the physical interface to which it has just been connected using
.IR ipsec_tncfg (8).
.SS ipsec.secrets file
.LP
A \fBpluto\fP daemon and another IKE daemon (for example, another instance
of \fBpluto\fP) must convince each other that they are who they are supposed
to be before any negotiation can succeed.  This authentication is
accomplished by using either secrets that have been shared beforehand
(manually) or by using RSA signatures.  There are other techniques,
but they have not been implemented in \fBpluto\fP.
.LP
The file \fI/etc/ipsec.secrets\fP is used to keep preshared secret keys
and RSA private keys for
authentication with other IKE daemons.  For debugging, there is an
argument to the \fBpluto\fP command to use a different file.
This file is described in
.IR ipsec.secrets (5).
.SS Running Pluto
.LP
To fire up the daemon, just type \fBpluto\fP (be sure to be running as
the superuser).
The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons.
\fBpluto\fP must be run by the superuser to be able to use the UDP 500 port.
.LP
\fBpluto\fP attempts to create a lockfile with the name
\fI/var/run/pluto/pluto.pid\fP.  If the lockfile cannot be created,
\fBpluto\fP exits \- this prevents multiple \fBpluto\fPs from
competing  Any ``leftover'' lockfile must be removed before
\fBpluto\fP will run.  \fBpluto\fP writes its pid into this file so
that scripts can find it.  This lock will not function properly if it
is on an NFS volume (but sharing locks on multiple machines doesn't
make sense anyway).
.LP
\fBpluto\fP then forks and the parent exits.  This is the conventional
``daemon fork''.  It can make debugging awkward, so there is an option
to suppress this fork.
.LP
All logging, including diagnostics, is sent to
.IR syslog (3)
with facility=authpriv;
it decides where to put these messages (possibly in /var/log/secure).
Since this too can make debugging awkward, there is an option to
steer logging to stderr.
.LP
Once \fBpluto\fP is started, it waits for requests from \fBwhack\fP.
.SS Pluto's Internal State
.LP
To understand how to use \fBpluto\fP, it is helpful to understand a little
about its internal state.  Furthermore, the terminology is needed to decipher
some of the diagnostic messages.
.LP
The \fI(potential) connection\fP database describes attributes of a
connection.  These include the IP addresses of the hosts and client
subnets and the security characteristics desired.  \fBpluto\fP
requires this information (simply called a connection) before it can
respond to a request to build an SA.  Each connection is given a name
when it is created, and all references are made using this name.
.LP
During the IKE exchange to build an SA, the information about the
negotiation is represented in a \fIstate object\fP.  Each state object
reflects how far the negotiation has reached.  Once the negotiation is
complete and the SA established, the state object remains to represent
the SA.  When the SA is terminated, the state object is discarded.
Each State object is given a serial number and this is used to refer
to the state objects in logged messages.
.LP
Each state object corresponds to a connection and can be thought of
as an instantiation of that connection.
At any particular time, there may be any number of state objects
corresponding to a particular connection.
Often there is one representing an ISAKMP SA and another representing
an IPsec SA.
.LP
\fBKLIPS\fP hooks into the routing code in a LINUX kernel.
Traffic to be processed by an IPsec SA must be directed through
\fBKLIPS\fP by routing commands.  Furthermore, the processing to be
done is specified by \fIipsec eroute(8)\fP commands.
\fBpluto\fP takes the responsibility of managing both of these special
kinds of routes.
.LP
Each connection may be routed, and must be while it has an IPsec SA.
The connection specifies the characteristics of the route: the
interface on this machine, the ``gateway'' (the nexthop),
and the peer's client subnet.  Two
connections may not be simultaneously routed if they are for the same
peer's client subnet but use different interfaces or gateways
(\fBpluto\fP's logic does not reflect any advanced routing capabilities).
.LP
Each eroute is associated with the state object for an IPsec SA
because it has the particular characteristics of the SA.
Two eroutes conflict if they specify the identical local
and remote clients (unlike for routes, the local clients are
taken into account).
.LP
When \fBpluto\fP needs to install a route for a connection,
it must make sure that no conflicting route is in use.  If another
connection has a conflicting route, that route will be taken down, as long
as there is no IPsec SA instantiating that connection.
If there is such an IPsec SA, the attempt to install a route will fail.
.LP
There is an exception.  If \fBpluto\fP, as Responder, needs to install
a route to a fixed client subnet for a connection, and there is
already a conflicting route, then the SAs using the route are deleted
to make room for the new SAs.  The rationale is that the new
connection is probably more current.  The need for this usually is a
product of Road Warrior connections (these are explained later; they
cannot be used to initiate).
.LP
When \fBpluto\fP needs to install an eroute for an IPsec SA (for a
state object), first the state object's connection must be routed (if
this cannot be done, the eroute and SA will not be installed).
If a conflicting eroute is already in place for another connection,
the eroute and SA will not be installed (but note that the routing
exception mentioned above may have already deleted potentially conflicting SAs).
If another IPsec
SA for the same connection already has an eroute, all its outgoing traffic
is taken over by the new eroute.  The incoming traffic will still be
processed.  This characteristic is exploited during rekeying.
.LP
All of these routing characteristics are expected change when
\fBKLIPS\fP is modified to use the firewall hooks in the LINUX 2.4.x
kernel.
.SS Using Whack
.LP
\fBwhack\fP is used to command a running \fBpluto\fP.
\fBwhack\fP uses a UNIX domain socket to speak to \fBpluto\fP
(by default, \fI/var/pluto.ctl\fP).
.LP
\fBwhack\fP has an intricate argument syntax.
This syntax allows many different functions to be specified.
The help form shows the usage or version information.
The connection form gives \fBpluto\fP a description of a potential connection.
The public key form informs \fBpluto\fP of the RSA public key for a potential peer.
The delete form deletes a connection description and all SAs corresponding
to it.
The listen form tells \fBpluto\fP to start or stop listening on the public interfaces
for IKE requests from peers.
The route form tells \fBpluto\fP to set up routing for a connection;
the unroute form undoes this.
The initiate form tells \fBpluto\fP to negotiate an SA corresponding to a connection.
The terminate form tells \fBpluto\fP to remove all SAs corresponding to a connection,
including those being negotiated.
The status form displays the \fBpluto\fP's internal state.
The debug form tells \fBpluto\fP to change the selection of debugging output
``on the fly''.  The shutdown form tells
\fBpluto\fP to shut down, deleting all SAs.
.LP
Most options are specific to one of the forms, and will be described
with that form.  There are three options that apply to all forms.
.TP
\fB\-\-ctlbase\fP\ \fIpath\fP
\fIpath\fP.ctl is used as the UNIX domain socket for talking
to \fBpluto\fP.
This option facilitates debugging.
.TP
\fB\-\-optionsfrom\fP\ \fIfilename\fP