Provided by: openswan_2.4.9+dfsg-1build1_i386 bug

NAME

       ipsec  pluto  -  ipsec  whack  :  IPsec  IKE  keying daemon and control
       interface

SYNOPSIS

       ipsec pluto [--help] [--version] [--optionsfrom filename] [--nofork]
             [--stderrlog] [--use-auto] [--use-klips] [--use-netkey]
             [--use-nostack] [--uniqueids] [--nat_traversal]
             [--virtual_private network_list] [--keep_alive delay_sec]
             [--force_keepalive] [--disable_port_floating] [--nocrsend]
             [--strictcrlpolicy] [--crlcheckinterval] [--ocspuri]
             [--interface interfacename] [--ikeport portnumber]
             [--ctlbase path] [--secretsfile secrets-file] [--adns pathname]
             [--nhelpers number] [--lwdnsq pathname] [--perpeerlog]
             [--perpeerlogbase dirname] [--ipsecdir dirname]
             [--coredir dirname] [--noretransmits]

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

       ipsec whack [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt]
             [--debug-parsing] [--debug-emitting] [--debug-control]
             [--debug-lifecycle] [--debug-klips] [--debug-pfkey]
             [--debug-nat-t] [--debug-dpd] [--debug-dns] [--debug-oppo]
             [--debug-private]

       ipsec whack --name connection-name [--ipv4 | --ipv6] [--tunnelipv4 |
             --tunnelipv6]

              [--id identity] [--host ip-address] [--cert path]
             [--ca distinguished name] [--groups access control groups]
             [--sendcert yes | forced | always | ifasked | no | never]
             [--certtype number] [--ikeport portnumber] [--nexthop ip-address]
             [--client subnet | --clientwithin subnet]
             [--clientprotoport protocol/port] [--srcip ip-address]
             [--xauthserver] [--xauthclient] [--modecfgserver]
             [--modecfgclient] [--dnskeyondemand] [--updown updown]

              --to

              [--id identity] [--host ip-address] [--cert path]
             [--ca distinguished name] [--groups access control groups]
             [--sendcert yes | always | ifasked | no | never]
             [--certtype number] [--ikeport port-number]
             [--nexthop ip-address] [--client subnet] [--clientwithin subnet]
             [--clientprotoport protocol/port] [--srcip ip-address]
             [--xauthserver] [--xauthclient] [--modecfgserver]
             [--modecfgclient] [--dnskeyondemand] [--updown updown]

              [--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate]
             [--compress] [--pfs]
             [--pfsgroup modp1024 | modp1536 | modp2048 | modp3072 | modp4096 | modp6144 | modp8192]
             [--disablearrivalcheck] [--ikelifetime seconds]
             [--ipseclifetime seconds] [--rekeymargin seconds]
             [--rekeyfuzz percentage] [--keyingtries count] [--esp esp-algos]
             [--dontrekey] [--aggrmode] [--modecfgpull] [--dpddelay seconds |
             --dpdtimeout seconds] [--dpdaction clear | hold | restart]
             [--forceencaps]
             [--initiateontraffic | --pass | --drop | --reject]
             [--failnone | --failpass | --faildrop | --failreject]
             [--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
             [--xauthuser user] [--xauthpass pass] [--asynchronous]
             [--ctlbase path] [--optionsfrom filename] [--label string]

       ipsec whack [--tunnelipv4 | --tunnelipv6] --oppohere ip-address
             --oppothere ip-address

       ipsec whack --crash [ipaddress]

       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-controlmore]
             [--debug-lifecycle] [--debug-klips] [--debug-pfkey] [--debug-dns]
             [--debug-dpd] [--debug-natt] [--debug-oppo] [--debug-private]
             [--impair-delay-adns-key-answer] [--impair-delay-adns-txt-answer]
             [--impair-bust-mi2] [--impair-bust-mr2] [--impair-sa-fail]
             [--impair-die-oninfo] [--impair-jacob-two-two]

       ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
             [--listcacerts] [--listacerts] [--listaacerts] [--listocspcerts]
             [--listgroups] [--listcrls] [--listocsp] [--listcards]

       ipsec whack [--utc] [--rereadsecrets] [--rereadall] [--rereadcacerts]
             [--rereadacerts] [--rereadaacerts] [--rereadocspcerts]
             [--rereadcrls]

       ipsec whack --purgeocsp

       ipsec whack --listevents

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

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

