IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


NAME
       ipsec pluto - IPsec IKE keying daemon
       ipsec whack - control interface for IPSEC keying daemon

SYNOPSIS
       ipsec pluto [--help] [--version] [--optionsfrom filename]
	      [--nofork] [--stderrlog] [--noklips] [--uniqueids]
	      [--ikeport portnumber] [--ctlbase path]
	      [--secretsfile secrets-file] [--debug-none]
	      [--debug-all] [--debug-raw] [--debug-crypt]
	      [--debug-parsing] [--debug-emitting]
	      [--debug-control] [--debug-klips] [--debug-private]

       ipsec whack [--help] [--version]

       ipsec whack --name connection-name
	      [--id id] [--host ip-address]
	      [--ikeport port-number] [--nexthop ip-address]
	      [--client subnet] [--updown updown]
	      --to
	      [--id id] [--host ip-address]
	      [--ikeport port-number] [--nexthop ip-address]
	      [--client subnet] [--updown updown]
	      [--psk] [--rsasig] [--encrypt] [--authenticate]
	      [--compress] [--tunnel] [--pfs] [--ipv4] [--ipv6]
	      [--tunnelipv4] [--tunnelipv6]
	      [--ikelifetime seconds] [--ipseclifetime seconds]
	      [--rekeymargin seconds] [--rekeyfuzz percentage]
	      [--keyingtries count] [--delete] [--ctlbase path]
	      [--optionsfrom filename] [--label string]

       ipsec whack --keyid id [--pubkeyrsa key] [--ctlbase path]
	      [--optionsfrom filename] [--label string]

       ipsec whack --listen|--unlisten [--ctlbase path]
	      [--optionsfrom filename] [--label string]

       ipsec whack --route|--unroute --name connection-name
	      [--ctlbase path] [--optionsfrom filename]
	      [--label string]

       ipsec whack --initiate|--terminate --name connection-name
	      [--asynchronous] [--ctlbase path]
	      [--optionsfrom filename] [--label string]

       ipsec whack --delete --name connection-name
	      [--ctlbase path] [--optionsfrom filename]
	      [--label string]

       ipsec whack [--name connection-name] [--debug-none]
	      [--debug-all] [--debug-raw] [--debug-crypt]
	      [--debug-parsing] [--debug-emitting]
	      [--debug-control] [--debug-klips] [--debug-private]
	      [--ctlbase path] [--optionsfrom filename]



			  28 March 1999				1





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


	      [--label string]

       ipsec whack --status [--ctlbase path]
	      [--optionsfrom filename] [--label string]

       ipsec whack --shutdown [--ctlbase path]
	      [--optionsfrom filename] [--label string]

