*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> ipsec (4)              



NAME    [Toc]    [Back]

     ipsec - IP Security Protocol

NOTE    [Toc]    [Back]

     IPsec  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

DESCRIPTION    [Toc]    [Back]

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

     The original Internet Protocol - IPv4 - does not  inherently
provide any
     protection  to  transferred  data.  Furthermore, it does not
even guarantee
     that the sender is who he claims to be.  IPsec tries to remedy this by
     providing  the  required security services for IP datagrams.
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 transit.
  If you are on a line carrying invoicing data you
           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 really
  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.  I.e. it
           should not be possible for an  attacker  to  record  a
           (such  as  a bank account withdrawal), and then by replaying it verbatim
 cause the peer to think a new message (withdrawal request)
           had  been  received.   WARNING:  as  per the standards
           replay protection is not performed when using  manualkeyed IPsec
           (e.g., when using ipsecadm(8)).

   IPsec Protocols    [Toc]    [Back]
     IPsec  provides  these services using two new protocols: AH,
     Header, and ESP, Encapsulating Security Payload.

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

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

   Security Associations (SAs)    [Toc]    [Back]
     These protocols require certain parameters for each  connection, describing
  exactly  how  the  desired protection will be achieved.
These parameters
 are collected in an entity called a  security  association, or SA for
     short.   Typical SA parameters include encryption algorithm,
hash algorithm,
 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
     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 using
 a key management daemon.

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

   Authentication Header (AH)    [Toc]    [Back]
     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
  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
     (authenticity) or a sequence number (replay protection).  He
knows this
     because  the  secret authentication key makes sure no active
attacker (manin-the-middle)
 can recompute the correct value after  altering the packet.
     The  algorithms used to compute these values are called hash
     and are parameters in the SA, just like  the  authentication

   Encapsulating Security Payload (ESP)    [Toc]    [Back]
     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 confidentiality.
   Both the algorithm and the encryption key are parameters of the

   Security Parameter Indexes (SPIs)    [Toc]    [Back]
     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 parameter
 index (aka SPI) and the security protocol (ESP or  AH).
Since the
     destination address is part of the name, an SA is necessarily a unidirectional
 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    [Toc]    [Back]
     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 contained
 in the protected payload.  Tunnel mode  can  be  used
for establishing
  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.  An SA will hold information telling if
it is a tunnel
  or  transport mode SA, and for tunnels, it will contain
values to fill
     in into the outer IP header.

   Lifetimes    [Toc]    [Back]
     The SA also holds a couple of other  parameters,  especially
useful for automatic
  keying, called lifetimes, which puts a limit on how
much we can
     use an SA for protecting our data.  These limits can  be  in
     time or in volume of our data.

   IPsec Examples    [Toc]    [Back]
     To better illustrate how IPsec works, consider a typical TCP

           [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, confidentiality).
   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 protected.
   Notice  the  insertion of an IP header between the
     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 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

           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

     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 matching,
 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) ->
           UL/R <-------- PF/NAT(enc0) <- IPsec -> PF/NAT(IF)  <-

     With IF being the real interface and UL/R the Upper Layer or
     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-processed,
 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 isakmpd(8) key management  daemon.

   API Details    [Toc]    [Back]
     The  following  IP-level setsockopt(2) and getsockopt(2) options are specific
 to ipsec.  A socket can specify  security  levels  for
three different

     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

     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,

     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
     Only a privileged process can lower the security level  with
     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,

     The system does guarantee that it will succeed at establishing the required
  security  associations.  In any case a properly configured key management
 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    [Toc]    [Back]

     A socket operation may fail with one of the following errors

     [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
     about IPsec flows.

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

SEE ALSO    [Toc]    [Back]

     enc(4),  icmp(4),  inet(4),  ip(4),   netintro(4),   tcp(4),
     ipsecadm(8), isakmpd(8), vpn(8)

HISTORY    [Toc]    [Back]

     The  IPsec  protocol  design  process was started in 1992 by
John Ioannidis,
     Phil Karn and William Allen Simpson.  In  1995,  the  former
wrote an implementation
  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.

ACKNOWLEDGMENTS    [Toc]    [Back]

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

     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

BUGS    [Toc]    [Back]

     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     3.6                        September     5,      1997
[ Back ]
 Similar pages
Name OS Title
ipsec Tru64 Internet Protocol Security Architecture
samp IRIX Security Attribute Modulation Protocol
satmp IRIX Security Attribute Token Mapping Protocol (SATMP)
satmpd IRIX Security Attribute Token Mapping Protocol Daemon
t6ext_attr IRIX Activate extended security attributes or set policy on security attribute change
db_archive Tru64 displays security database log files no longer involved in active transactions (Enhanced Security)
secconfig Tru64 Security features setup graphical interface (Enhanced Security)
secsetup Tru64 Security features setup graphical interface (Enhanced Security)
db_dump Tru64 Reads and writes the security databases (Enhanced Security)
db_checkpoint Tru64 Periodically checkpoint the security database log (Enhanced Security)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service