DESCRIPTION

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

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 other parts of the system - the kernel. Pluto can talk to various kernel implementations, such as KLIPS, such as NETKEY, and such as KAME IPsec stacks. ipsec_auto(8) provides a more convenient interface to pluto and whack.
       pluto is used to automatically build shared â

   IKEs 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.
       Currently, Main Mode and Aggressive Mode are implemented.

       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 system  running  the
       KLIPS  or  NETKEY  implementation of IPsec, or a FreeBSD/NetBSD/Mac OSX
       system running the KAME implementation of IPsec.

       pluto implements a large subset of  IKE.  This  is  enough  for  it  to
       interoperate  with  other  instances  of  pluto,  and  many  other  IKE
       implementations. It currently supports XAUTH, ModeConfig,  X.509,  Dead
       Peer  Detection,  Opportunistic  Encryption  and  all the NAT Traversal
       standards.

       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. These RSA signatures can come from DNS(SEC),  a
       configuration file, or from X.509 and CA certificates.

       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 KLIPS 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 kernel to implement it.
       If necessary, it also invokes a script to adjust any firewall and issue
       route(8) commands to direct IP packets.

       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 working IPsec stack.

       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. Each
       interface with a name of the  form  ipsec[0-9]  is  taken  as  a  KLIPS
       virtual  public  interface.  Another network interface with the same IP
       address  (the  first  one  found  will  be  used)  is  taken   as   the
       corresponding  real  public interface. ifconfig(8) or ip(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.

   Setting up KLIPS for pluto
       The most basic network topology that pluto supports  has  two  security
       gateways  negotiating on behalf of client subnets. 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  distribution  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 IP 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 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).

   Setting up NETKEY for pluto
       No special requirements are necessary to use NETKEY - it ships with all
       modern versions of Linux  2.4  and  2.6.  however,  note  that  certain
       vendors  or older distributions use old versions or backports of NETKEY
       which are broken. If possible use a NETKEY version  that  is  at  least
       based on, or backported from Linux 2.6.11 or newer.

   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,  RSA
       private   keys,   X.509   encoded  keyfiles  and  smartcard  PIN’s  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. If pluto is told to enable NAT-Traversal, then
       UDP port 4500 is also taken by pluto to listen on.

       Pluto supports different IPstacks on different operating  systems.  The
       option  --use-auto,  which is also the default, lets pluto find a stack
       automatically. This behaviour can be changed by explicitely setting the
       stack  using  --use-klips, --use-netkey or --use-nostack. The latter is
       meant for testing only - no actual IPsec  connections  will  be  loaded
       into the kernel.

       Pluto  supports  the  NAT-Traversal  drafts and the final standard, RFC
       3947, if the --nat_traversal is specified. The allowed range behind the
       NAT  routers  is  submitted  using  the  --virtual_private  option. See
       ipsec.conf(5) for the syntax. The option --force_keepalive  forces  the
       sending  of  the  keep-alive packets, which are send to prevent the NAT
       router from closing its port when there is not enough  traffic  on  the
       IPsec connection. The --keep_alive sets the delay (in seconds) of these
       keep-alive packets. The newer NAT-T standards  support  port  floating,
       and  Openswan  enables  this  per default. It can be disabled using the
       --disable_port_floating option.

       Pluto supports the use of X.509 certificates and sends  it  certificate
       when needed. This can confuse IKE implementations that do not implement
       this, such as the old FreeS/WAN implementation. The --nocrsend prevents
       pluto from sending these. At startup, pluto loads all the X.509 related
       files from the  directories  /etc/ipsec.d/certs,  /etc/ipsec.d/cacerts,
       /etc/ipsec.d/aacerts,  /etc/ipsec.d/ocspcerts, /etc/ipsec.d/private and
       /etc/ipsec.d/crls.  The  Certificate  Revocation  Lists  can  also   be
       retrieved  from  an  URL.  The  option --crlcheckinterval sets the time
       between checking for CRL expiration and issuing new fetch commands. The
       first  attempt  to update a CRL is started at 2*crlcheckinterval before
       the next update time. Pluto logs a warning if no valid CRL  was  loaded
       or  obtained  for  a  connection.  If  --strictcrlpolicy  is given, the
       connection will be rejected until a valid CRL has  been  loaded.  Pluto
       also  has  support  for the Online Certificate Store Protocol (OSCP) as
       defined in RFC 2560. The URL to the OSCP store can be  given  to  pluto
       via the --ocspuri option.

       Pluto can use the BIND9 secure resolver, which means it has support for
       DNSSEC, using the BIND9 lwres {} interface,  see  named.conf(5).  Pluto
       can  also  use the old adns interface if there is no BIND9 running with
       lwres {} on the host, but then pluto cannot do any  DNSSEC  processing.
       Pluto  forks  and  starts  these  DNS helpers in seperate children. The
       options --lwdnsq and --adns invoke these resolvers.

       Pluto  can  also  use  helper  children   to   off-load   cryptographic
       operations. This behavior can be fine tuned using the --nhelpers. Pluto
