← Back to branch summary

~ubuntu-branches/ubuntu/hardy/openswan/hardy-updates

« back to all changes in this revision

Viewing changes to programs/spi/spi.5.xml

  • Committer: Bazaar Package Importer
  • Author(s): Rene Mayrhofer
  • Date: 2005-01-27 16:10:11 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20050127161011-idgybmyz3vwhpfiq
Tags: 2.3.0-2
http://bugs.debian.org/292458
http://bugs.debian.org/291143
Urgency HIGH due to security issue and problems with build-deps in sarge.
* Fix the security issue. Please see
  http://www.idefense.com/application/poi/display?id=190&
      type=vulnerabilities&flashstatus=false
  for more details. Thanks to Martin Schulze for informing me about
  this issue.
  Closes: #292458: Openswan XAUTH/PAM Buffer Overflow Vulnerability
* Added a Build-Dependency to lynx.
  Closes: #291143: openswan: FTBFS: Missing build dependency.

Show diffs side-by-side

added added

removed removed

Lines of Context:
programs/spi/spi.5.xml
 
1
<?xml version="1.0" encoding="ISO-8859-1"?>
 
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 
3
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 
4
<!-- lifted from troff+man by doclifter -->
 
5
<refentry>
 
6
<refmeta>
 
7
<refentrytitle>IPSEC_SPI</refentrytitle>
 
8
<manvolnum>5</manvolnum>
 
9
<refmiscinfo class='date'>26 Jun 2000</refmiscinfo>
 
10
</refmeta>
 
11
<refnamediv id='name'>
 
12
<refname>ipsec_spi</refname>
 
13
<refpurpose>list IPSEC Security Associations</refpurpose>
 
14
</refnamediv>
 
15
<!-- body begins here -->
 
16
<refsynopsisdiv id='synopsis'>
 
17
<cmdsynopsis>
 
18
  <command>ipsec</command>    
 
19
    <arg choice='plain'><replaceable>spi</replaceable></arg>
 
20
    <sbr/>
 
21
    <arg choice='plain'><replaceable>cat/proc/net/ipsec_spi</replaceable></arg>
 
22
    <sbr/>
 
23
</cmdsynopsis>
 
24
</refsynopsisdiv>
 
25
 
 
26
 
 
27
<refsect1 id='description'><title>DESCRIPTION</title>
 
28
<para><filename>/proc/net/ipsec_spi</filename>
 
29
is a read-only file that lists the current IPSEC Security Associations.
 
30
A Security Association (SA) is a transform through which packet contents
 
31
are to be processed before being forwarded.  A transform can be an
 
32
IPv4-in-IPv4 or IPv6-in-IPv6 encapsulation, an IPSEC Authentication Header (authentication
 
33
with no encryption), or an IPSEC Encapsulation Security Payload
 
34
(encryption, possibly including authentication).</para>
 
35
 
 
36
<para>When a packet is passed from a higher networking layer through an IPSEC
 