DESCRIPTION
       pluto is an IKE (``IPsec Key Exchange'') daemon.	 whack is
       an auxiliary program to allow requests to  be  made  to	a
       running pluto.

       pluto is used to automatically build shared ``security as-
       sociations'' on a system that has  IPsec,  the  secure  IP
       protocol.  In other words, 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  KLIPS,  the  companion  implementation  of	  IPsec).
       ipsec_auto(8) provides a more convenient interface to plu-
       to and whack.

   IKE's Job
       A Security Association (SA) is an  agreement  between  two
       network	nodes  on  how to process certain traffic between
       them.  This processing involves encapsulation, authentica-
       tion, encryption, or compression.

       IKE can be deployed on a network node to negotiate Securi-
       ty 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.

       An IKE instance (i.e. an IKE implementation on a	 particu-
       lar  network  node) communicates with another IKE instance
       using UDP IP packets, so there must be a route between the
       nodes in each direction.

       The negotiation of Security Associations requires a number
       of choices that involve tradeoffs between security, conve-
       nience,	trust,	and  efficiency.  These are policy issues
       and are normally specified to the IKE instance by the sys-
       tem administrator.

       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 com-
       munication between the two IKEs.	 IPsec SAs  can	 then  be
       built  by  the IKEs - these are used to carry protected IP
       traffic between the systems.

       The negotiation of the ISAKMP SA is known as Phase 1.   In



			  28 March 1999				2





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       theory, Phase 1 can be accomplished by a couple of differ-
       ent exchange types, but we only implement one called  Main
       Mode (we don't implement Aggressive Mode).

       Any  negotiation under the protection of an ISAKMP SA, in-
       cluding 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.

       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  stan-
       dards.

       IKE  negotiation can be initiated by any instance with any
       other.  If both can find an agreeable set of  characteris-
       tics  for  a Security Association, and both recognize each
       others authenticity, they can set up a  Security	 Associa-
       tion.  The standards do not specify what causes an IKE in-
       stance to initiate a negotiation.

       In summary, an IKE instance is prepared	to  automate  the
       management  of  Security Associations in an IPsec environ-
       ment, but a number of issues are considered policy and are
       left in the system administrator's hands.

   Pluto
       pluto 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 KLIPS implementation of IPsec.

       pluto only implements a subset of IKE.  This is enough for
       it to interoperate with other instances of pluto, and many
       other IKE implementations.  We are working on implementing
       more of IKE.

       The policy for acceptable characteristics for Security As-
       sociations  is  mostly  hardwired  into	the code of pluto
       (spdb.c).  Eventually this will be moved into  a	 security
       policy  database with reasonable expressive power and more
       convenience.

       pluto uses shared secrets or RSA signatures  to	authenti-
       cate  peers  with whom it is negotiating.  In future other
       techniques will be supported.

       pluto initiates negotiation of a Security Association when
       it  is manually prodded: the program whack is run to trig-
       ger this.  Eventually, more convenient and  useful  mecha-
       nisms will be implemented.

       pluto  implements ISAKMP SAs itself.  After it has negoti-
       ated the characteristics of an IPsec SA, it directs  KLIPS
       to  implement it.  It also issues route(8) commands to di-



			  28 March 1999				3





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       rect messages through KLIPS.

       When pluto shuts down, it  closes  all  Security	 Associa-
       tions.

   Before Running Pluto
       pluto  runs  as a daemon with userid root.  Before running
       it, a few things must be set up.

       pluto requires  KLIPS,  the  FreeS/WAN  implementation  of
       IPsec.  All of the components of KLIPS and pluto should be
       installed.

       pluto 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.	It does this only when whack tells it  to
       --listen,  so  the  interfaces must be configured by then.
       Each interface with a name of the form ipsec[0-9] is taken
       as  a KLIPS virtual public interface.  Another network in-
       terface with the same IP address	 (there	 should	 be  only
       one)  is taken as the corresponding real public interface.
       ifconfig(8) with the -a flag will show the name and status
       of each network interface.

       pluto  requires	a  database  of preshared secrets and RSA
       private keys.  This is described in the	ipsec.secrets(5).
       pluto is told of RSA public keys via whack commands.

   Setting up KLIPS for pluto
       The  most  basic	 network topology that pluto supports has
       two security gateways negotiating on behalf of client sub-
       nets.  The diagram of RGB's testbed is a good example (see
       klips/doc/rgb_setup.txt).

       The file INSTALL in the base directory of  this	distribu-
       tion  explains  how  to start setting up the whole system,
       including KLIPS.

       Make sure that the security gateways have routes	 to  each
       other.	This is usually covered by the default route, but
       may require issuing route(8) commands.  The route must  go
       through a particular ethernet interface (we will assume it
       is eth0, but it need not be).  The interface that connects
       the  security  gateway  to  its client must be a different
       one.

       It is necessary to issue a 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



			  28 March 1999				4





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       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 ipsec_tncfg(8).

   ipsec.secrets file
       A pluto daemon and another IKE daemon (for example, anoth-
       er  instance  of pluto) must convince each other that they
       are who they are supposed to be before any negotiation can
       succeed.	 This authentication is accomplished by using ei-
       ther secrets that have been shared  beforehand  (manually)
       or  by  using RSA signatures.  There are other techniques,
       but they have not been implemented in pluto.

       The file /etc/ipsec.secrets is used to keep preshared  se-
       cret  keys  and	RSA  private keys for authentication with
       other IKE daemons.  For debugging, there is an argument to
       the  pluto  command to use a different file.  This file is
       described in ipsec.secrets(5).

   Running Pluto
       To fire up the daemon, just type pluto (be sure to be run-
       ning  as	 the  superuser).  The default IKE port number is
       500, the UDP port assigned by IANA for IKE Daemons.  pluto
       must be run by the superuser to be able to use the UDP 500
       port.

       pluto  attempts	to  create  a  lockfile	 with  the   name
       /var/run/pluto.pid.   If	 the  lockfile cannot be created,
       pluto exits - this prevents multiple plutos from competing
       Any  ``leftover''  lockfile  must  be removed before pluto
       will run.  pluto 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).

       pluto  then  forks and the parent exits.	 This is the con-
       ventional ``daemon fork''.  It can make debugging awkward,
       so there is an option to suppress this fork.

       All  logging, including diagnostics, is sent to syslog(3);
       it decides  where  to  put  these  messages  (possibly  in
       /var/log/secure).   Since this too can make debugging awk-
       ward, there is an option to steer logging to stderr.

       Once pluto is started, it waits for requests from whack.

   Pluto's Internal State
       To understand how to use pluto, it is  helpful  to  under-
       stand a little about its internal state.	 Furthermore, the
       terminology is needed to decipher some of  the  diagnostic
       messages.

       The  (potential)	 connection database describes attributes
       of a connection.	 These include the IP  addresses  of  the



			  28 March 1999				5





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       hosts  and client subnets and the security characteristics
       desired.	 pluto 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.

       During  the  IKE	 exchange to build an SA, the information
       about the negotiation is represented in	a  state  object.
       Each  state  object  reflects  how far the negotiation has
       reached.	 Once the negotiation is complete and the SA  es-
       tablished,  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.

       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.

       KLIPS  hooks  into  the	routing	 code  in a LINUX kernel.
       Traffic to be processed by an IPsec SA  must  be	 directed
       through	KLIPS by routing commands.  Furthermore, the pro-
       cessing to be done is specified by  ipsec  eroute(8)  com-
       mands.  pluto takes the responsibility of managing both of
       these special kinds of routes.

       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 connec-
       tions may not be simultaneously routed if they are for the
       same  peer's client subnet but use different interfaces or
       gateways (pluto's logic	does  not  reflect  any	 advanced
       routing capabilities).

       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 identi-
       cal local and remote clients (unlike for routes, the local
       clients are taken into account).

       When  pluto  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  in-
       stantiating  that  connection.	If there is such an IPsec
       SA, the attempt to install a route will fail.

       There is an exception.  If pluto, 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 us-



			  28 March 1999				6





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       ing  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  can-
       not be used to initiate).

       When pluto 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  men-
       tioned  above  may  have	 already deleted potentially con-
       flicting SAs).  If another IPsec SA for the  same  connec-
       tion  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 dur-
       ing rekeying.

       All of these routing characteristics are	 expected  change
       when  KLIPS  is	modified to use the firewall hooks in the
       LINUX 2.4.x kernel.

   Using Whack
       whack is used to command a running pluto.   whack  uses	a
       UNIX   domain  socket  to  speak	 to  pluto  (by	 default,
       /var/pluto.ctl).

       whack has an intricate argument syntax.	This  syntax  al-
       lows  many  different functions to be specified.	 The help
       form shows the usage or version information.  The  connec-
       tion form gives pluto a description of a potential connec-
       tion.  The public key form informs pluto of the RSA public
       key  for a potential peer.  The delete form deletes a con-
       nection description and all SAs corresponding to it.   The
       listen  form tells pluto to start or stop listening on the
       public interfaces for IKE requests from peers.  The  route
       form  tells  pluto to set up routing for a connection; the
       unroute form undoes this.  The initiate form  tells  pluto
       to  negotiate  an  SA  corresponding to a connection.  The
       terminate form tells pluto to remove all SAs corresponding
       to  a  connection,  including those being negotiated.  The
       status form displays the pluto's internal state.	 The  de-
       bug  form tells pluto to change the selection of debugging
       output ``on the fly''.  The shutdown form tells	pluto  to
       shut down, deleting all SAs.

       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.

       --ctlbase path
	      path.ctl	is  used  as  the  UNIX domain socket for
	      talking to pluto.	 This option  facilitates  debug-



			  28 March 1999				7





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


	      ging.

       --optionsfrom filename
	      adds the contents of the file to the argument list.

       --label string
	      adds the string to all error messages generated  by
	      whack.

       The help form of whack is self-explanatory.

       --help display the usage message.

       --version
	      display the version of whack.

       The  connection	form  describes a potential connection to
       pluto.  pluto needs  to	know  what  connections	 can  and
       should  be  negotiated.	 When  pluto is the initiator, it
       needs to know what to propose.  When pluto is the  respon-
       der, it needs to know enough to decide whether is is will-
       ing to set up the proposed connection.

       The description of a potential connection  can  specify	a
       large  number  of  details.   Each connection has a unique
       name.  This name will appear in a updown shell command, so
       it should not contain punctuation that would make the com-
       mand ill-formed.

       --name connection-name

       The topology of circuit is symmetric,  so  to  save  space
       here is half a picture:

	  client_subnet<-->host:ikeport<-->nexthop<---

       A similar trick is used in the flags.  The same flag names
       are used for both ends.	Those before the  --to	flag  de-
       scribe  the  left  side	and those afterwards describe the
       right side.  When pluto attempts to use the connection, it
       decides	whether	 it is the left side or the right side of
       the connection, based on the IP numbers of its interfaces.

       --id id
	      the identity of the end.	Currently, this can be an
	      IP address (specified as dotted quad or as a  Fully
	      Qualified Domain Name, which will be resolved imme-
	      diately) or as a Fully Qualified Domain Name itself
	      (prefixed by ``@'' to signify that it should not be
	      resolved), or as user@FQDN.  pluto  only	authenti-
	      cates  the  identity,  and  does not use it for ad-
	      dressing, so, for example, an IP address	need  not
	      be the one to which packets are to be sent.  If the
	      option is absent, the identity defaults to  the  IP



			  28 March 1999				8





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


	      address specified by --host.

       --host ip-address
	      the IP address of the end (generally the public in-
	      terface).	 If pluto is to act as	a  responder  for
	      IKE negotiations initiated from unknown IP address-
	      es (the ``Road  Warrior''	 case),	 the  IP  address
	      should  be  specified as %any (currently, the obso-
	      lete notation 0.0.0.0 is also accepted for this).

       --ikeport port-number
	      the UDP port that IKE listens to on that host.  The
	      default  is  500.	  (pluto on this machine uses the
	      port specified by its own command line argument, so
	      this only affects where pluto sends messages.)

       --nexthop ip-address
	      where  to route packets for the peer's client (pre-
	      sumably for the peer too, but it will not	 be  used
	      for this).  When pluto installs an IPsec SA, it is-
	      sues a route command.  It uses the nexthop  as  the
	      gateway.	 The  default  is  the	peer's IP address
	      (this can be explicitly written as %direct; the ob-
	      solete  notation 0.0.0.0 is accepted).  This option
	      is necessary if pluto's host's interface	used  for
	      sending  packets	to  the peer is neither point-to-
	      point nor directly connected to the peer.

       --client subnet
	      the subnet for which the IPsec traffic will be des-
	      tined.   If  not	specified,  the	 host will be the
	      client.  The subnet can be specified in any of  the
	      forms supported by ipsec_atosubnet(3).  The general
	      form is address/mask.  The address can be either	a
	      domain  name  or	four  decimal numbers (specifying
	      octets) separated by  dots.   The	 most  convenient
	      form  of	the mask is a decimal integer, specifying
	      the number of leading one bits in	 the  mask.   So,
	      for  example,  10.0.0.0/8 would specify the class A
	      network ``Net 10''.

       --updown updown
	      specifies an external shell command to be run when-
	      ever  pluto  brings  up  or down a connection.  The
	      script is used to build a shell command, so it  may
	      contain  positional  parameters,	but  ought not to
	      have punctuation that  would  cause  the	resulting
	      command  to  be  ill-formed.   The default is ipsec
	      _updown.

       --to   separates the specification of the left  and  right
	      ends of the connection.

       The  potential connection description also specifies char-



			  28 March 1999				9





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       acteristics of rekeying and security.

       --psk  Propose and allow preshared  secret  authentication
	      for  IKE	peers.	This authentication requires that
	      each side use the same  secret.	May  be	 combined
	      with --rsasig.  pluto supported for a long time.

       --rsasig
	      Propose and allow RSA signatures for authentication
	      of IKE peers.  This  authentication  requires  that
	      each  side  have	have a private key of its own and
	      know the public key of its peer.	May  be	 combined
	      with --psk.

       If  neither --rsasig nor --psk is specified, the initiator
       will default to proposing those for which it has	 the  re-
       quired keying material.	The responder defaults similarly,
       but does not know the identity of  the  initiator  (except
       for its IP address), so it is willing to accept RSA Sig if
       it is proposed (PSK cannot use the  Identity  payload,  so
       the responder does know if it can handle PSK).

       --encrypt
	      All  proposed  or	 accepted  IPsec SAs will include
	      non-null ESP.  The actual choices of transforms are
	      wired into pluto.

       --authenticate
	      All  proposed  IPsec  SAs will include AH.  All ac-
	      cepted IPsec SAs will include AH or  ESP	with  au-
	      thentication.  The actual choices of transforms are
	      wired into pluto.	 Note that this has nothing to do
	      with IKE authentication.

       --compress
	      All  proposed  IPsec  SAs will include IPCOMP (com-
	      pression).

       --tunnel
	      the IPsec SA should use tunneling.  Implicit if the
	      SA  is  for  clients.  Must only be used with --au-
	      thenticate or --encrypt.

       --ipv4 The host addresses will be interpreted as IPv4  ad-
	      dresses.	 This  is  the	default.  Note that for a
	      connection, all host addresses must be of the  same
	      Address Family (IPv4 and IPv6 use different Address
	      Families).

       --ipv6 The host addresses (including nexthop) will be  in-
	      terpreted	 as IPv6 addresses.  Note that for a con-
	      nection, all host addresses must be of the same Ad-
	      dress  Family  (IPv4 and IPv6 use different Address
	      Families).



			  28 March 1999			       10





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       --tunnelipv4
	      The client addresses will be  interpreted	 as  IPv4
	      addresses.   The	default is to match what the host
	      will be.	This does not imply --tunnel so the  flag
	      can be safely used when no tunnel is actually spec-
	      ified.  Note that for a connection, all tunnel  ad-
	      dresses must be of the same Address Family.

       --tunnelipv6
	      The  client  addresses  will be interpreted as IPv6
	      addresses.  The default is to match what	the  host
	      will  be.	 This does not imply --tunnel so the flag
	      can be safely used when no tunnel is actually spec-
	      ified.   Note that for a connection, all tunnel ad-
	      dresses must be of the same Address Family.

       --pfs  There should be Perfect Forward Secrecy - new  key-
	      ing  material  will  be generated for each IPsec SA
	      rather than being derived from the ISAKMP SA keying
	      material.	 Since the group to be used cannot be ne-
	      gotiated (a dubious feature of the standard), pluto
	      will  propose  the  same group that was used during
	      Phase 1.	We don't implement a stronger form of PFS
	      which  would  require that the ISAKMP SA be deleted
	      after the IPSEC SA is negotiated.

       If none of the --encrypt, --authenticate,  --compress,  or
       --pfs  flags  is given, the initiating the connection will
       only build an ISAKMP SA.

       More work is needed to allow for flexible policies.   Cur-
       rently policy is hardwired in the source file spdb.c.  The
       ISAKMP SAs may use Oakley groups	 MODP1024  and	MODP1536;
       3DES  encryption;  SHA1-96 and MD5-96 authentication.  The
       IPsec SAs may use 3DES and MD5-96 or SHA1-96 for	 ESP,  or
       just  MD5-96 or SHA1-96 for AH.	IPCOMP Compression is al-
       ways Deflate.

       --ikelifetime seconds
	      how long pluto will propose that an  ISAKMP  SA  be
	      allowed  to  live.   The default is 3600 (one hour)
	      and the maximum is 28800 (8  hours).   This  option
	      will  not	 affect what is accepted.  pluto will re-
	      ject proposals that exceed the maximum.

       --ipseclifetime seconds
	      how long pluto will propose that an IPsec SA be al-
	      lowed  to live.  The default is 28800 (eight hours)
	      and the maximum is 86400 (one  day).   This  option
	      will  not	 affect what is accepted.  pluto will re-
	      ject proposals that exceed the maximum.

       --rekeymargin seconds
	      how long before an SA's expiration should pluto try



			  28 March 1999			       11





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


	      to negotiate a replacement SA.  This will only hap-
	      pen if pluto was the initiator.  The default is 540
	      (nine minutes).

       --rekeyfuzz percentage
	      maximum  size  of random component to add to rekey-
	      margin, expressed as a percentage	 of  rekeymargin.
	      pluto  will  select  a  delay uniformly distributed
	      within this range.  By default, the percentage will
	      be 100.  If greater determinism is desired, specify
	      0.  It may be appropriate for the percentage to  be
	      much larger than 100.

       --keyingtries count
	      how many times pluto should try to negotiate an SA,
	      either for the first time or for rekeying.  A value
	      of  0  is interpreted as a very large number: never
	      give up.	The default is three.

       --delete
	      when used in the connection  form,  it  causes  any
	      previous	connection  with  this name to be deleted
	      before this one is added.	 Unlike a normal  delete,
	      no  diagnostic is produced if there was no previous
	      connection to delete.  Any routing in place for the
	      connection is undone.

       The delete form deletes a named connection description and
       any SAs established or negotiations initiated  using  this
       connection.   Any  routing  in place for the connection is
       undone.

       --delete

       --name connection-name

       The route form of the whack command tells pluto to set  up
       routing	for  a	connection.   Although like a traditional
       route, it uses an ipsec device  as  a  virtual  interface.
       Once  routing  is set up, no packets will be sent ``in the
       clear'' to the peer's client specified in the  connection.
       An explicit whack route is not always needed: if it hasn't
       been done when an IPsec SA is being installed, one will be
       automatically attempted.

       When  a	routing is attempted for a connection, there must
       not already be a routing for a different	 connection  with
       the same subnet but different interface or destination, or
       if there is, it must not be being used  by  an  IPsec  SA.
       Otherwise the attempt will fail.

       --route





			  28 March 1999			       12





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       --name connection-name

       The  unroute form of the whack command tells pluto to undo
       a routing.  pluto will refuse if an IPsec SA is using  the
       connection.   If	 another  connection  is sharing the same
       routing, it will be left in  place.   Without  a	 routing,
       packets will be sent without encryption or authentication.

       --unroute

       --name connection-name

       The initiate form tells pluto to	 initiate  a  negotiation
       with  another pluto (or other IKE daemon) according to the
       named  connection.   Initiation	requires  a  route   that
       --route	would provide; if none is in place at the time an
       IPsec SA is being installed, pluto attempts to set one up.

       --initiate

       --name connection-name

       --asynchronous

       The  initiate  form  of	the whack command will relay back
       from pluto status information via the UNIX  domain  socket
       (unless --asynchronous is specified).  The status informa-
       tion is meant to look a bit like that from FTP.	Currently
       whack  simply  copies this to stderr.  When the request is
       finished (eg. the SAs are established or pluto gives  up),
       pluto closes the channel, causing whack to terminate.

       The  terminate form tells pluto to delete any SAs that use
       the specified connection and to stop any	 negotiations  in
       process.	 It does not prevent new negotiations from start-
       ing (the delete form has this effect).

       --terminate

       --name connection-name

       The public key for informs pluto of the RSA public key for
       a  potential  peer.   Private keys must be kept secret, so
       they are kept in ipsec.secrets(5).

       --keyid id
	      specififies the identity of the peer  for	 which	a
	      public  key  should be used.  Its form is identical
	      to the identity in the connection.   If  no  public
	      key  is  specified,  pluto  attempts  to find a KEY
	      record from DNS for the id (if a FQDN)  or  through
	      reverse lookup (if an IP address).  Note that there
	      several interesting ways in which this is	 not  se-
	      cure.



			  28 March 1999			       13





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       --pubkeyrsa key
	      specifies the value of the RSA public key.  It is a
	      sequence	of  bytes  as  described  in   RFC   2537
	      ``RSA/MD5	 KEYs  and SIGs in the Domain Name System
	      (DNS)''.	It is  denoted	in  a  way  suitable  for
	      ipsec_atodata(3).	  For  example, a base 64 numeral
	      starts with 0s.

       The listen form tells pluto to start listening for IKE re-
       quests  on  its	public	interfaces.  To avoid race condi-
       tions, it is normal to load  the	 appropriate  connections
       into  pluto  before allowing it to listen.  If pluto isn't
       listening, it is pointless to initiate negotiations, so it
       will  refuse  requests to do so.	 Whenever the listen form
       is used, pluto looks for public interfaces and will notice
       when  new ones have been added and when old ones have been
       removed.	 This is also the trigger for pluto to	read  the
       ipsec.secrets  file.  So listen may useful more than once.

       --listen
	      start listening for IKE traffic  on  public  inter-
	      faces.

       --unlisten
	      stop  listening  for  IKE	 traffic on public inter-
	      faces.

       The status form will display information about the  inter-
       nal  state of pluto: information about each potential con-
       nection and about each state object.

       --status

       The shutdown form is the proper way to  shut  down  pluto.
       It  will	 tear down the SAs on this machine that pluto has
       negotiated.  It does not inform its peers, so the  SAs  on
       their machines remain.

       --shutdown

   Examples
       It  would  be  normal  to start pluto in one of the system
       initialization scripts.	It needs to be run by  the  supe-
       ruser.	Generally,  no	arguments  are needed.	To run in
       manually, the superuser can simply type

	  ipsec pluto

       The command will immediately return, but a  pluto  process
       will be left running, waiting for requests from whack or a
       peer.

       Using whack, several potential connections  would  be  de-
       scribed:



			  28 March 1999			       14





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


	  ipsec whack --name silly --host 127.0.0.1 --to
	      --host 127.0.0.2 --ikelifetime 900
	      --ipseclifetime 800 --keyingtries 3

       Since  this silly connection description specifies neither
       encryption, authentication, nor tunneling, it  could  only
       be used to establish an ISAKMP SA.

	  ipsec whack --name secret --host 10.0.0.1
	      --client 10.0.1.0/24 --to --host 10.0.0.2
	      --client 10.0.2.0/24 --encrypt

       This is something that must be done on both sides.  If the
       other side is pluto, the same whack command could be  used
       on  it  (the command syntax is designed to not distinguish
       which end is ours).

       Now that the connections are specified, pluto is ready  to
       handle requests and replies via the public interfaces.  We
       must tell it to discover those interfaces  and  start  ac-
       cepting messages from peers:

	  ipsec whack --listen

       If  we don't immediately wish to bring up a secure connec-
       tion between the two clients, we might wish to prevent in-
       secure  traffic.	 The routing form asks pluto to cause the
       packets sent from our client to the peer's  client  to  be
       routed  through the ipsec0 device; if there is no SA, they
       will be discarded:

	  ipsec whack --route secret

       Finally, we are ready to get pluto to initiate negotiation
       for an IPsec SA (and implicitly, an ISAKMP SA):

	  ipsec whack --initiate --name secret

       A  small log of interesting events will appear on standard
       output (other logging is sent to syslog).

       whack can also be used to terminate pluto cleanly, tearing
       down all SAs that it has negotiated.

	  ipsec whack --shutdown

       At  this time, the tearing down is all local: no notifica-
       tion is given to the peers.

   The updown command
       Whenever pluto brings a connection up or down, it  invokes
       the  updown  command.  This command is specified using the
       --updown option.	 This allows for customized control  over
       routing and firewall manipulation.



			  28 March 1999			       15





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       The updown is invoked for five different operations.  Each
       of these operations can be for our client  subnet  or  for
       our host itself.

       prepare-host or prepare-client
	      is  run  before  bringing up a new connection if no
	      other connection with the same clients is up.  Gen-
	      erally,  this  is	 useful for deleting a route that
	      might have been set up before pluto was run or per-
	      haps by some agent not known to pluto.

       route-host or route-client
	      is run when bringing up a connection for a new peer
	      client subnet (even  if  prepare-host  or	 prepare-
	      client  was  run).   The	command	 should install a
	      suitable route.  Routing decisions are  based  only
	      on  the destination (peer's client) subnet address,
	      unlike eroutes which discriminate based  on  source
	      too.

       unroute-host or unroute-client
	      is run when bringing down the last connection for a
	      particular peer client subnet.  It should undo what
	      the route-host or route-client did.

       up-host or up-client
	      is  run  when bringing up an eroute with a new pair
	      of client subnets (technically: when an  eroute  is
	      being  added  (not replaced)).  This command should
	      install firewall rules as appropriate.  It is  gen-
	      erally  a good idea to allow IKE messages (UDP port
	      500) travel between the hosts.

       down-host or down-client
	      is run when bringing down the eroute for a pair  of
	      client  subnets.	 This command should delete fire-
	      wall rules as appropriate.  Note that there may re-
	      main  some inbound IPsec SAs with these client sub-
	      nets.

       The script is passed a large number of  environment  vari-
       ables to specify what needs to be done.

       PLUTO_VERSION
	      indicates	 what  version of this interface is being
	      used.  This document describes version  1.1.   This
	      is upwardly compatible with version 1.0.

       PLUTO_VERB
	      specifies the name of the operation to be performed
	      (prepare-host,r prepare-client, up-host, up-client,
	      down-host,  or down-client).  If the address family
	      for security gateway to security gateway communica-
	      tions is IPv6, then a suffix of -v6 is added to the



			  28 March 1999			       16





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


	      verb.

       PLUTO_CONNECTION
	      is the name of the  connection  for  which  we  are
	      routing.

       PLUTO_NEXT_HOP
	      is the next hop to which packets bound for the peer
	      must be sent.

       PLUTO_INTERFACE
	      is the name of the ipsec interface to be used.

       PLUTO_ME
	      is the IP address of our host.

       PLUTO_MY_CLIENT
	      is the IP address / count of our client subnet.  If
	      the  client  is  just  the  host,	 this will be the
	      host's own IP address / max (where max  is  32  for
	      IPv4 and 128 for IPv6).

       PLUTO_MY_CLIENT_NET
	      is the IP address of our client net.  If the client
	      is just the host, this will be the  host's  own  IP
	      address.

       PLUTO_MY_CLIENT_MASK
	      is  the  mask for our client net.	 If the client is
	      just the host, this will be 255.255.255.255.

       PLUTO_PEER
	      is the IP address of our peer.

       PLUTO_PEER_CLIENT
	      is the IP address / count of the peer's client sub-
	      net.   If the client is just the peer, this will be
	      the peer's own IP address / max (where  max  is  32
	      for IPv4 and 128 for IPv6).

       PLUTO_PEER_CLIENT_NET
	      is the IP address of the peer's client net.  If the
	      client is just the peer, this will  be  the  peer's
	      own IP address.

       PLUTO_PEER_CLIENT_MASK
	      is  the  mask  for  the  peer's client net.  If the
	      client   is   just   the	 peer,	 this	will   be
	      255.255.255.255.

       All  output  sent  by  the  script  to stderr or stdout is
       logged.	The script should return an exit status of  0  if
       and only if it succeeds.




			  28 March 1999			       17





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


   Rekeying
       When  an	 SA that was initiated by pluto has only a bit of
       lifetime left, pluto will initiate the creation of  a  new
       SA.   This  applies to ISAKMP and IPsec SAs.  The rekeying
       will be initiated when the SA's remaining lifetime is less
       than  the  rekeymargin plus a random percentage, between 0
       and rekeyfuzz, of the rekeymargin.

       Similarly, when an SA that was initiated by the	peer  has
       only  a	bit  of lifetime left, pluto will try to initiate
       the creation of a replacement.  To give preference to  the
       initiator,  this	 rekeying will only be initiated when the
       SA's remaining lifetime is half of rekeymargin.	If rekey-
       ing  is done by the responder, the roles will be reversed:
       the responder for the old SA will be the initiator for the
       replacement.   The  former  initiator  might also initiate
       rekeying, so there may be redundant SAs created.	 To avoid
       these  complications, make sure that rekeymargin is gener-
       ous.

       One risk of having the former responder initiate	 is  that
       perhaps	none of its proposals is acceptable to the former
       initiator (they have not been used in a successful negoti-
       ation).	 To  reduce the chances of this happening, and to
       prevent loss of security, the policy  settings  are  taken
       from  the old SA (this is the case even if the former ini-
       tiator is initiating).  These may be stricter  than  those
       of the connection.

       pluto  will not rekey an SA if that SA is not the most re-
       cent of its type (IPsec or ISAKMP) for its potential  con-
       nection.	 This avoids creating redundant SAs.

       The  random  component in the rekeying time (rekeyfuzz) is
       intended to make certain pathological patterns of rekeying
       unstable.  If both sides decide to rekey at the same time,
       twice as many SAs as necessary are  created.   This  could
       become a stable pattern without the randomness.

       Another more important case occurs when a security gateway
       has SAs with many other security gateways.  Each of  these
       connections  might  need	 to  be rekeyed at the same time.
       This would cause a high	peek  requirement  for	resources
       (network bandwidth, CPU time, entropy for random numbers).
       The rekeyfuzz can be used to stagger the rekeying times.

       Once a new set of SAs has been negotiated, pluto will nev-
       er  send traffic on a superseded one.  Traffic will be ac-
       cepted on an old SA until it expires.

   Selecting a Connection When Responding: Road Warrior Support
       When pluto receives an initial Main Mode message, it needs
       to  decide which connection this message is for.	 It picks
       based solely on the source and destination IP addresses of



			  28 March 1999			       18





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       the  message.   There  might  be	 several connections with
       suitable IP addresses, in which case one of them is  arbi-
       trarily	chosen.	 (The ISAKMP SA proposal contained in the
       message could be taken into account, but it is not.)

       The ISAKMP SA is negotiated before the parties  pass  fur-
       ther  identifying information, so all ISAKMP SA character-
       istics specified in the connection description  should  be
       the  same  for  every connection with the same two host IP
       addresses.  At the moment, the  only  characteristic  that
       might differ is authentication method.

       Up to this point, all configuring has presumed that the IP
       addresses are known to all parties ahead	 of  time.   This
       will not work when either end is mobile (or assigned a dy-
       namic IP address for other reasons).  We call this  situa-
       tion  ``Road  Warrior''.	 It is fairly tricky and has some
       important limitations, most of which are features  of  the
       IKE protocol.

       Only  the  initiator may be mobile: the initiator may have
       an IP number unknown to the responder.  When the responder
       doesn't	recognize  the	IP address on the first Main Mode
       packet, it looks for a connection with itself as	 one  end
       and  %any as the other.	If it cannot find one, it refuses
       to negotiate.  If it does find one, it creates a temporary
       connection  that	 is  a duplicate except with the %any re-
       placed by the source IP address from the packet; if  there
       was no identity specified for the peer, the new IP address
       will be used.

       When pluto is using one of these temporary connections and
       needs  to  find the preshared secret or RSA private key in
       ipsec.secrets, and and the connection specified no identi-
       ty for the peer, %any is used as its identity.  After all,
       the real IP address was apparently unknown to the configu-
       ration,	so  it is unreasonable to require that it be used
       in this table.

       Part way into the Phase 1 (Main	Mode)  negotiation  using
       one of these temporary connection descriptions, pluto will
       be receive an Identity  Payload.	  At  this  point,  pluto
       checks  for  a  more  appropriate  connection, one with an
       identity for the peer that matches the payload  but  which
       would  use  the	same keys so-far used for authentication.
       If it finds one, it will switch to using this better  con-
       nection	(or a temporary derived from this, if it has %any
       for the peer's IP address).  It may even turn out that  no
       connection  matches the newly discovered identity, includ-
       ing the current connection; if so, pluto terminates  nego-
       tiation.

       Unfortunately, if preshared secret authentication is being
       used, the Identity Payload is encrypted using this secret,



			  28 March 1999			       19





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       so  the	secret	must be selected by the responder without
       knowing this payload.  This limits there to being at  most
       one preshared secret for all Road Warrior systems connect-
       ing to a host.  RSA Signature authentications does not re-
       quire  that  the	 responder know how to select the initia-
       tor's public key until after the initiator's Identity Pay-
       load  is	 decoded  (using  the responder's private key, so
       that must be preselected).

       When pluto is responding to a Quick Mode	 negotiation  via
       one  of	these  temporary  connection descriptions, it may
       well find that the  subnets  specified  by  the	initiator
       don't match those in the temporary connection description.
       If so, it will look for a connection  with  matching  sub-
       nets,  its  own	host  address, a peer address of %any and
       matching identities.  If it finds  one,	a  new	temporary
       connection is derived from this one and used for the Quick
       Mode negotiation of IPsec SAs.  If it does not  find  one,
       pluto terminates negotiation.

       Be  sure to specify an appropriate nexthop for the respon-
       der to send a message to the initiator: pluto has  no  way
       of  guessing  it (if forwarding isn't required, use an ex-
       plicit %direct as the nexthop and the IP	 address  of  the
       initiator will be filled in; the obsolete notation 0.0.0.0
       is still accepted).

       pluto has no special provision  for  the	 initiator  side.
       The current (possibly dynamic) IP address and nexthop must
       be used in defining connections.	 These must  be	 properly
       configured  each	 time the initiator's IP address changes.
       pluto has no mechanism to do this automatically.

       Although we call this Road Warrior Support, it could  also
       be  used	 to  support encrypted connections with anonymous
       initiators.  The responder's organization  could	 announce
       the  preshared secret that would be used with unrecognized
       initiators and let anyone connect.  Of course the  initia-
       tor's identity would not be authenticated.

       If  any Road Warrior connections are supported, pluto can-
       not reject an exchange initiated by an unknown host  until
       it  has	determined  that  the secret is not shared or the
       signature is invalid.  This must await the third Main Mode
       message from the initiator.  If no Road Warrior connection
       is supported, the first message	from  an  unknown  source
       would  be rejected.  This has implications for ease of de-
       bugging configurations and for denial of service	 attacks.

       Although	 a  Road  Warrior connection must be initiated by
       the mobile side, the other side can and will  rekey  using
       the temporary connection it has created.	 If the Road War-
       rior wishes to be able to disconnect, it is probably  wise
       to set --keyingtries to 1 in the connection on the non-mo-



			  28 March 1999			       20





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       bile side to prevent it trying to  rekey	 the  connection.
       Unfortunately,  there  is no mechanism to unroute the con-
       nection automatically.

   Debugging
       pluto accepts several optional  arguments,  useful  mostly
       for debugging.

       --ikeport port-number
	      changes  the UDP port that pluto will use (default,
	      specified by IANA: 500)

       --ctlbase path
	      basename for control files.  path.ctl is the socket
	      through	which	whack  communicates  with  pluto.
	      path.pid is the lockfile to prevent multiple  pluto
	      instances.  The default is /var/run/pluto).

       --secretsfile file
	      specifies	 the file for authentication secrets (de-
	      fault: /etc/ipsec.secrets).  This name  is  subject
	      to  ``globbing''	as in sh(1), so every file with a
	      matching name is processed.  Quoting  is	generally
	      needed  to  prevent  the shell from doing the glob-
	      bing.

       --nofork
	      disable ``daemon fork'' (default is to fork)

       --noklips
	      don't actually implement negotiated IPsec SAs

       --uniquids
	      if this option has been selected,	 whenever  a  new
	      ISAKMP  SA  is established, any connection with the
	      same Peer ID but a different Peer IP address is un-
	      oriented (causing all its SAs to be deleted).  This
	      helps clean up dangling SAs when	a  connection  is
	      lost and then regained at another IP address.

       --stderrlog
	      log  goes	 to  standard out {default is to use sys-
	      logd(8))

       For example

       pluto	  --secretsfile ipsec.secrets
       --ctlbase pluto.base	--ikeport 8500 --nofork --noklips
       --stderrlog

       lets one test pluto without using the superuser account.

       pluto  is willing to produce a prodigious amount of debug-
       ging information.  To do so,  it	 must  be  compiled  with



			  28 March 1999			       21





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       -DDEBUG.	  There	 are several classes of debugging output,
       and pluto may be directed to produce a selection of  them.
       All  lines of debugging output are prefixed with ``| '' to
       distinguish them from error messages.

       When pluto is invoked, it may be given arguments to speci-
       fy which classes to output.  The current options are:

       --debug-raw
	      show the raw bytes of messages

       --debug-crypt
	      show the encryption and decryption of messages

       --debug-parsing
	      show the structure of input messages

       --debug-emitting
	      show the structure of output messages

       --debug-control
	      show pluto's decision making

       --debug-klips
	      show pluto's interaction with KLIPS

       --debug-all
	      all of the above

       --debug-private
	      allow debugging output with private keys.

       --debug-none
	      none of the above

       The debug form of the whack command will change the selec-
       tion in a running pluto.	 If a connection name  is  speci-
       fied,  the  flags  are added whenever pluto has identified
       that it is dealing with that  connection.   Unfortunately,
       this  is often part way into the operation being observed.

       For example, to start a pluto with a display of the struc-
       ture of input and output:

	      pluto --debug-emitting --debug-parsing

       To later change this pluto to only display raw bytes:

	      whack --debug-raw

       For testing, SSH's IKE test page is quite useful:

	      http://isakmp-test.ssh.fi/




			  28 March 1999			       22





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       Hint:  ISAKMP  SAs are often kept alive by IKEs even after
       the IPsec SA is established.   This  allows  future  IPsec
       SA's  to	 be  negotiated	 directly.  If one of the IKEs is
       restarted, the other may try to use the ISAKMP SA but  the
       new IKE won't know about it.  This can lead to much confu-
       sion.  pluto is not yet smart enough to get out of such	a
       mess.

   Pluto's Behaviour When Things Go Wrong
       When pluto doesn't understand or accept a message, it just
       ignores the message.  It is not yet capable of communicat-
       ing  the problem to the other IKE daemon (in the future it
       will use Notifications to accomplish this in many  cases).
       It does log a diagnostic.

       When pluto gets no response from a message, it resends the
       same message (a message will be sent at most three times).
       This is appropriate: UDP is unreliable.

       When  pluto gets a message that it has already seen, there
       are many cases when it notices and discards it.	This  too
       is appropriate for UDP.

       Combine these three rules, and you can explain many appar-
       ently mysterious behaviours.  In	 a  pluto  log,	 retrying
       isn't  usually  the interesting event.  The critical thing
       is either earlier (pluto got a  message	which  it  didn't
       like  and  so ignored, so it was still awaiting an accept-
       able message and got impatient) or  on  the  other  system
       (pluto  didn't  send  a reply because it wasn't happy with
       the previous message).

   Notes
       If pluto is compiled without -DKLIPS, it negotiates  Secu-
       rity  Associations but never ask the kernel to put them in
       place and never makes routing changes.  This allows  pluto
       to be tested on systems without KLIPS, but makes it rather
       useless.

       Each IPsec SA is assigned an SPI, a 32-bit number used  to
       refer to the SA.	 The IKE protocol lets the destination of
       the SA choose the SPI.  The range 0 to  0xFF  is	 reserved
       for  IANA.  Pluto also avoids choosing an SPI in the range
       0x100 to 0xFFF, leaving these SPIs free for manual keying.
       Remember	 that the peer, if not pluto, may well chose SPIs
       in this range.

   Policies
       This catalogue of policies may be of use	 when  trying  to
       configure Pluto and another IKE implementation to interop-
       erate.

       In Phase 1, only Main Mode is supported.	 We are not  sure
       that  Aggressive	 Mode  is secure.  For one thing, it does



			  28 March 1999			       23





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       not support identity protection.	 It may allow more severe
       Denial Of Service attacks.

       No  Informational  Exchanges are supported.  These are op-
       tional and since their delivery is not assured, they  must
       not  matter.  It is the case that some IKE implementations
       won't interoperate without Informational Exchanges, but we
       feel they are broken.

       No  Informational  Payloads  are supported.  These are op-
       tional, but useful.  It is of concern that these	 payloads
       are  not	 authenticated	in  Phase 1, nor in those Phase 2
       messages authenticated with HASH(3).

       o Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and  5)
	 are  supported.   Group MODP768 (1) is not supported be-
	 cause it is too weak.

       o Host authetication can be done by RSA Signatures or Pre-
	 Shared Secrets.

       o 3DES  CBC  (Cypher  Block Chaining mode) is the only en-
	 cryption supported, both for ISAKMP SAs and IPSEC SAs.

       o MD5 and SHA1 hashing are supported for packet	authenti-
	 cation in both kinds of SAs.

       o The ESP, AH, or AH plus ESP are supported.  If, and only
	 if, AH and ESP are combined, the ESP need not	have  its
	 own  authentication  component.   The	selection is con-
	 trolled by the --encrypt and --authenticate flags.

       o Each of these may be combined with IPCOMP  Deflate  com-
	 pression, but only if the potential connection specifies
	 compression.

       o The IPSEC SAs may be tunnel or transport mode, where ap-
	 propriate.   The  --tunnel flag controls this when pluto
	 is initiating.

       o When responding to an ISAKMP SA  proposal,  the  maximum
	 acceptable  lifetime is eight hours.  The default is one
	 hour.	There is no minimum.  The --ikelifetime flag con-
	 trols this when pluto is initiating.

       o When responding to an IPSEC SA proposal, the maximum ac-
	 ceptable lifetime is one  day.	  The  default	is  eight
	 hours.	  There	 is no minimum.	 The --ipseclifetime flag
	 controls this when pluto is initiating.

       o PFS is acceptable, and will be	 proposed  if  the  --pfs
	 flag  was  specified.	The DH group proposed will be the
	 same as negotiated for Phase 1.




			  28 March 1999			       24





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


