IPSEC(4)                  OpenBSD Programmer's Manual                 IPSEC(4)

NAME
     IPsec - IP Security Protocol

NOTE
     IPsec is enabled with the following sysctl(3) variables in
     /etc/sysctl.conf:

     net.inet.esp.enable    Enable the ESP IPsec protocol

     net.inet.ah.enable     Enable the AH IPsec protocol

DESCRIPTION
     IPsec is a pair of protocols, ESP (for Encapsulating Security Payload)
     and AH (for Authentication Header), which provide security services for
     IP datagrams.

     The internet protocol, IP, aka IPv4, does not inherently provide any pro-
     tection to your transferred data.  It does not even guarantee that the
     sender is who he says he is.  IPsec tries to remedy this.  There are sev-
     eral kinds of properties you might want to add to your communication, the
     most common are:

           Confidentiality - Make sure it is hard for anyone but the receiver
           to understand what data has been communicated.  You do not want
           anyone to see your passwords when logging into a remote machine
           over the Internet.

           Integrity - Guarantee that the data does not get changed on the
           way.  If you are on a line carrying invoicing data you probably
           want to know that the amounts and account numbers are correct and
           not altered while in-transit.

           Authenticity - Sign your data so that others can see that it is re-
           ally you that sent it.  It is clearly nice to know that documents
           are not forged.

           Replay protection - We need ways to ensure a transaction can only
           be carried out once unless we are authorized to repeat it.  I.e. it
           should not be possible for someone to record a transaction, and
           then replaying it verbatim, in order to get an effect of multiple
           transactions being received by the peer.  Consider the attacker has
           got to know what the traffic is all about by other means than
           cracking the encryption, and that the traffic causes events
           favourable for him, like depositing money into his account.  We
           need to make sure he cannot just replay that traffic later.  WARN-
           ING: as per the standards specification, replay protection is not
           performed when using manual-keyed IPsec (e.g., when using
           ipsecadm(8)).

     IPsec can provide all of these properties, in two new protocols, called
     AH, Authentication header, and ESP, Encapsulated security payload.

     ESP can provide authentication, integrity, replay protection, and confi-
     dentiality of the data (it secures everything in the packet that follows
     the IP header).  Replay protection requires authentication and integrity
     (these two go always together).  Confidentiality (encryption) can be used
     with or without authentication/integrity.  Similarly, one could use au-
     thentication/integrity with or without confidentiality.

     AH provides authentication, integrity, and replay protection (but not
     confidentiality).  Its main difference with ESP is that AH also secures
     parts of the IP header of the packet (like the source/destination ad-
     dresses).
     These protocols need some parameters for each connection, telling exactly
     how the wanted protection will be added.  These parameters are collected
     in an entity called a security association, or SA for short.  Typical pa-
     rameters are: encryption algorithm, hash algorithm, encryption key, au-
     thentication key etc.  When two peers have setup matching SAs at both
     ends, packets protected with one end's SA, will be possible to verify
     and/or decrypt using the other end's SA.  The only problem left is to see
     that both ends have matching SAa, which can be done manually, or automat-
     ically with a key management daemon.

     Further information on manual SA establishment is described in
     ipsecadm(8), and we provide two key management daemons, photurisd(8) and
     isakmpd(8).

     AH works by doing a computation of a value depending on all of the pay-
     load data, some of the IP header data and a certain secret value, the au-
     thentication key and sending this value along with the rest of each pack-
     et.  The receiver will do the same computation, and if the value matches,
     he knows no one tampered with the data (integrity), the address informa-
     tion (authenticity) or a sequence number (replay protection).  He knows
     this because the secret authentication key makes sure no man in the mid-
     dle can recompute the correct value after altering the packet.  The algo-
     rithms used for the computations are called hash algorithms and is a pa-
     rameter in the SA, just like the authentication key.

     ESP optionally does almost everything that AH does except that it does
     not protect the outer IP header but furthermore it encrypts the payload
     data with an encryption algorithm using a secret encryption key.  Only
     the ones knowing this key can decrypt the data, thus providing confiden-
     tiality.  Both the algorithm and the encryption key are parameters of the
     SA.

     In order to identify a SA we need to have a unique name for it.  This
     name is a triplet, consisting of the destination address, security param-
     eter index (aka SPI) and the security protocol.  Since the destination
     address is part of the name, a SA is a unidirectional construct.  For a
     bidirectional communication channel, two SAs are needed, one outgoing and
     one incoming, where the destination address is our local IP address.  The
     SPI is just a number that helps us making the name unique, it can be ar-
     bitrarily chosen in the range 0x100 - 0xffffffff.  The security protocol
     number should be 50 for ESP and 51 for AH, as these are the protocol num-
     bers assigned by IANA.

     IPsec can operate in two modes, either tunnel or transport mode.  In
     transport mode the ordinary IP header is used to deliver the packets to
     their endpoint, in tunnel mode the ordinary IP header just tells us the
     address of a security gateway, knowing how to verify/decrypt the payload
     and forward the packet to a destination given by another IP header con-
     tained in the protected payload.  Tunnel mode can be used for establish-
     ing VPNs, virtual private networks, where parts of the networks can be
     spread out over an unsafe public network, but security gateways at each
     subnet are responsible for encrypting and decrypting the data passing
     over the public net.  A SA will hold information telling if it is a tun-
     nel or transport mode SA, and for tunnels, it will contain values to fill
     in into the outer IP header.

     The SA also holds a couple of other parameters, especially useful for au-
     tomatic keying, called lifetimes, which puts a limit on how much we can
     use a SA for protecting our data.  These limits can be in wall-clock time
     or in volume of our data.

     To better illustrate how IPsec works, consider a typical TCP packet:

           [IP header] [TCP header] [data...]

     If we apply ESP in transport mode to the above packet, we will get:

           [IP header] [ESP header] [TCP header] [data...]

     where everything after the ESP header is protected by whatever services
     of ESP we are using (authentication/integrity, replay protection, confi-
     dentiality).  This means the IP header itself is not protected.

     If we apply ESP in tunnel mode to the original packet, we would get:

           [IP header] [ESP header] [IP header] [TCP header] [data...]

     where, again, everything after the ESP header is cryptographically pro-
     tected.  Notice the insertion of an IP header between the ESP and TCP
     header.  This mode of operation allows us to hide who the true source and
     destination addresses of a packet are (since the protected and the unpro-
     tected IP headers don't have to be exactly the same).  A typical applica-
     tion of this is in Virtual Private Networks (or VPNs), where two fire-
     walls use IPsec to secure the traffic of all the hosts behind them.  For
     example:

           Net A <----> Firewall 1 <--- Internet ---> Firewall 2 <----> Net B

     Firewall 1 and Firewall 2 can protect all communications between Net A
     and Net B by using IPsec in tunnel mode, as illustrated above.

     This implementation makes use of a virtual interface enc0, which can be
     used in packet filters to specify those packets that have been or will be
     processed by IPsec.

     NAT can also be applied to enc# interfaces, but special care should be
     taken because of the interactions between NAT and the IPsec flow match-
     ing, especially on the packet output path.  Inside the TCP/IP stack,
     packets go through the following stages:

           UL/R -> [X] -> PF/NAT(enc0) -> IPSec -> PF/NAT(IF) -> IF
           UL/R <-------- PF/NAT(enc0) <- IPSec -> PF/NAT(IF) <- IF

     With IF being the real interface and UL/R the Upper Layer or Routing
     code.  The [X] Stage on the output path represents the point where the
     packet is matched against the IPsec flow database (SPD) to determine if
     and how the packet has to be IPsec-processed.  If, at this point, it is
     determined that the packet should be IPSec-processed, it is processed by
     the PF/NAT code.  Unless PF drops the packet, it will then be IPsec-pro-
     cessed, even if the packet has been modified by NAT.

     Security Associations can be set up manually with the ipsecadm(8) utility
     or automatically with the photurisd(8) or isakmpd(8) key management dae-
     mons.

     The following IP-level setsockopt(2) and getsockopt(2) options are spe-
     cific to ipsec(4). A socket can specify security levels for three differ-
     ent categories:

     IP_AUTH_LEVEL         Specifies the use of authentication for packets
                           sent or received by the socket.

     IP_ESP_TRANS_LEVEL    Specifies the use of encryption in transport mode
                           for packets sent or received by the socket.

     IP_ESP_NETWORK_LEVEL  Specifies the use of encryption in tunnel mode.

     For each of the categories there are five possible levels which specify
     the security policy to use in that category:

     IPSEC_LEVEL_BYPASS   Bypass the default system security policy.  This op-
                          tion can only be used by privileged processes.  This
                          level is necessary for key management daemons like
                          photurisd(8) or isakmpd(8).

     IPSEC_LEVEL_AVAIL    If a Security Association is available it will be
                          used for sending packets by that socket.

     IPSEC_LEVEL_USE      Use IP Security for sending packets but still accept
                          packets which are not secured.

     IPSEC_LEVEL_REQUIRE  Use IP Security for sending packets and also require
                          IP Security for received data.

     IPSEC_LEVEL_UNIQUE   The outbound Security Association will only be used
                          by this socket.

     When a new socket is created, it is assigned the default system security
     level in each category.  These levels can be queried with getsockopt(2).
     Only a privileged process can lower the security level with a setsock-
     opt(2) call.

     For example, a server process might want to accept only authenticated
     connections to prevent session hijacking.  It would issue the following
     setsockopt(2) call:

         int level = IPSEC_LEVEL_REQUIRE;
         error = setsockopt(s, IPPROTO_IP, IP_AUTH_LEVEL, &level, sizeof(int));

     The system does guarantee that it will succeed at establishing the re-
     quired security associations.  In any case a properly configured key man-
     agement daemon is required which listens to messages from the kernel.

     A list of all security associations in the kernel tables can be obtained
     via the kernfs file <ipsec> (typically in </kern/ipsec> ).

DIAGNOSTICS
     A socket operation may fail with one of the following errors returned:

     [EACCES]  when an attempt is made to lower the security level below the
               system default by a non-privileged process.

     [EINVAL]  The length of option field did not match or an unknown security
               level was given.

     netstat(1) can be used to obtain some statistics about AH and ESP usage,
     using the -p flag.  Using the -r flag, netstat(1) displays information
     about IPsec flows.

     vmstat(8) displays information about memory use by IPsec with the -m flag
     (look for ``tdb'' and ``xform'' allocations).

BUGS
     There's a lot more to be said on this subject.  This is just a beginning.
     At the moment the socket options are not fully implemented.

SEE ALSO
     enc(4), icmp(4), inet(4), ip(4), netintro(4), tcp(4), udp(4),
     ipsecadm(8), isakmpd(8), photurisd(8), vpn(8)

ACKNOWLEDGMENTS
     The authors of the IPsec code proper are John Ioannidis, Angelos D.
     Keromytis, and Niels Provos.

     Niklas Hallqvist and Niels Provos are the authors of isakmpd(8).

     Eric Young's libdeslite was used in this implementation for the DES algo-
     rithm.
     Steve Reid's SHA-1 code was also used.

     The setsockopt(2)/getsockopt(2) interface follows somewhat loosely the
     draft-mcdonald-simple-ipsec-api, which is work in progress.

HISTORY
     The IPsec protocol design process was started in 1992 by John Ioannidis,
     Phil Karn and William Allen Simpson.  In 1995, the former wrote an imple-
     mentation for BSDI BSD/OS. Angelos D. Keromytis ported it to OpenBSD and
     NetBSD. The latest transforms and new features were implemented by Ange-
     los D. Keromytis and Niels Provos.

OpenBSD 3.0                    September 5, 1997                             5