37
virtual interface, a search in the extended routing table (see
 
38
<citerefentry><refentrytitle>ipsec_eroute</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
 
39
yields
 
40
a IP protocol number
 
41
,
 
42
a Security Parameters Index (SPI)
 
43
and
 
44
an effective destination address
 
45
 
 
46
When an IPSEC packet arrives from the network,
 
47
its ostensible destination, an SPI and an IP protocol
 
48
specified by its outermost IPSEC header are used.
 
49
The destination/SPI/protocol combination is used to select a relevant SA.
 
50
(See
 
51
<citerefentry><refentrytitle>ipsec_spigrp</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 
52
for discussion of how multiple transforms are combined.)</para>
 
53
 
 
54
<para>An
 
55
<emphasis remap='I'>spi ,</emphasis>
 
56
<emphasis remap='I'>proto,</emphasis>
 
57
<emphasis remap='I'>daddr</emphasis>
 
58
and
 
59
<emphasis remap='I'>address_family</emphasis>
 
60
arguments specify an SAID.
 
61
<emphasis remap='I'>Proto</emphasis>
 
62
is an ASCII string, "ah", "esp", "comp" or "tun", specifying the IP protocol.
 
63
<emphasis remap='I'>Spi</emphasis>
 
64
is a number, preceded by '.' indicating hexadecimal and IPv4 or by ':' indicating hexadecimal and IPv6,
 
65
where each hexadecimal digit represents 4 bits,
 
66
between
 
67
<emphasis remap='B'>0x100</emphasis>
 
68
and
 
69
<emphasis remap='B'>0xffffffff</emphasis>;
 
70
values from
 
71
<emphasis remap='B'>0x0</emphasis>
 
72
to
 
73
<emphasis remap='B'>0xff</emphasis>
 
74
are reserved.
 
75
<emphasis remap='I'>Daddr</emphasis>
 
76
is a dotted-decimal IPv4 destination address or a coloned hex IPv6 destination address.</para>
 
77
 
 
78
<para>An
 
79
<emphasis remap='I'>SAID</emphasis>
 
80
combines the three parameters above, such as: "tun.101@1.2.3.4" for IPv4 or "tun:101@3049:1::1" for IPv6</para>
 
81
 
 
82
<para>A table entry consists of:</para>
 
83
<variablelist remap='IP'>
 
84
  <varlistentry>
 
85
  <term>+</term>
 
86
  <listitem>
 
87
<para><emphasis remap='B'>SAID</emphasis></para>
 
88
  </listitem>
 
89
  </varlistentry>
 
90
  <varlistentry>
 
91
  <term>+</term>
 
92
  <listitem>
 
93
<para>&lt;transform name (proto,encalg,authalg)&gt;:</para>
 
94
  </listitem>
 
95
  </varlistentry>
 
96
  <varlistentry>
 
97
  <term>+</term>
 
98
  <listitem>
 
99
<para>direction (dir=)</para>
 
100
  </listitem>
 
101
  </varlistentry>
 
102
  <varlistentry>
 
103
  <term>+</term>
 
104
  <listitem>
 
105
<para>source address (src=)</para>
 
106
  </listitem>
 
107
  </varlistentry>
 
108
  <varlistentry>
 
109
  <term>+</term>
 
110
  <listitem>
 
111
<para>source and destination addresses and masks for inner header policy check
 
112
addresses (policy=), as dotted-quads or coloned hex, separated by '-&gt;',
 
113
for IPv4-in-IPv4 or IPv6-in-IPv6 SAs only</para>
 
114
  </listitem>
 
115
  </varlistentry>
 
116
  <varlistentry>
 
117
  <term>+</term>
 
118
  <listitem>
 
119
<para>initialisation vector length and value (iv_bits=, iv=) if non-zero</para>
 
120
  </listitem>
 
121
  </varlistentry>
 
122
  <varlistentry>
 
123
  <term>+</term>
 
124
  <listitem>
 
125
<para>out-of-order window size, number of out-of-order errors, sequence
 
126
number, recently received packet bitmask, maximum difference between
 
127
sequence numbers (ooowin=, ooo_errs=, seq=, bit=, max_seq_diff=) if SA
 
128
is AH or ESP and if individual items are non-zero</para>
 
129
  </listitem>
 
130
  </varlistentry>
 
131
  <varlistentry>
 
132
  <term>+</term>
 
133
  <listitem>
 
134
<para>extra flags (flags=) if any are set</para>
 
135
  </listitem>
 
136
  </varlistentry>
 
137
  <varlistentry>
 
138
  <term>+</term>
 
139
  <listitem>
 
140
<para>authenticator length in bits (alen=) if non-zero</para>
 
141
  </listitem>
 
142
  </varlistentry>
 
143
  <varlistentry>
 
144
  <term>+</term>
 
145
  <listitem>
 
146
<para>authentication key length in bits (aklen=) if non-zero</para>
 
147
  </listitem>
 
148
  </varlistentry>
 
149
  <varlistentry>
 
150
  <term>+</term>
 
151
  <listitem>
 
152
<para>authentication errors (auth_errs=) if non-zero</para>
 
153
  </listitem>
 
154
  </varlistentry>
 
155
  <varlistentry>
 
156
  <term>+</term>
 
157
  <listitem>
 
158
<para>encryption key length in bits (eklen=) if non-zero</para>
 
159
  </listitem>
 
160
  </varlistentry>
 
161
  <varlistentry>
 
162
  <term>+</term>
 
163
  <listitem>
 
164
<para>encryption size errors (encr_size_errs=) if non-zero</para>
 
165
  </listitem>
 
166
  </varlistentry>
 
167
  <varlistentry>
 
168
  <term>+</term>
 
169
  <listitem>
 
170
<para>encryption padding error warnings (encr_pad_errs=) if non-zero</para>
 
171
  </listitem>
 
172
  </varlistentry>
 
173
  <varlistentry>
 
174
  <term>+</term>
 
175
  <listitem>
 
176
<para>lifetimes legend, c=Current status, s=Soft limit when exceeded will
 
177
initiate rekeying, h=Hard limit will cause termination of SA (life(c,s,h)=)</para>
 
178
  </listitem>
 
179
  </varlistentry>
 
180
  <varlistentry>
 
181
  <term>+</term>
 
182
  <listitem>
 
183
<para>number of connections to which the SA is allocated (c), that will cause a
 
184
rekey (s), that will cause an expiry (h) (alloc=), if any value is non-zero</para>
 
185
  </listitem>
 
186
  </varlistentry>
 
187
  <varlistentry>
 
188
  <term>+</term>
 
189
  <listitem>
 
190
<para>number of bytes processesd by this SA (c), that will cause a rekey (s), that
 
191
will cause an expiry (h) (bytes=), if any value is non-zero</para>
 
192
  </listitem>
 
193
  </varlistentry>
 
194
  <varlistentry>
 
195
  <term>+</term>
 
196
  <listitem>
 
197
<para>time since the SA was added (c), until rekey (s), until expiry (h), in seconds (add=)</para>
 
198
  </listitem>
 
199
  </varlistentry>
 
200
  <varlistentry>
 
201
  <term>+</term>
 
202
  <listitem>
 
203
<para>time since the SA was first used (c), until rekey (s), until expiry (h), in seconds (used=),
 
204
if any value is non-zero</para>
 
205
  </listitem>
 
206
  </varlistentry>
 
207
  <varlistentry>
 
208
  <term>+</term>
 
209
  <listitem>
 
210
<para>number of packets processesd by this SA (c), that will cause a rekey (s), that
 
211
will cause an expiry (h) (packets=), if any value is non-zero</para>
 
212
  </listitem>
 
213
  </varlistentry>
 
214
  <varlistentry>
 
215
  <term>+</term>
 
216
  <listitem>
 
217
<para>time since the last packet was processed, in seconds (idle=), if SA has
 
218
been used</para>
 
219
 
 
220
<para>average compression ratio (ratio=)</para>
 
221
  </listitem>
 
222
  </varlistentry>
 
223
</variablelist>
 
224
</refsect1>
 
225
 
 
226
<refsect1 id='examples'><title>EXAMPLES</title>
 
227
<para><emphasis remap='B'>tun.12a@192.168.43.1 IPIP: dir=out src=192.168.43.2</emphasis>
 
228
<!-- .br -->
 
229
<emphasis remap='B'>      life(c,s,h)=bytes(14073,0,0)add(269,0,0)</emphasis>
 
230
<!-- .br -->
 
231
<emphasis remap='B'>      use(149,0,0)packets(14,0,0)</emphasis>
 
232
<!-- .br -->
 
233
<emphasis remap='B'>      idle=23</emphasis></para>
 
234
 
 
235
<para>is an outbound IPv4-in-IPv4 (protocol 4) tunnel-mode SA set up between machines
 
236
192.168.43.2 and 192.168.43.1 with an SPI of 12a in hexadecimal that has
 
237
passed about 14 kilobytes of traffic in 14 packets since it was created,
 
238
269 seconds ago, first used 149 seconds ago and has been idle for 23
 
239
seconds.</para>
 
240
 
 
241
<para><emphasis remap='B'>esp:9a35fc02@3049:1::1 ESP_3DES_HMAC_MD5:</emphasis>
 
242
<!-- .br -->
 
243
<emphasis remap='B'>      dir=in src=9a35fc02@3049:1::2</emphasis>
 
244
<!-- .br -->
 
245
<emphasis remap='B'>      ooowin=32 seq=7149 bit=0xffffffff</emphasis>
 
246
<!-- .br -->
 
247
<emphasis remap='B'>      alen=128 aklen=128 eklen=192</emphasis>
 
248
<!-- .br -->
 
249
<emphasis remap='B'>      life(c,s,h)=bytes(1222304,0,0)add(4593,0,0)</emphasis>
 
250
<!-- .br -->
 
251
<emphasis remap='B'>      use(3858,0,0)packets(7149,0,0)</emphasis>
 
252
<!-- .br -->
 
253
<emphasis remap='B'>      idle=23</emphasis></para>
 
254
 
 
255
<para>is an inbound Encapsulating Security Payload (protocol 50) SA on machine
 
256
3049:1::1 with an SPI of 9a35fc02 that uses 3DES as the encryption
 
257
cipher, HMAC MD5 as the authentication algorithm, an out-of-order
 
258
window of 32 packets, a present sequence number of 7149, every one of
 
259
the last 32 sequence numbers was received, the authenticator length and
 
260
keys is 128 bits, the encryption key is 192 bits (actually 168 for 3DES
 
261
since 1 of 8 bits is a parity bit), has passed 1.2 Mbytes of data in
 
262
7149 packets, was added 4593 seconds ago, first used
 
263
3858 seconds ago and has been idle for 23 seconds.</para>
 
264
 
 
265
</refsect1>
 
266
 
 
267
<refsect1 id='files'><title>FILES</title>
 
268
<para>/proc/net/ipsec_spi, /usr/local/bin/ipsec</para>
 
269
</refsect1>
 
270
 
 
271
<refsect1 id='see_also'><title>SEE ALSO</title>
 
272
<para>ipsec(8), ipsec_manual(8), ipsec_tncfg(5), ipsec_eroute(5),
 
273
ipsec_spigrp(5), ipsec_klipsdebug(5), ipsec_spi(8), ipsec_version(5),
 
274
ipsec_pf_key(5)</para>
 
275
</refsect1>
 
276
 
 
277
<refsect1 id='history'><title>HISTORY</title>
 
278
<para>Written for the Linux FreeS/WAN project
 
279
&lt;<ulink url='http://www.freeswan.org/'>http://www.freeswan.org/</ulink>&gt;
 
280
by Richard Guy Briggs.</para>
 
281
</refsect1>
 
282
 
 
283
<refsect1 id='bugs'><title>BUGS</title>
 
284
<para>The add and use times are awkward, displayed in seconds since machine
 
285
start.  It would be better to display them in seconds before now for
 
286
human readability.</para>
 
287
 
 
288
<!--  $Log: spi.5.xml,v $
 
289
<!--  Revision 1.1  2004/05/26 17:50:59  ken
 
290
<!--  Import XML version
 
291
<!-- -->
 
292
<!--  Revision 1.9  2002/04/24 07:35:39  mcr -->
 
293
<!--  Moved from ./klips/utils/spi.5,v -->
 
294
 
 
295
<!--  Revision 1.8  2001/08/01 23:22:44  rgb -->
 
296
<!--  Fix inconsistancies between manpage and output. -->
 
297
 
 
298
<!--  Revision 1.7  2000/11/30 16:47:28  rgb -->
 
299
<!--  Added src= to /proc/net/ipsec_spi manpage. -->
 
300
 
 
301
<!--  Revision 1.6  2000/09/17 18:56:48  rgb -->
 
302
<!--  Added IPCOMP support. -->
 
303
 
 
304
<!--  Revision 1.5  2000/09/13 15:54:32  rgb -->
 
305
<!--  Added Gerhard's ipv6 updates. -->
 
306
 
 
307
<!--  Revision 1.4  2000/07/05 17:24:03  rgb -->
 
308
<!--  Updated for relative, rather than absolute values for addtime and -->
 
309
<!--  usetime. -->
 
310
 
 
311
<!--  Revision 1.3  2000/06/30 18:21:55  rgb -->
 
312
<!--  Update SEE ALSO sections to include <citerefentry><refentrytitle>ipsec_version</refentrytitle><manvolnum>5</manvolnum></citerefentry> and <citerefentry><refentrytitle>ipsec_pf_key</refentrytitle><manvolnum>5</manvolnum></citerefentry> -->
 
313
<!--  and correct FILES sections to no longer refer to /dev/ipsec which has -->
 
314
<!--  been removed since PF_KEY does not use it. -->
 
315
 
 
316
<!--  Revision 1.2  2000/06/28 12:44:12  henry -->
 
317
<!--  format touchup -->
 
318
 
 
319
<!--  Revision 1.1  2000/06/28 05:43:00  rgb -->
 
320
<!--  Added manpages for all 5 klips utils. -->
 
321
 
 
322
 
 
323
</refsect1>
 
324
</refentry>
 
325