EXIT STATUS
       pluto normally forks a daemon process, so the exit  status
       is normally a very preliminary result.

       0      means that all is OK so far.

       1      means that something was wrong.

       10     means that the lock file already exists.

       If  whack detects a problem, it will return an exit status
       of 1.  If it received progress messages from pluto, it re-
       turns  as  status the value of the numeric prefix from the
       last such message that was not a message sent to syslog or
       a  comment  (but	 the prefix for success is treated as 0).
       Otherwise, the exit status is 0.

FILES
       /var/run/pluto.pid
       /var/run/pluto.ctl
       /etc/ipsec.secrets
       /dev/urandom

SEE ALSO
       The rest of  the	 FreeS/WAN  distribution,  in  particular
       ipsec(8).

       ipsec_auto(8)  is designed to make using pluto more pleas-
       ant.  Use it!

       ipsec.secrets(5) describes the format of the secrets file.

       ipsec_atoaddr(3),  part of the FreeS/WAN distribution, de-
       scribes the forms that IP addresses may take.   ipsec_ato-
       subnet(3),  part	 of the FreeS/WAN distribution, describes
       the forms that subnet specifications.

       For more information on IPsec, the mailing list,	 and  the
       relevant documents, see:

	      http://www.ietf.cnri.reston.va.us/html.charters/ipsec-
	      charter.html

       At the time of writing, the most relevant IETF RFCs are:

	      RFC2409 The Internet Key Exchange (IKE)

	      RFC2408 Internet Security Association and Key  Man-
	      agement Protocol (ISAKMP)

	      RFC2407  The  Internet IP Security Domain of Inter-
	      pretation for ISAKMP

       The linux-ipsec@clinet.fi mailing list.



			  28 March 1999			       25





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


