freeswan/klips/utils/spi.5

   1 .TH IPSEC_SPI 5 "26 Jun 2000"
   2 .\"
   3 .\" RCSID $Id: spi.5,v 1.8 2001/08/01 23:22:44 rgb Exp $
   4 .\"
   5 .SH NAME
   6 ipsec_spi \- list IPSEC Security Associations
   7 .SH SYNOPSIS
   8 .B ipsec
   9 .B spi
  10 .PP
  11 .B cat
  12 .B /proc/net/ipsec_spi
  13 .PP
  14 .SH DESCRIPTION
  15 .I /proc/net/ipsec_spi
  16 is a read-only file that lists the current IPSEC Security Associations.
  17 A Security Association (SA) is a transform through which packet contents
  18 are to be processed before being forwarded.  A transform can be an
  19 IPv4-in-IPv4 or IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication
  20 with no encryption), or an IPSEC Encapsulation Security Payload
  21 (encryption, possibly including authentication).
  22 .PP
  23 When a packet is passed from a higher networking layer through an IPSEC
  24 virtual interface, a search in the extended routing table (see
  25 .IR ipsec_eroute (5))
  26 yields
  27 a IP protocol number
  28 ,
  29 a Security Parameters Index (SPI)
  30 and
  31 an effective destination address
  32 .
  33 When an IPSEC packet arrives from the network,
  34 its ostensible destination, an SPI and an IP protocol
  35 specified by its outermost IPSEC header are used.
  36 The destination/SPI/protocol combination is used to select a relevant SA.
  37 (See
  38 .IR ipsec_spigrp (5)
  39 for discussion of how multiple transforms are combined.)
  40 .PP
  41 An
  42 .I spi ,
  43 .I proto,
  44 .I daddr
  45 and
  46 .IR address_family
  47 arguments specify an SAID.
  48 .I Proto
  49 is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol.
  50 .I Spi
  51 is a number, preceded by '.' indicating hexadecimal and IPv4 or by ':' indicating hexadecimal and IPv6,
  52 where each hexadecimal digit represents 4 bits,
  53 between
  54 .B 0x100
  55 and
  56 .BR 0xffffffff ;
  57 values from
  58 .B 0x0
  59 to
  60 .B 0xff
  61 are reserved.
  62 .I Daddr
  63 is a dotted-decimal IPv4 destination address or a coloned hex IPv6 destination address.
  64 .PP
  65 An
  66 .I SAID
  67 combines the three parameters above, such as: "tun.101@1.2.3.4" for IPv4 or "tun:101@3049:1::1" for IPv6
  68 .PP
  69 A table entry consists of:
  70 .IP + 3
  71 .BR SAID
  72 .IP +
  73 <transform name (proto,encalg,authalg)>:
  74 .IP +
  75 direction (dir=)
  76 .IP +
  77 source address (src=)
  78 .IP +
  79 source and destination addresses and masks for inner header policy check
  80 addresses (policy=), as dotted-quads or coloned hex, separated by '->',
  81 for IPv4-in-IPv4 or IPv6-in-IPv6 SAs only
  82 .IP +
  83 initialisation vector length and value (iv_bits=, iv=) if non-zero
  84 .IP +
  85 out-of-order window size, number of out-of-order errors, sequence
  86 number, recently received packet bitmask, maximum difference between
  87 sequence numbers (ooowin=, ooo_errs=, seq=, bit=, max_seq_diff=) if SA
  88 is AH or ESP and if individual items are non-zero
  89 .IP +
  90 extra flags (flags=) if any are set
  91 .IP +
  92 authenticator length in bits (alen=) if non-zero
  93 .IP +
  94 authentication key length in bits (aklen=) if non-zero
  95 .IP +
  96 authentication errors (auth_errs=) if non-zero
  97 .IP +
  98 encryption key length in bits (eklen=) if non-zero
  99 .IP +
 100 encryption size errors (encr_size_errs=) if non-zero
 101 .IP +
 102 encryption padding error warnings (encr_pad_errs=) if non-zero
 103 .IP +
 104 lifetimes legend, c=Current status, s=Soft limit when exceeded will
 105 initiate rekeying, h=Hard limit will cause termination of SA (life(c,s,h)=)
 106 .IP + 6
 107 number of connections to which the SA is allocated (c), that will cause a
 108 rekey (s), that will cause an expiry (h) (alloc=), if any value is non-zero
 109 .IP +
 110 number of bytes processesd by this SA (c), that will cause a rekey (s), that
 111 will cause an expiry (h) (bytes=), if any value is non-zero
 112 .IP +
 113 time since the SA was added (c), until rekey (s), until expiry (h), in seconds (add=)
 114 .IP +
 115 time since the SA was first used (c), until rekey (s), until expiry (h), in seconds (used=),
 116 if any value is non-zero
 117 .IP +
 118 number of packets processesd by this SA (c), that will cause a rekey (s), that
 119 will cause an expiry (h) (packets=), if any value is non-zero
 120 .IP + 3
 121 time since the last packet was processed, in seconds (idle=), if SA has
 122 been used
 123 .IP
 124 average compression ratio (ratio=)
 125 .SH EXAMPLES
 126 .B "tun.12a@192.168.43.1 IPIP: dir=out src=192.168.43.2"
 127 .br
 128 .B "      life(c,s,h)=bytes(14073,0,0)add(269,0,0)"
 129 .br
 130 .B "      use(149,0,0)packets(14,0,0)"
 131 .br
 132 .B "      idle=23
 133 .LP
 134 is an outbound IPv4-in-IPv4 (protocol 4) tunnel-mode SA set up between machines
 135 192.168.43.2 and 192.168.43.1 with an SPI of 12a in hexadecimal that has
 136 passed about 14 kilobytes of traffic in 14 packets since it was created,
 137 269 seconds ago, first used 149 seconds ago and has been idle for 23
 138 seconds.
 139 .LP
 140 .B "esp:9a35fc02@3049:1::1 ESP_3DES_HMAC_MD5:"
 141 .br
 142 .B "      dir=in src=9a35fc02@3049:1::2"
 143 .br
 144 .B "      ooowin=32 seq=7149 bit=0xffffffff"
 145 .br
 146 .B "      alen=128 aklen=128 eklen=192"
 147 .br
 148 .B "      life(c,s,h)=bytes(1222304,0,0)add(4593,0,0)"
 149 .br
 150 .B "      use(3858,0,0)packets(7149,0,0)"
 151 .br
 152 .B "      idle=23"
 153 .LP
 154 is an inbound Encapsulating Security Payload (protocol 50) SA on machine
 155 3049:1::1 with an SPI of 9a35fc02 that uses 3DES as the encryption
 156 cipher, HMAC MD5 as the authentication algorithm, an out-of-order
 157 window of 32 packets, a present sequence number of 7149, every one of
 158 the last 32 sequence numbers was received, the authenticator length and
 159 keys is 128 bits, the encryption key is 192 bits (actually 168 for 3DES
 160 since 1 of 8 bits is a parity bit), has passed 1.2 Mbytes of data in
 161 7149 packets, was added 4593 seconds ago, first used
 162 3858 seconds ago and has been idle for 23 seconds.
 163 .LP
 164 .SH FILES
 165 /proc/net/ipsec_spi, /usr/local/bin/ipsec
 166 .SH "SEE ALSO"
 167 ipsec(8), ipsec_manual(8), ipsec_tncfg(5), ipsec_eroute(5),
 168 ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_spi(8), ipsec_version(5),
 169 ipsec_pf_key(5)
 170 .SH HISTORY
 171 Written for the Linux FreeS/WAN project
 172 <http://www.freeswan.org/>
 173 by Richard Guy Briggs.
 174 .SH BUGS
 175 The add and use times are awkward, displayed in seconds since machine
 176 start.  It would be better to display them in seconds before now for
 177 human readability.
 178 .\"
 179 .\" $Log: spi.5,v $
 180 .\" Revision 1.8  2001/08/01 23:22:44  rgb
 181 .\" Fix inconsistancies between manpage and output.
 182 .\"
 183 .\" Revision 1.7  2000/11/30 16:47:28  rgb
 184 .\" Added src= to /proc/net/ipsec_spi manpage.
 185 .\"
 186 .\" Revision 1.6  2000/09/17 18:56:48  rgb
 187 .\" Added IPCOMP support.
 188 .\"
 189 .\" Revision 1.5  2000/09/13 15:54:32  rgb
 190 .\" Added Gerhard's ipv6 updates.
 191 .\"
 192 .\" Revision 1.4  2000/07/05 17:24:03  rgb
 193 .\" Updated for relative, rather than absolute values for addtime and
 194 .\" usetime.
 195 .\"
 196 .\" Revision 1.3  2000/06/30 18:21:55  rgb
 197 .\" Update SEE ALSO sections to include ipsec_version(5) and ipsec_pf_key(5)
 198 .\" and correct FILES sections to no longer refer to /dev/ipsec which has
 199 .\" been removed since PF_KEY does not use it.
 200 .\"
 201 .\" Revision 1.2  2000/06/28 12:44:12  henry
 202 .\" format touchup
 203 .\"
 204 .\" Revision 1.1  2000/06/28 05:43:00  rgb
 205 .\" Added manpages for all 5 klips utils.
 206 .\"
 207 .\"