s you have (including hypherthreaded CPUâs). A value of 0 forces pluto to do all operations in the main process. A value of -1 tells pluto to perform the above calculation. Any other value forces the number to that amount.
       will start (n-1) of them, where n is the number of CPUâ

       pluto   attempts   to    create    a    lockfile    with    the    name
       /var/run/pluto/pluto.pid.  If  the  lockfile  cannot  be created, pluto
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).
       exits - this prevents multiple plutos from competing Any â
       pluto then forks and the parent exits. This is the conventional â

       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, the option
       --stderrlog is used 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.

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

       Pluto supports food groups, and X.509 certificates. These  are  located
       in /etc/ipsec.d, or another directory as specified by --ipsecdir.

       Pluto  may  core  dump. It will normally do so into the current working
       directory. The standard scripts have an option dumpdir=, which can  set
       the current directory to determine where the core dump will go. In some
       cases, it may be more convenient to specify  it  on  the  command  line
       using  --coredir.  A  third  method  is to set the environment variable
       PLUTO_CORE_DIR. The command line argument  takes  precedence  over  the
       environment  variable.  The option plutorestartoncrash can be set to no
       to prevent multiple core files and a looping pluto  process.  Normally,
       when pluto crashes, another pluto process is started.

       At  times  it  may be desireable to turn off all timed events in pluto,
       this can be done with --noretransmits.

       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.

       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 processing to be done is specified by ipsec
       eroute(8) commands. pluto takes the responsibility of managing both  of
       these special kinds of routes.

       NETKEY requires no special routing.

       Each  connection  may  be routed, and must be while it has an IPsec SA.
       The  connection  specifies  the  characteristics  of  the  route:   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).
       interface on this machine, the â

       On  KLIPS, 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.

       All of these routing characteristics are expected change when KLIPS and
       NETKEY merge into a single new 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
on the flyâ. The shutdown form tells pluto to shut down, deleting all SAs.
       output â

       The crash option asks pluto to consider a  particularly  target  IP  to
       have  crashed,  and  to attempt to restart all connections with that IP
       address as a gateway. In general, you should use Dead Peer Detection to
       detect  this  kind  of  situation automatically, but this is not always
       possible.

       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
              sets the name of the connection

       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
