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 will start (n-1) of them, where n is the number of CPU’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.
pluto attempts to create a lockfile with the name /var/run/pluto/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. In certain configurations, pluto might also launch helper programs to assist with DNS queries or to offload cryptographic operations.
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.
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.
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 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).
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 output “on the fly”. The shutdown form tells pluto to shut down, deleting all SAs.
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 Domain Name itself (prefixed by “@” to signify that it should not be resolved), or as user@FQDN, or an X.509 DN, 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
- --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 “Net 10”.
- --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 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.
- --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 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 for a connection, all host addresses must be of the same Address Family (IPv4 and IPv6 use different Address Families).
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 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.
- --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 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 for a connection, all host addresses must be of the same Address Family (IPv4 and IPv6 use different Address Families).
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 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.
- --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 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 for a connection, all host addresses must be of the same Address Family (IPv4 and IPv6 use different Address Families).