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

NAME
     ipsec - IP Security Protocol

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

     Both protocols may be enabled or disabled using the following sysctl(3)
     variables in /etc/sysctl.conf.  By default, both protocols are enabled:

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

     There are four main security properties provided by IPsec:

           Confidentiality - Ensure it is hard for anyone but the receiver to
           understand what data has been communicated.  For example, ensuring
           the secrecy of passwords when logging into a remote machine over
           the Internet.

           Integrity - Guarantee that the data does not get changed in tran-
           sit.  If you are on a line carrying invoicing data you probably
           want to know that the amounts and account numbers are correct and
           have not been modified by a third party.

           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 datagram is processed
           only once, regardless of how many times it is received.  That is,
           it should not be possible for an attacker to record a transaction
           (such as a bank account withdrawal), and then by replaying it ver-
           batim cause the peer to think a new message (withdrawal request)
           had been received.  WARNING: as per the standard's specification,
           replay protection is not performed when using manual-keyed IPsec
           (e.g. when using ipsecctl(8)).

   IPsec Protocols
     IPsec provides these services using two new protocols: Authentication
     Header (AH), and Encapsulating Security Payload (ESP).

     ESP can provide the properties authentication, integrity, replay protec-
     tion, and confidentiality of the data (it secures everything in the pack-
     et that follows the IP header).  Replay protection requires authentica-
     tion and integrity (these two always go together).  Confidentiality (en-
     cryption) can be used with or without authentication/integrity.  Similar-
     ly, one could use authentication/integrity with or without confidentiali-
     ty.

     AH provides authentication, integrity, and replay protection (but not
     confidentiality).  The main difference between the authentication fea-
     tures of AH and ESP is that AH also authenticates portions of the IP
     header of the packet (such as the source/destination addresses).  ESP au-
     thenticates only the packet payload.

   Authentication Header (AH)
     AH works by computing a value that depends on all of the payload data,
     some of the IP header data, and a certain secret value (the authentica-
     tion key).  This value is then sent with the rest of each packet.  The
     receiver performs the same computation, and if the value matches, he
     knows no one tampered with the data (integrity), the address information
     (authenticity) or a sequence number (replay protection).  He knows this
     because the secret authentication key makes sure no active attacker (man-
     in-the-middle) can recompute the correct value after altering the packet.
     The algorithms used to compute these values are called hash algorithms
     and are parameters in the SA, just like the authentication key.

   Encapsulating Security Payload (ESP)
     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.

   Security Associations (SAs)
     These protocols require certain parameters for each connection, describ-
     ing exactly how the desired protection will be achieved.  These parame-
     ters are collected in an entity called a security association, or SA for
     short.  Typical SA parameters include encryption algorithm, hash algo-
     rithm, encryption key, and authentication key, to name a few.  When two
     peers have established matching SAs (one at each end), packets protected
     with one end's SA may be verified and/or decrypted using the information
     in the other end's SA.  The only issue remaining is to ensure that both
     ends have matching SAs.  This may be done manually, or automatically us-
     ing a key management daemon.

     Further information on manual SA establishment is described in
     ipsecctl(8).  Information on automated key management may be found in
     isakmpd(8).

   Security Parameter Indexes (SPIs)
     In order to identify an 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 (ESP or AH).  Since the
     destination address is part of the name, an SA is necessarily a unidirec-
     tional construct.  For a bidirectional communication channel, two SAs are
     required, one outgoing and one incoming, where the destination address is
     our local IP address.  The SPI is just a number that helps us make the
     name unique; it can be arbitrarily chosen in the range 0x100 -
     0xffffffff.  The security protocol number should be 50 for ESP and 51 for
     AH, as these are the protocol numbers assigned by IANA.

   Modes of Operation
     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 which knows how to verify/decrypt the pay-
     load and forward the packet to a destination given by another IP header
     contained in the protected payload.  Tunnel mode can be used for estab-
     lishing virtual private networks (VPNs), 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 pass-
     ing over the public net.  An SA will contain information specifying
     whether it is a tunnel or transport mode SA, and for tunnels it will con-
     tain values to fill in into the outer IP header.

   Lifetimes
     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 an SA for protecting our data.  These limits can be in wall-clock
     time or in volume of our data.

   IPsec Examples
     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...]

     Everything after the ESP header is protected by whatever services of ESP
     we are using (authentication/integrity, replay protection, confidentiali-
     ty).  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...]

     Again, everything after the ESP header is cryptographically protected.
     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 destina-
     tion addresses of a packet are (since the protected and the unprotected
     IP headers don't have to be exactly the same).  A typical application of
     this is in Virtual Private Networks (or VPNs), where two firewalls 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 ipsecctl(8) or automat-
     ically with the isakmpd(8) key management daemon.

   Additional Variables
     A number of sysctl(8) variables are relevant to ipsec.  These are gener-
     ally net.inet.ah.*, net.inet.esp.*, net.inet.ip.forwarding,
     net.inet6.ip6.forwarding, and net.inet.ip.ipsec-*.  Full explanations can
     be found in sysctl(3), and variables can be set using the sysctl(8) in-
     terface.

     A number of kernel options are also relevant to ipsec.  See options(4)
     for further information.

   API Details
     The following IP-level setsockopt(2) and getsockopt(2) options are spe-
     cific to ipsec.  A socket can specify security levels for three different
     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
                            option can only be used by privileged processes.
                            This level is necessary for the key management
                            daemon, 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 ac-
                            cept packets which are not secured.

       IPSEC_LEVEL_REQUIRE  Use IP Security for sending packets and also re-
                            quire 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
     setsockopt(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
     using the ipsecctl(8) command.

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

     [EACCES]  An attempt was made to lower the security level below the sys-
               tem 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).

SEE ALSO
     enc(4), options(4), ipsecctl(8), isakmpd(8), sysctl(8)

HISTORY
     IPsec was originally designed to provide security services for Internet
     Protocol IPv6.  It has since been engineered to provide those services
     for the original Internet Protocol, IPv4.

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

AUTHORS
     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 (since expired, but still available from
     ftp://ftp.kame.net/pub/internet-drafts/).

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.

OpenBSD 4.7                      May 31, 2007                                5