HISTORY
       This code is released under the GPL terms.  See the accom-
       panying	file  COPYING-2.0 for more details.  The GPL does
       NOT apply to those pieces of code written by others  which
       are  included in this distribution, except as noted by the
       individual authors.

       This software was originally  written  for  the	FreeS/WAN
       project	<http://www.xs4all.nl/~freeswan/>  by  Angelos D.
       Keromytis (angelos@dsl.cis.upenn.edu), in  May/June  1997,
       in  Athens,  Greece.   Thanks go to John Ioannidis for his
       help.

       It is currently (2000) being developed and  maintained  by
       D. Hugh Redelmeier (hugh@mimosa.com), in Canada.	 The reg-
       ulations of Greece and Canada allow us to  make	the  code
       freely redistributable.

       Kai Martius (admin@imib.med.tu-dresden.de) contributed the
       initial version of the code supporting PFS.

       Richard Guy Briggs <rgb@conscoop.ottawa.on.ca>  and  Peter
       Onion <ponion@srd.bt.co.uk> added the PFKEY2 support.

       We  gratefully  acknowledge  that  we  use  parts  of Eric
       Young's libdes package; see ../libdes/COPYRIGHT.

BUGS
       pluto is a work-in-progress.  It currently has many  limi-
       tations.	  For  example,	 it ignores notification messages
       that it receives, and it generates none.

       pluto does not check that the SA returned by the Responder
       is  actually  one  that was proposed.  It only checks that
       the SA is acceptable.  The difference is	 not  large,  but
       can show up in attributes such as SA lifetime.

       There is no provision for unrouting a Road Warrior connec-
       tion that has expired.  In fact, there is no good way  for
       a  Road	Warrior to indicate that the connection should be
       torn down.  The expiry of SAs is	 the  closest  approxima-
       tion.   If,  however,  a	 Road Warrior has a client subnet
       with a fixed IP address, a negotiation  with  that  subnet
       will  cause  any other connection instantiations with that
       same subnet to be unoriented (deleted, in effect).

       In IPCOMP SAs, the SPI is replaced by a	CPI.   The  stan-
       dards  and  drafts allow for certain well-known CPIs to be
       used instead of a unique CPI for the SA.	  FreeS/WAN  does
       not allow well-known CPIs, only negotiated ones.

       When pluto sends a message to a peer that has disappeared,
       pluto receives incomplete information from the kernel,  so
       it  logs	 the unsatisfactory message ``some IKE message we



			  28 March 1999			       26





