Provided by: openswan_2.6.23+dfsg-1ubuntu1_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/> by
       Richard Guy Briggs.

BUGS

       The syntax is messy and the transform naming needs work.