Provided by: openswan_2.4.12+dfsg-1.3_i386 bug

NAME

       ipsec spi - manage IPSEC Security Associations

SYNOPSIS

       Note: In the following,

       <SA> means: --af (inet | inet6) --edst daddr --spi spi --proto proto OR
            --said said,
            <life> means: --life (soft | hard) allocations | bytes | addtime |
            usetime | packets | value <SA> --src src --ah
            (hmac-md5-96 | hmac-sha1-96) [--replay_window replayw] [<life>]
            --authkey akey
             ipsec spi <SA> --src src --esp
            (3des | 3des-md5-96 | 3des-sha1-96) [--replay_window replayw]
            [<life>] --enckey ekey
             ipsec spi <SA> --src src --esp [--replay_window replayw] [<life>]
            --enckey ekey --authkey akey
             ipsec spi <SA> --src src --comp deflate
             ipsec spi <SA> --ip4 --src encap-src --dst encap-dst
             ipsec spi <SA> --ip6 --src encap-src --dst encap-dst
             ipsec spi <SA> --del
             ipsec spi --help
             ipsec spi --version
             ipsec spi --clear

DESCRIPTION

       Spi  creates  and  deletes  IPSEC  Security  Associations.  A  Security
       Association (SA) is a transform through which packet contents are to be
       processed before being forwarded. A transform can be an IPv4-in-IPv4 or
       an   IPv6-in-IPv6   encapsulation,   an   IPSEC  Authentication  Header
       (authentication with no encryption), or an IPSEC Encapsulation Security
       Payload (encryption, possibly including authentication).

       When a packet is passed from a higher networking layer through an IPSEC
       virtual  interface,  a  search  in  the  extended  routing  table  (see
       ipsec_eroute(8))  yields  an  effective destination address, a Security
       Parameters Index (SPI) and a IP protocol number. When an  IPSEC  packet
       arrives  from the network, its ostensible destination, an SPI and an IP
       protocol  specified  by  its  outermost  IPSEC  header  are  used.  The
       destination/SPI/protocol  combination  is used to select a relevant SA.
       (See ipsec_spigrp(8) for discussion  of  how  multiple  transforms  are
       combined.)

       The  af, daddr, spi and proto arguments specify the SA to be created or
       deleted. af is the address family (inet  for  IPv4,  inet6  for  IPv6).
       Daddr  is  a destination address in dotted-decimal notation for IPv4 or
       in a coloned hex notation for IPv6. Spi is a number, preceded  by  ’0x’
       for  hexadecimal, between 0x100 and 0xffffffff; values from 0x0 to 0xff
       are reserved. Proto is an ASCII string, "ah", "esp", "comp"  or  "tun",
       specifying  the IP protocol. The protocol must agree with the algorithm
       selected.

       Alternatively, the said argument can also specify an SA to  be  created
       or  deleted.  Said  combines  the  three  parameters  above,  such  as:
       "tun.101@1.2.3.4" or "tun:101@1:2::3:4", where the  address  family  is
       specified  by  "."  for  IPv4  and  ":"  for  IPv6.  The address family
       indicators substitute the "0x" for hexadecimal.

       The source address, src, must also be provided for the  inbound  policy
       check  to  function. The source address does not need to be included if
       inbound policy checking has been disabled.

       Keys vectors must be entered as hexadecimal  or  base64  numbers.  They
       should be cryptographically strong random numbers.

       All  hexadecimal  numbers  are entered as strings of hexadecimal digits
       (0-9 and a-f), without spaces, preceded by ’0x’, where each hexadecimal
       digit  represents  4 bits. All base64 numbers are entered as strings of
       base64 digits (0-9, A-Z, a-z, ’+’ and ’/’), without spaces, preceded by
       ’0s’,  where  each  hexadecimal digit represents 6 bits and ’=’ is used
       for padding.

       The deletion of an SA which has been grouped will result in the  entire
       chain being deleted.

       The   form   with   no  additional  arguments  lists  the  contents  of
       /proc/net/ipsec_spi. The format of /proc/net/ipsec_spi is discussed  in
       ipsec_spi(5).

       The  lifetime  severity  of  soft  sets a limit when the key management
       daemons are asked to rekey the SA. The lifetime severity of hard sets a
       limit  when the SA must expire. The lifetime type allocations tells the
       system when to expire the SA because it is being  shared  by  too  many
       eroutes  (not  currently  used).  The  lifetime type of bytes tells the
       system to expire the SA after a  certain  number  of  bytes  have  been
       processed  with  that SA. The lifetime type of addtime tells the system
       to expire the  SA  a  certain  number  of  seconds  after  the  SA  was
       installed.  The lifetime type of usetime tells the system to expire the
       SA a certain number of seconds after that SA has  processed  its  first
       packet.  The lifetime type of packets tells the system to expire the SA
       after a certain number of packets have been processed with that SA.