@â to signify that it should not be resolved), or as user@FQDN, or an X.509 DN, or as the magic value 9myid. 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. 9myid 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 9myid should stand for: the IP address of 9defaultroute, 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.
              Domain Name itself (prefixed by â

       --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
Road Warriorâ case), the IP address should be specified as 9any (currently, the obsolete notation 0.0.0.0 is also accepted for this). If pluto is to opportunistically initiate the connection, use 9opportunistic
              from unknown IP addresses (the â

       --cert filename
              The  filename  of the X.509 certificate. This must be the public
              key certificate only, and  cannot  be  the  PKCS#12  certificate
              file.  See  ipsec.conf(5) on how to extrac this from the PKCS#12
              file.

       --ca distinguished name
              the X.509 Certificate Authority’s Distinguished Name  (DN)  used
              as  trust anchor for this connection. This is the CA certificate
              that signed the host certificate, as well as the certificate  of
              the incoming client.

       --groups access control groups
              the access control groups used.

       --sendcert yes|forced|always|ifasked|no|never
              Wether  or  not  to send our X.509 certificate credentials. This
              could potentially give an attacker too  much  information  about
              which  identities  are  allowed  to  connect  to  this host. The
              default is to use ifasked when we are a Responder,  and  to  use
              yes  (which  is  the  same  as  forced  and  always if we are an
              Initiator.  The  values  no  and  never  are  equivalent.  NOTE:
              "forced"  does  not seem to be actually implemented - do not use
              it.

       --certtype number
              The X.509 certificate type number.

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

       --clientwithin subnet
              This option is obsolete and will be removed.  Do  not  use  this
              option anymore.

       --clientprotoport protocol/port
              specify  the  Port  Selectors  (filters)  to  be  used  on  this
              connection. The general form  is  protocol/port.  This  is  most
              commonly  used  to  limit the connection to L2TP traffic only by
              specifying a value of 17/1701 for UDP  (protocol  17)  and  port
              1701.  The notation 17/%any can be used to allow all UDP traffic
              and is needed for L2TP  connections  with  Windows  XP  machines
              before Service Pack 2.

       --srcip ip-address
              the  IP  address for this host to use when transmitting a packet
              to the remote IPsec gateway itself. This option is used to  make
              the  gateway  itself  use  its internal IP, which is part of the
              --client subnet. Otherwise it will use its nearest  IP  address,
              which  is  its  public  IP  address,  which  is  not part of the
              subnet-subnet  IPsec  tunnel,  and  would   therefor   not   get
              encrypted.

       --xauthserver
              this  end  is an xauthserver. It will lookup the xauth user name
              and password and verify this before allowing the  connection  to
              get established.

       --xauthclient
              this end is an xauthclient. To bring this connection up with the
              --initiate also  requires  the  client  to  specify  --xauthuser
              username and --xauthpass password

       --xauthuser
              The   username  for  the  xauth  authentication.This  option  is
              normally passed along by ipsec_auto(8) when an xauth  connection
              is started using ipsec auto --up conn

       --xauthpass
              The  password  for  the  xauth  authentication.  This  option is
              normally passed along by ipsec_auto(8) when an xauth  connection
              is started using ipsec auto --up conn

       --modecfgserver
              this end is an Mode Config server

       --modecfgclient
              this end is an Mode Config client

       --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.  Pluto
              passes  a  dozen  environment  variables to the script about the
              connection involved.

       --to   separates the specification of the left and right  ends  of  the
              connection.  Pluto  tries  to  decide wether it is left or right
              based on the information provided on both sides of this  option.

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

       --pfsgroup modp-group
              Sets the Diffie-Hellman  group  used.  Currently  the  following
              values  are  supported:  modp1024 (DHgroup 2), modp1536 (DHgroup
              5), modp2048  (DHgroup  14),  modp3072  (DHgroup  15),  modp4096
              (DHgroup  16), modp6144 (DHgroup 17), and modp8192 (DHgroup 18).
              It is possible to support the weak and broken  modp768  (DHgroup
              1),  but  this  requires  a  manual  recompile  and  is strongly
              discouraged.

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

       --esp esp-algos
              ESP  encryption/authentication  algorithm  to  be  used  for the
              connection (phase2 aka IPsec SA). The options must  be  suitable
              as  a  value  of  ipsec_spi(8). See ipsec.conf(5) for a detailed
              description of the algorithm format.

       --aggrmode
              This tunnel is using aggressive  mode  ISAKMP  negotiation.  The
              default  is  main mode. Aggressive mode is less secure than main
              mode as it reveals your identity  to  an  eavesdropper,  but  is
              needed   to   support   road  warriors  using  PSK  keys  or  to
              interoperate with other buggy implementations insisting on using
              aggressive mode.

       --modecfgpull
              Pull the Mode Config network information from the peer.

       --dpddelay seconds
              Set  the  delay  (in  seconds) between Dead Peer Dectection (RFC
              3706) keepalives (R_U_THERE, R_U_THERE_ACK) that  are  sent  for
              this connection (default 30 seconds).

       --timeout seconds
              Set the length of time (in seconds) we will idle without hearing
              either an R_U_THERE poll from  our  peer,  or  an  R_U_THERE_ACK
              reply.  After  this  period  has elapsed with no response and no
              traffic, we will declare  the  peer  dead,  and  remove  the  SA
              (default 120 seconds).

       --dpdaction action
              When  a DPD enabled peer is declared dead, what action should be
              taken. hold(default) means the eroute will  be  put  into  %hold
              status, while clearmeans the eroute and SA with both be cleared.
              Clear is really only usefull on the server  of  a  Road  Warrior
              config.  The  action  restart is used on tunnels that need to be
              permanently up, and have static IP addresses.

       --forceencaps
              In some cases, for example when ESP packets are filtered or when
              a  broken  IPsec peer does not properly recognise NAT, it can be
              useful to force RFC-3948 encapsulation  using  this  option.  It
              causes  pluto  lie  and  tell  the  remote  peer  that  RFC-3948
              encapsulation (ESP in UDP port 4500 packets)  is  required.  For
              this  option  to  have  any effect, pluto must have been started
              with the --nat_traversal option.

       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.

       Apart  from  initiating  directly using the --initiate option, a tunnel
       can be loaded with a different policy

       --initiateontraffic
              Only initiate the connection when we have traffic to  send  over
              the connection

       --pass Allow unencrypted traffic to flow until the tunnel is initiated.

       --drop Drop unencrypted traffic silently.

       --reject
              Drop unencrypted traffic silently,  but  send  an  ICMP  message
              notifying the other end.

       These options need to be documented

       --failnone
              to be documented

       --failpass
              to be documented

       --faildrop
              to be documented

       --failreject
              to be documented

       pluto supports various X.509 Certificate related options.

       --utc  display all times in UTC.

       --listall
              lists all of the X.509 information known to pluto.

       --listpubkeys
              list all the public keys that have been successfully loaded.

       --listcerts
              list all the X.509 certificates that are currently loaded.

       --listcacerts
              list all the X.509 Certificate Agency (CA) certificates that are
              currently loaded.

       --listacerts
              list all the X.509 Attribute  certificates  that  are  currently
              loaded

       --listaacerts

       --ocspcerts
              list  all  of  the  X.509  certificates  obtained via the Online
              Certificate Store Protocol (OCSP)

       --listgroups

       --listcrls
              list all the loaded Certificate Revocation Lists (CRLs)

       --listcards
              list all the smartcard and USB token devices.

       The     corresponding     options     --rereadsecrets,     --rereadall,
       --rereadcacerts,   --rereadacerts,  --rereadaacerts,  --rereadocspcerts
       --rereadcrls, and --purgeocsp, options  reread  this  information  from
       their   respective   sources,   and   purge  all  the  online  obtained
       information. The  option  --listevents  lists  all  pending  CRL  fetch
       commands.

       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;  AES  or  3DES encryption; SHA1-96 and
       MD5-96 authentication. The IPsec SAs may use AES or 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 3600 (one hour) and the maximum is 86400 (1
              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 28800 (eight hours) 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.

       --delete, --name connection-name
              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.

       --deletestate state-number
              The deletestate form deletes the state object with the specified
              serial number. This is useful for selectively deleting instances
              of connections.

       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
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.
       as a virtual interface. Once routing is set up, no packets will be sent
       â

       --route, --name connection-name
              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.

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

       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.

       Ending an connection

       --terminate, --name connection-name
              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).

       --crash ip-address
              If the remote peer has crashed, and therefor did not notify  us,
              we  keep  sending encrypted traffic, and rejecting all plaintext
              (non-IKE) traffic from that remote peer. The --crash brings  our
              end  down as well for all the known connections to the specified
              ip-address

       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
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.
              bytes as described in RFC 2537 â

       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.

   XAUTH
       If pluto needs additional authentication, such as defined by the  XAUTH
       specifications,  then  it  may  ask  whack  to  prompt the operator for
       username or passwords. Typically, these will be entered  interactively.
       A  GUI  that  wraps around whack may look for the 041 (username) or 040
       (password) prompts, and display them to the user.

       For testing purposes, the options --xauthuser  user   --xauthpass  pass
       may  be  be  given prior to the --initiate  to provide responses to the
       username and password prompts.

   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.

       PLUTO_MY_PROTOCOL
              lists the protocols allowed over this IPsec SA.

       PLUTO_PEER_PROTOCOL
              lists the protocols the peer allows over this IPsec SA.

       PLUTO_MY_PORT
              lists the ports allowed over this IPsec SA.

       PLUTO_PEER_PORT
              lists the ports the peer allows over this IPsec SA.

       PLUTO_MY_ID
              lists our id.

       PLUTO_PEER_ID
              Dlists our peer’s id.

       PLUTO_PEER_CA
              lists the peer’s CA.

       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 â

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

       --secretsfile file
              specifies  the  file  for   authentication   secrets   (default:
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.
              /etc/ipsec.secrets). This name is subject to â

       --adns path to adns, --lwdnsq path to lwdnsq
              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 â

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

       For example

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

       lets one test pluto without using the superuser account.

       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
| â to distinguish them from error messages.
       with â

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

       --debug-none
              disable all debugging

       --debug-all
              enable all debugging

       --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-controlmore
              show even more detailed pluto decision making

       --debug-lifecycle
              [this option is temporary] log more detail of lifecycle of SAs

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

       --debug-pfkey
              show pluto’s PFKEYinterface communication

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

       --debug-dpd
              show pluto’s Dead Peer Detection handling

       --debug-natt
              show pluto’s NAT Traversal handling

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

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

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

   Plutos 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
       If  pluto  is  compiled  without  -DKLIPS,   it   negotiates   Security
       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 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 KLIPS
       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/pluto.pid                       /var/run/pluto/pluto.ctl
       /etc/ipsec.secrets                            $IPSEC_LIBDIR/_pluto_adns
       $IPSEC_EXECDIR/lwdnsq    /dev/urandom

ENVIRONMENT

       IPSEC_LIBDIR    IPSEC_EXECDIR    IPSECmyid    PLUTO_CORE_DIR

SEE ALSO

       The rest of the Openswan 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  Openswan  distribution, describes the
       forms that IP addresses  may  take.  ipsec_atosubnet(3),  part  of  the
       Openswan  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:
       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  Openswan  web  site <htp://www.openswan.org> and the mailing lists
       described there.

HISTORY

       This code is released under the GPL terms. See the  accompanying  files
       COPYING  and  CREDITS 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:  http://www.freeswan.org>,  founded  by  John
       Gilmore  and  managed  by  Hugh  Daniel.  It  was written 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  maintained and extended by Xelerance Corporation, in
       Canada under the Openswan name. See CHANGES for details.

       FreeS/WAN was developed/maintained from 2000-2004 by D. Hugh Redelmeier
       (hugh@mimosa.com),  in  Canada.  The  regulations  of Greece and Canada
       allow the code to be 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 â
       The word â

       Bugs should be reported to the <users@lists.openswan.org> mailing list.

                                26 October 2006                 IPSEC_PLUTO(8)