IPSEC_SPI(8)					     IPSEC_SPI(8)


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

       ipsec spi

       ipsec spi <SA> --src src --ah  hmac-md5-96|hmac-sha1-96	[
       --replay_window replayw ] --authkey akey

       ipsec  spi  <SA>	 --src	src  --esp 3des [ --replay_window
       replayw ] --enckey ekey

       ipsec spi <SA> --src src --esp 3des-md5-96|3des-sha1-96	[
       --replay_window replayw ] --enckey ekey --authkey akey

       ipsec  spi <SA> --src src --esp null-md5-96|null-sha1-96 [
       --replay_window replayw ] --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  for-
       warded.	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 Encapsu-
       lation 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



			   21 Jun 2000				1





IPSEC_SPI(8)					     IPSEC_SPI(8)


       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 nota-
       tion for IPv6.  Spi is a number, preceded by '0x' for hex-
       adecimal, 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 num-
       bers.  They should be cryptographically strong random num-
       bers.

       All hexadecimal numbers are entered as strings of hexadec-
       imal  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).

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




			   21 Jun 2000				2





IPSEC_SPI(8)					     IPSEC_SPI(8)


       --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, obso-
		 letes RFC1826)

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

       hmac-sha1-96
		 transform following the HMAC and SHA1 standards,
		 using	a 160-bit key to produce a 96-bit authen-
		 ticator (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)

       null-md5-96
		 encryption using  the	identity  transform  with
		 authentication	 provided by HMAC and MD5 (96-bit
		 authenticator), using a  128-bit  HMAC-MD5  akey
		 (RFC2410, RFC2403)





			   21 Jun 2000				3





IPSEC_SPI(8)					     IPSEC_SPI(8)


       null-sha1-96
		 encryption  using  the	 identity  transform with
		 authentication provided by HMAC and SHA1 (96-bit
		 authenticator),  using	 a 160-bit HMAC-SHA1 akey
		 (RFC2410, RFC2404)

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

       --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  tun-
		 nel 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



			   21 Jun 2000				4





IPSEC_SPI(8)					     IPSEC_SPI(8)


       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/local/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.
















			   21 Jun 2000				5