OPTIONS

       --af   specifies the address family (inet for IPv4, inet6 for IPv6)

       --edst specifies  the  effective  destination  daddr  of  the  Security
              Association

       --spi  specifies  the  Security  Parameters  Index  spi of the Security
              Association

       --proto
              specifies the IP protocol proto of the Security Association

       --said specifies the Security Association in monolithic format

       --ah   add an SA for an IPSEC Authentication Header, specified  by  the
              following  transform  identifier  (hmac-md5-96  or hmac-sha1-96)
              (RFC2402, obsoletes RFC1826)

       hmac-md5-96
              transform following the HMAC and MD5 standards, using a  128-bit
              key to produce a 96-bit authenticator (RFC2403)

       hmac-sha1-96
              transform following the HMAC and SHA1 standards, using a 160-bit
              key to produce a 96-bit authenticator (RFC2404)

       --esp  add an SA for an IPSEC Encapsulation Security Payload, specified
              by  the  following  transform  identifier  (3des, or 3des-md5-96
              (RFC2406, obsoletes RFC1827)

       3des   encryption  transform  following  the  Triple-DES  standard   in
              Cipher-Block-Chaining   mode   using  a  64-bit  iv  (internally
              generated) and a 192-bit 3DES ekey (RFC2451)

       3des-md5-96
              encryption  transform  following  the  Triple-DES  standard   in
              Cipher-Block-Chaining  mode with authentication provided by HMAC
              and MD5 (96-bit authenticator), using a  64-bit  iv  (internally
              generated),  a  192-bit  3DES  ekey  and a 128-bit HMAC-MD5 akey
              (RFC2451, RFC2403)

       3des-sha1-96
              encryption  transform  following  the  Triple-DES  standard   in
              Cipher-Block-Chaining  mode with authentication provided by HMAC
              and SHA1 (96-bit authenticator), using a 64-bit  iv  (internally
              generated),  a  192-bit  3DES  ekey and a 160-bit HMAC-SHA1 akey
              (RFC2451, RFC2404)

       --replay_window replayw
              sets the replay window size; valid values are decimal, 1 to 64

       --life life_param[,life_param]
              sets the lifetime expiry; the format of life_param consists of a
              comma-separated  list of lifetime specifications without spaces;
              a lifetime specification is comprised of a severity of  soft  or
              hard  followed  by  a  ’-’,  followed  by  a  lifetime  type  of
              allocations, bytes, addtime, usetime or packets followed  by  an
              ’=’ and finally by a value

       --comp add  an  SA for IPSEC IP Compression, specified by the following
              transform identifier (deflate) (RFC2393)

       deflate
              compression  transform   following   the   patent-free   Deflate
              compression algorithm (RFC2394)

       --ip4  add an SA for an IPv4-in-IPv4 tunnel from encap-src to encap-dst

       --ip6  add an SA for an IPv6-in-IPv6 tunnel from encap-src to encap-dst

       --src  specify  the  source end of an IP-in-IP tunnel from encap-src to
              encap-dst and also specifies the source address of the  Security
              Association  to  be  used in inbound policy checking and must be
              the same address family as af and edst

       --dst  specify the destination end of an IP-in-IP tunnel from encap-src
              to encap-dst

       --del  delete the specified SA

       --clear
              clears the table of SAs

       --help display synopsis

       --version
              display version information

EXAMPLES

       To  keep line lengths down and reduce clutter, some of the long keys in
       these examples have been abbreviated by replacing part  of  their  text
       with  ‘‘...’’.  Keys  used  when the programs are actually run must, of
       course, be the full length required for the particular algorithm.

       ipsec spi --af inet --edst gw2 --spi 0x125 --proto esp \     --src  gw1
       \      --esp 3des-md5-96 \       --enckey 0x6630...97ce \     --authkey
       0x9941...71df

       sets up an SA from gw1 to gw2 with an SPI of  0x125  and  protocol  ESP
       (50)   using   3DES  encryption  with  integral  MD5-96  authentication
       transform,  using  an  encryption   key   of   0x6630...97ce   and   an
       authentication  key  of 0x9941...71df (see note above about abbreviated
       keys).

       ipsec spi --af inet6 --edst 3049:9::9000:3100 --spi 0x150 --proto ah  \
       --src      3049:9::9000:3101      \          --ah     hmac-md5-96     \
       --authkey 0x1234...2eda \

       sets up an SA from 3049:9::9000:3101 to 3049:9::9000:3100 with  an  SPI
       of  0x150  and  protocol AH (50) using MD5-96 authentication transform,
       using an authentication key of  0x1234...2eda  (see  note  above  about
       abbreviated keys).

       ipsec spi --said tun.987@192.168.100.100 --del

       deletes  an  SA  to  192.168.100.100  with an SPI of 0x987 and protocol
       IPv4-in-IPv4 (4).

       ipsec spi --said tun:500@3049:9::1000:1 --del

       deletes an SA to 3049:9::1000:1 with  an  SPI  of  0x500  and  protocol
       IPv6-in-IPv6 (4).

FILES

       /proc/net/ipsec_spi, /usr/bin/ipsec

SEE ALSO

       ipsec(8),     ipsec_manual(8),     ipsec_tncfg(8),     ipsec_eroute(8),
       ipsec_spigrp(8), ipsec_klipsdebug(8), ipsec_spi(5)

HISTORY

       Written for  the  Linux  FreeS/WAN  project  <http://www.freeswan.org/:
       http://www.freeswan.org/> by Richard Guy Briggs.

BUGS

       The syntax is messy and the transform naming needs work.

                                  23 Oct 2001                     IPSEC_SPI(8)