IPSEC_PLUTO(8)					   IPSEC_PLUTO(8)


       sent has been rejected with ECONNREFUSED (kernel	 supplied
       no  details)''.	John Denker suggests that this command is
       useful for tracking down the source of these problems:
	    tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0
       Substitute your public interface for eth0 if it is differ-
       ent.

       The  word  ``authenticate'' is used for two different fea-
       tures.  We must authenticate each IKE peer to  the  other.
       This is an important task of Phase 1.  Each packet must be
       authenticated, both in IKE and in IPsec,	 and  the  method
       for  IPsec is negotiated as an AH SA or part of an ESP SA.
       Unfortunately, the protocol has no mechanism for authenti-
       cating the Phase 2 identities.

       Bugs should be reported to the linux-ipsec@clinet.fi mail-
       ing list.  Caution: we cannot accept actual code	 from  US
       residents,  or even US citizens living outside the US, be-
       cause that would bring  FreeS/WAN  under	 US  export  law.
       Some  other countries cause similar problems.  In general,
       we would prefer that you	 send  detailed	 problem  reports
       rather  than code:  we want FreeS/WAN to be unquestionably
       freely exportable, which means being  very  careful  about
       where  the  code comes from, and for a small bug fix, that
       is often more time-consuming than just reinventing the fix
       ourselves.































			  28 March 1999			       27


