Provided by: strongswan-ikev1_4.5.2-1.2_amd64 bug

NAME

       pluto - IPsec IKE keying daemon and control interface

       whack - control interface for IKE keying daemon

SYNOPSIS

       ipsec pluto [--help] [--version] [--optionsfrom filename] [--nofork] [--stderrlog]
              [--uniqueids] [--interface interfacename] [--ikeport portnumber] [--ctlbase path]
              [--secretsfile secrets‐file] [--adns pathname] [--lwdnsq pathname] [--perpeerlog]
              [--perpeerlogbase dirname] [--debug‐none] [--debug‐all] [--debug‐raw] [--debug‐
              crypt] [--debug‐parsing] [--debug‐emitting] [--debug‐control] [--debug‐lifecycle]
              [--debug‐kernel] [--debug‐dns] [--debug‐oppo] [--debug‐private]

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

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

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

       ipsec whack --myid id

       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 [--tunnelipv4] [--tunnelipv6] --oppohere ip‐address --oppothere ip‐address

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

       ipsec whack --deletestate state-number [--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‐lifecycle]
              [--debug‐kernel] [--debug‐dns] [--debug‐oppo] [--debug‐private] [--ctlbase path]
              [--optionsfrom filename] [--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 associations'' 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 the
       Linux kernel.  ipsec_auto(8) provides a more convenient interface to pluto 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, authentication,
       encryption, or compression.

       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.

       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.

       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.

       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.

       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).

       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.

       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.

       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.

       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.

   Pluto
       pluto is an implementation of IKE.  It runs as a daemon on  a  network  node.   Currently,
       this network node must be a Linux 2.6 system running the native NETKEY IPsec stack.

       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 Associations 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  authenticate  peers with whom it is
       negotiating.

       pluto initiates negotiation of a Security Association when it  is  manually  prodded:  the
       program  whack is run to trigger this.  It will also initiate a negotiation when the Linux
       kernel traps an outbound packet for Opportunistic Encryption.

       pluto implements ISAKMP SAs itself.  After it has negotiated  the  characteristics  of  an
       IPsec SA, it directs the Linux kernel to implement it.  It also invokes a script to adjust
       any firewall and issue route(8) commands.

       When pluto shuts down, it closes all Security Associations.

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

       pluto requires a Linux 2.6 kernel with the modules for the native IPsec stack enabled.

       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 (the --interface option
       can be used to limit the interfaces considered).  It does this only when whack tells it to
       --listen, so the interfaces must be configured by then.  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.   If  the
       connection  is  Opportunistic, and no RSA public key is known, pluto will attempt to fetch
       RSA keys using the Domain Name System.

   ipsec.secrets file
       A pluto daemon and another IKE daemon  (for  example,  another  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  either  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 secret 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  running  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 conventional ``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) 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.

       If  the  --perpeerlog  option is given, then pluto will open a log file per connection. By
       default, this is in /var/log/pluto/peer, in a subdirectory formed by turning all  dot  (.)
       [IPv4} or colon (:) [IPv6] into slashes (/).

       The base directory can be changed with the --perpeerlogbase.

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

   Pluto's Internal State
       To  understand  how  to use pluto, it is helpful to understand 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 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 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.

       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.

       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 (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  identical
       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 instantiating 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 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).

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

       Some  of these routing characteristics are specific to KLIPS, the FreeS/WAN implementation
       of IPsec and are not relevant when running pluto on the native Linux 2.6 IPsec stack.

   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 allows many different functions to be
       specified.  The help form shows the usage or version  information.   The  connection  form
       gives pluto a description of a potential connection.  The public key form informs pluto 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 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 debug 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 debugging.

       --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 responder, it needs to know enough to  decide  whether
       is is willing 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 command ill-formed.

       --name connection-name

       The topology of a connection 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 describe 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 immediately) or as
              a Fully Qualified Domain Name itself (prefixed by ``@'' to signify that  it  should
              not  be  resolved),  or  as  user@FQDN,  or  as  the magic value %myid.  Pluto only
              authenticates the identity, and does not use it for addressing, 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 address specified by --host.  %myid  allows
              the  identity to be separately specified (by the pluto or whack option --myid or by
              the ipsec.conf(5) config setup parameter myid).  Otherwise, pluto  tries  to  guess
              what %myid should stand for: the IP address of %defaultroute, if it is supported by
              a suitable TXT record in the reverse domain for that IP address,  or  the  system's
              hostname, if it is supported by a suitable TXT record in its forward domain.

       --host ip‐address

       --host %any

       --host %opportunistic
              the  IP address of the end (generally the public interface).  If pluto is to act as
              a responder for IKE negotiations initiated from unknown IP  addresses  (the  ``Road
              Warrior''  case),  the  IP  address  should  be  specified  as %any (currently, the
              obsolete  notation  0.0.0.0  is  also  accepted  for  this).   If   pluto   is   to
              opportunistically initiate the connection, use %opportunistic

       --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 (presumably for the peer too, but it
              will not be used for this).  When pluto installs an IPsec SA,  it  issues  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  obsolete  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 destined.   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''.

       --dnskeyondemand]
              specifies that when an RSA public key is needed to authenticate this host,  and  it
              isn't already known, fetch it from DNS.

       --updown updown
              specifies  an  external  shell command to be run whenever 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  characteristics  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; at least one must be specified.

       --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; at least one must be
              specified.

       --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 accepted IPsec SAs will include AH or
              ESP with authentication.  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 (compression).  This will be ignored if
              the kernel is not configured with IPCOMP support.

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

       --ipv4 The  host  addresses  will  be interpreted as IPv4 addresses.  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 interpreted as IPv6 addresses.  Note
              that for a connection, all host addresses must be of the same Address Family  (IPv4
              and IPv6 use different Address Families).

       --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 specified.  Note that for a connection, all
              tunnel addresses 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 specified.  Note that for a connection,  all
              tunnel addresses must be of the same Address Family.

       --pfs  There should be Perfect Forward Secrecy - new keying 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 negotiated (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.

       --disablearrivalcheck
              If the connection is a tunnel, allow packets arriving through the  tunnel  to  have
              any source and destination addresses.

       If  none  of  the  --encrypt,  --authenticate,  --compress,  or  --pfs flags is given, the
       initiating the connection will only build an ISAKMP SA.  For  such  a  connection,  client
       subnets have no meaning and must not be specified.

       More  work is needed to allow for flexible policies.  Currently 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 always Deflate.

       --ikelifetime seconds
              how long pluto will propose that an ISAKMP SA be allowed to live.  The  default  is
              10800  (three  hours)  and  the  maximum  is 86400 (one day).  This option will not
              affect what is accepted.  pluto will reject proposals that exceed the maximum.

       --ipseclifetime seconds
              how long pluto will propose that an IPsec SA be allowed to live.   The  default  is
              3600  (one  hour)  and the maximum is 86400 (one day).  This option will not affect
              what is accepted.  pluto will reject proposals that exceed the maximum.

       --rekeymargin seconds
              how long before an SA's expiration should pluto try to negotiate a replacement  SA.
              This  will  only  happen  if  pluto  was  the  initiator.  The default is 540 (nine
              minutes).

       --rekeyfuzz percentage
              maximum size of random component to add to rekeymargin, 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.

       --dontrekey
              A  misnomer.  Only rekey a connection if we were the Initiator and there was recent
              traffic on the existing connection.  This applies to Phase 1 and Phase 2.  This  is
              currently  the  only automatic way for a connection to terminate.  It may be useful
              with Road Warrior or Opportunistic connections.
              Since SA lifetime negotiation is take-it-or-leave it, a Responder normally uses the
              shorter  of  the negotiated or the configured lifetime.  This only works because if
              the lifetime is shorter than negotiated, the Responder will rekey in time  so  that
              everything  works.   This  interacts  badly  with  --dontrekey.   In this case, the
              Responder will end up rekeying to rectify a shortfall in an IPsec SA lifetime;  for
              an ISAKMP SA, the Responder will accept the negotiated lifetime.

       --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 deletestate form deletes the state object with the specified serial number.   This  is
       useful for selectively deleting instances of connections.

       --deletestate state-number

       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.  A TRAP shunt eroute will be installed; if outbound traffic is  caught,
       Pluto  will  initiate 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

       --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 information 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 opportunistic initiate form is mainly used for debugging.

       --tunnelipv4

       --tunnelipv6

       --oppohere ip-address

       --oppothere ip-address

       This will cause pluto to attempt to opportunistically initiate a connection from  here  to
       the there, even if a previous attempt had been made.  The whack log will show the progress
       of this attempt.

       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 starting (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 KEY records 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 secure.

       --addkey
              specifies  that  the  new  key  is  added  to the collection; otherwise the new key
              replaces any old ones.

       --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_ttodata(3).  For example,  a  base  64  numeral
              starts with 0s.

       The  listen form tells pluto to start listening for IKE requests on its public interfaces.
       To avoid race conditions, 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 interfaces.

       --unlisten
              stop listening for IKE traffic on public interfaces.

       The  status  form  will display information about the internal state of pluto: information
       about each potential connection, about each state object, and about each shunt that  pluto
       is managing without an associated connection.

       --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 superuser.  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 described:

          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  accepting
       messages from peers:

          ipsec whack --listen

       If  we  don't immediately wish to bring up a secure connection between the two clients, we
       might wish to prevent insecure 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

       Notification  of  any  IPSEC  SA deletion, but not ISAKMP SA deletion is sent to the peer.
       Unfortunately, such Notification is  not  reliable.   Furthermore,  pluto  itself  ignores
       Notifications.

   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.

       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.  Generally, this is useful for deleting a route that might have been
              set up before pluto was run or perhaps 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 a tunnel eroute with a pair of client subnets that does not
              already  have  a  tunnel  eroute.   This  command  should install firewall rules as
              appropriate.  It is generally 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 firewall rules as appropriate.   Note  that  there  may  remain  some
              inbound IPsec SAs with these client subnets.

       The  script  is passed a large number of environment variables 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 communications is IPv6, then a suffix of -v6 is added
              to the 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 subnet.  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.

       Pluto  waits  for  the  script  to finish and will not do any other processing while it is
       waiting.  The script may assume that pluto will not change anything while the script runs.
       The  script  should  avoid doing anything that takes much time and it should not issue any
       command that requires processing by pluto.  Either of these activities could be  performed
       by a background subprocess of the script.

   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  rekeying  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 generous.

       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 negotiation).
       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 initiator is
       initiating).  These may be stricter than those of the connection.

       pluto will not rekey an SA if that SA is not the most recent of its type (IPsec or ISAKMP)
       for its potential connection.  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 never send traffic on a superseded
       one.  Traffic will be accepted 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 the
       message.  There might be several connections with suitable IP addresses, in which case one
       of  them is arbitrarily 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 further  identifying  information,  so
       all  ISAKMP  SA characteristics 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
       dynamic  IP  address  for other reasons).  We call this situation ``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 replaced 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  identity
       for the peer, %any is used as its identity.  After all, the real IP address was apparently
       unknown to the configuration, 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 connection (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,  including  the  current  connection; if so, pluto terminates
       negotiation.

       Unfortunately, if preshared secret authentication is being used, the Identity  Payload  is
       encrypted  using  this  secret,  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 connecting to a host.  RSA Signature authentications does not require
       that the responder know  how  to  select  the  initiator's  public  key  until  after  the
       initiator's  Identity  Payload 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  subnets,  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 responder  to  send  a  message  to  the
       initiator:  pluto has no way of guessing it (if forwarding isn't required, use an explicit
       %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 initiator's identity would not be authenticated.

       If  any  Road Warrior connections are supported, pluto cannot 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 debugging 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 Warrior
       wishes to be able to disconnect, it is probably wise to set  --keyingtries  to  1  in  the
       connection  on  the  non-mobile  side  to  prevent  it  trying  to  rekey  the connection.
       Unfortunately, there is no mechanism to unroute the connection automatically.

   Debugging
       pluto accepts several  optional  arguments,  useful  mostly  for  debugging.   Except  for
       --interface, each should appear at most once.

       --interface interfacename
              specifies  that  the named real public network interface should be considered.  The
              interface name specified should not be ipsecN.  If the option doesn't  appear,  all
              interfaces  are considered.  To specify several interfaces, use the option once for
              each.  One use of this option is to specify which interface should be used when two
              or more share the same IP address.

       --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 (default: /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
              globbing.

       --adns pathname

       --lwdnsq pathname
              specifies where to find pluto's helper program for asynchronous DNS lookup.   pluto
              can  be  built  to use one of two helper programs: _pluto_adns or lwdnsq.  You must
              use the program for which it was built.   By  default,  pluto  will  look  for  the
              program  in  $IPSEC_DIR (if that environment variable is defined) or, failing that,
              in the same directory as pluto.

       --nofork
              disable ``daemon fork'' (default is to fork).  In addition, after the lock file and
              control socket are created, print the line ``Pluto initialized'' to standard out.

       --uniqueids
              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  unoriented
              (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 syslogd(8))

       pluto is willing to produce a prodigious amount of debugging information.  To  do  so,  it
       must  be  compiled with -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 specify 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-lifecycle
              [this option is temporary] log more detail of lifecycle of SAs

       --debug-kernel
              show pluto's interaction with the kernel

       --debug-dns
              show pluto's interaction with DNS for KEY and TXT records

       --debug-oppo
              show why pluto didn't find a suitable DNS TXT  record  to  authorize  opportunistic
              initiation

       --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 selection in a running pluto.  If a
       connection name is specified, 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 structure 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/

       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 confusion.  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 communicating the problem to the other IKE daemon (in the future  it  might
       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 apparently 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 acceptable 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
       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 interoperate.

       In Phase 1, only Main Mode is supported.  We are not sure that Aggressive Mode is  secure.
       For  one  thing, it does not support identity protection.  It may allow more severe Denial
       Of Service attacks.

       No Informational Exchanges are supported.  These are optional 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  optional,  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).

       · Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are  supported.   Group  MODP768
         (1) is not supported because it is too weak.

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

       · 3DES  CBC (Cypher Block Chaining mode) is the only encryption supported, both for ISAKMP
         SAs and IPSEC SAs.

       · MD5 and SHA1 hashing are supported for packet authentication in both kinds of SAs.

       · 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 controlled by
         the --encrypt and --authenticate flags.

       · Each of these may be combined with IPCOMP Deflate compression, but only if the potential
         connection  specifies  compression  and  only  if  the  kernel is configured with IPCOMP
         support.

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

       · 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  controls
         this when pluto is initiating.

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

       · 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.

SIGNALS

       Pluto responds to SIGHUP by issuing a suggestion that ``whack --listen'' might  have  been
       intended.

       Pluto exits when it recieves SIGTERM.

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 returns 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
       $IPSEC_LIBDIR/_pluto_adns
       $IPSEC_EXECDIR/lwdnsq
       /dev/urandom

ENVIRONMENT

       IPSEC_LIBDIR
       IPSEC_EXECDIR
       IPSECmyid

SEE ALSO

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

       ipsec_auto(8) is designed to make using pluto more pleasant.  Use it!

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

       ipsec_atoaddr(3),  part  of  the  FreeS/WAN  distribution,  describes  the  forms  that IP
       addresses may take.  ipsec_atosubnet(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 Management Protocol (ISAKMP)

              RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP

       The FreeS/WAN web site <htp://www.freeswan.org> and the mailing lists described there.

HISTORY

       This code is released under the GPL terms.  See the accompanying 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.freeswan.org>
       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 regulations 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 limitations.  For example, it  ignores
       notification  messages  that  it  receives, and it generates only Delete Notifications and
       those only for IPSEC SAs.

       pluto does not support the Commit Flag.  The Commit Flag is  a  bad  feature  of  the  IKE
       protocol.  It isn't protected -- neither encrypted nor authenticated.  A man in the middle
       could turn it on, leading to DoS.  We just ignore it, with a warning.  This should let  us
       interoperate with implementations that insist on it, with minor damage.

       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 good way for a connection to be automatically terminated.  This is a problem
       for Road Warrior and Opportunistic connections.  The --dontrekey option does  prevent  the
       SAs  from being rekeyed on expiry.  Additonally, if a Road Warrior connection 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).
       See also the --uniqueids option for an extension of this.

       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
       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 different.

       The  word  ``authenticate'' is used for two different features.  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  authenticating
       the Phase 2 identities.

       Bugs  should  be  reported  to  the  <users@lists.freeswan.org> mailing list.  Caution: we
       cannot accept actual code from US residents, or even US citizens living  outside  the  US,
       because  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                            IPSEC_PLUTO(8)