← Back to branch summary

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

« back to all changes in this revision

Viewing changes to doc/manpage.d/ipsec_initsaid.3.html

  • 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:
doc/manpage.d/ipsec_initsaid.3.html
1
 
Content-type: text/html
2
 
 
3
 
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
 
<HTML><HEAD><TITLE>Man page of IPSEC_TTOSA</TITLE>
5
 
</HEAD><BODY>
6
 
<H1>IPSEC_TTOSA</H1>
7
 
Section: C Library Functions (3)<BR>Updated: 26 Nov 2001<BR><A HREF="#index">Index</A>
8
 
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
9
 
 
10
 
 
11
 
<A NAME="lbAB">&nbsp;</A>
12
 
<H2>NAME</H2>
13
 
 
14
 
ipsec ttosa, satot - convert IPsec Security Association IDs to and from text
15
 
<BR>
16
 
 
17
 
ipsec initsaid - initialize an SA ID
18
 
<A NAME="lbAC">&nbsp;</A>
19
 
<H2>SYNOPSIS</H2>
20
 
 
21
 
<B>#include &lt;<A HREF="file:///usr/include/freeswan.h">freeswan.h</A>&gt;</B>
22
 
 
23
 
<P>
24
 
<B>typedef struct {</B>
25
 
 
26
 
<BR>
27
 
&nbsp;
28
 
<B>ip_address dst;</B>
29
 
 
30
 
<BR>
31
 
&nbsp;
32
 
<B>ipsec_spi_t spi;</B>
33
 
 
34
 
<BR>
35
 
&nbsp;
36
 
<B>int proto;</B>
37
 
 
38
 
<BR>
39
 
 
40
 
<B>} ip_said;</B>
41
 
 
42
 
<P>
43
 
<B>const char *ttosa(const char *src, size_t srclen,</B>
44
 
 
45
 
<BR>
46
 
&nbsp;
47
 
<B>ip_said *sa);</B>
48
 
 
49
 
<BR>
50
 
 
51
 
<B>size_t satot(const ip_said *sa, int format,</B>
52
 
 
53
 
<BR>
54
 
&nbsp;
55
 
<B>char *dst, size_t dstlen);</B>
56
 
 
57
 
<BR>
58
 
 
59
 
<B>void initsaid(const ip_address *addr, ipsec_spi_t spi,</B>
60
 
 
61
 
<BR>
62
 
&nbsp;
63
 
<B>int proto, ip_said *dst);</B>
64
 
 
65
 
<A NAME="lbAD">&nbsp;</A>
66
 
<H2>DESCRIPTION</H2>
67
 
 
68
 
<I>Ttosa</I>
69
 
 
70
 
converts an ASCII Security Association (SA) specifier into an
71
 
<B>ip_said</B>
72
 
 
73
 
structure (containing
74
 
a destination-host address
75
 
in network byte order,
76
 
an SPI number in network byte order, and
77
 
a protocol code).
78
 
<I>Satot</I>
79
 
 
80
 
does the reverse conversion, back to a text SA specifier.
81
 
<I>Initsaid</I>
82
 
 
83
 
initializes an
84
 
<B>ip_said</B>
85
 
 
86
 
from separate items of information.
87
 
<P>
88
 
 
89
 
An SA is specified in text with a mail-like syntax, e.g.
90
 
<B><A HREF="mailto:esp.5a7@1.2.3.4">esp.5a7@1.2.3.4</A></B>.
91
 
 
92
 
An SA specifier contains
93
 
a protocol prefix (currently
94
 
<B>ah</B>,
95
 
 
96
 
<B>esp</B>,
97
 
 
98
 
<B>tun</B>,
99
 
 
100
 
<B>comp</B>,
101
 
 
102
 
or
103
 
<B>int</B>),
104
 
 
105
 
a single character indicating the address family
106
 
(<B>.</B>
107
 
 
108
 
for IPv4,
109
 
<B>:</B>
110
 
 
111
 
for IPv6),
112
 
an unsigned integer SPI number in hexadecimal (with no
113
 
<B>0x</B>
114
 
 
115
 
prefix),
116
 
and an IP address.
117
 
The IP address can be any form accepted by
118
 
<I><A HREF="/cgi-bin/man/man2html?3+ipsec_ttoaddr">ipsec_ttoaddr</A></I>(3),
119
 
 
120
 
e.g. dotted-decimal IPv4 address,
121
 
colon-hex IPv6 address,
122
 
or DNS name.
123
 
<P>
124
 
 
125
 
As a special case, the SA specifier
126
 
<B>%passthrough4</B>
127
 
 
128
 
or
129
 
<B>%passthrough6</B>
130
 
 
131
 
signifies the special SA used to indicate that packets should be
132
 
passed through unaltered.
133
 
(At present, these are synonyms for
134
 
<B><A HREF="mailto:tun.0@0.0.0.0">tun.0@0.0.0.0</A></B>
135
 
 
136
 
and
137
 
<B>tun:0@::</B>
138
 
 
139
 
respectively,
140
 
but that is subject to change without notice.)
141
 
<B>%passthrough</B>
142
 
 
143
 
is a historical synonym for
144
 
<B>%passthrough4</B>.
145
 
 
146
 
These forms are known to both
147
 
<I>ttosa</I>
148
 
 
149
 
and
150
 
<I>satot</I>,
151
 
 
152
 
so the internal representation is never visible.
153
 
<P>
154
 
 
155
 
Similarly, the SA specifiers
156
 
<B>%pass</B>,
157
 
 
158
 
<B>%drop</B>,
159
 
 
160
 
<B>%reject</B>,
161
 
 
162
 
<B>%hold</B>,
163
 
 
164
 
<B>%trap</B>,
165
 
 
166
 
and
167
 
<B>%trapsubnet</B>
168
 
 
169
 
signify special ``magic'' SAs used to indicate that packets should be
170
 
passed, dropped, rejected (dropped with ICMP notification),
171
 
held,
172
 
and trapped (sent up to
173
 
<I><A HREF="/cgi-bin/man/man2html?8+ipsec_pluto">ipsec_pluto</A></I>(8),
174
 
 
175
 
with either of two forms of
176
 
<B>%hold</B>
177
 
 
178
 
automatically installed)
179
 
respectively.
180
 
These forms too are known to both routines,
181
 
so the internal representation of the magic SAs should never be visible.
182
 
<P>
183
 
 
184
 
The
185
 
<B>&lt;<A HREF="file:///usr/include/freeswan.h">freeswan.h</A>&gt;</B>
186
 
 
187
 
header file supplies the
188
 
<B>ip_said</B>
189
 
 
190
 
structure, as well as a data type
191
 
<B>ipsec_spi_t</B>
192
 
 
193
 
which is an unsigned 32-bit integer.
194
 
(There is no consistency between kernel and user on what such a type
195
 
is called, hence the header hides the differences.)
196
 
<P>
197
 
 
198
 
The protocol code uses the same numbers that IP does.
199
 
For user convenience, given the difficulty in acquiring the exact set of
200
 
protocol names used by the kernel,
201
 
<B>&lt;<A HREF="file:///usr/include/freeswan.h">freeswan.h</A>&gt;</B>
202
 
 
203
 
defines the names
204
 
<B>SA_ESP</B>,
205
 
 
206
 
<B>SA_AH</B>,
207
 
 
208
 
<B>SA_IPIP</B>,
209
 
 
210
 
and
211
 
<B>SA_COMP</B>
212
 
 
213
 
to have the same values as the kernel names
214
 
<B>IPPROTO_ESP</B>,
215
 
 
216
 
<B>IPPROTO_AH</B>,
217
 
 
218
 
<B>IPPROTO_IPIP</B>,
219
 
 
220
 
and
221
 
<B>IPPROTO_COMP</B>.
222
 
 
223
 
<P>
224
 
 
225
 
<B>&lt;<A HREF="file:///usr/include/freeswan.h">freeswan.h</A>&gt;</B>
226
 
 
227
 
also defines
228
 
<B>SA_INT</B>
229
 
 
230
 
to have the value
231
 
<B>61</B>
232
 
 
233
 
(reserved by IANA for ``any host internal protocol'')
234
 
and
235
 
<B>SPI_PASS</B>,
236
 
 
237
 
<B>SPI_DROP</B>,
238
 
 
239
 
<B>SPI_REJECT</B>,
240
 
 
241
 
<B>SPI_HOLD</B>,
242
 
 
243
 
and
244
 
<B>SPI_TRAP</B>
245
 
 
246
 
to have the values 256-260 (in <I>host</I> byte order) respectively.
247
 
These are used in constructing the magic SAs
248
 
(which always have address
249
 
<B>0.0.0.0</B>).
250
 
 
251
 
<P>
252
 
 
253
 
If
254
 
<I>satot</I>
255
 
 
256
 
encounters an unknown protocol code, e.g. 77,
257
 
it yields output using a prefix
258
 
showing the code numerically, e.g. ``unk77''.
259
 
This form is
260
 
<I>not</I>
261
 
 
262
 
recognized by
263
 
<I>ttosa</I>.
264
 
 
265
 
<P>
266
 
 
267
 
The
268
 
<I>srclen</I>
269
 
 
270
 
parameter of
271
 
<I>ttosa</I>
272
 
 
273
 
specifies the length of the string pointed to by
274
 
<I>src</I>;
275
 
 
276
 
it is an error for there to be anything else
277
 
(e.g., a terminating NUL) within that length.
278
 
As a convenience for cases where an entire NUL-terminated string is
279
 
to be converted,
280
 
a
281
 
<I>srclen</I>
282
 
 
283
 
value of
284
 
<B>0</B>
285
 
 
286
 
is taken to mean
287
 
<B>strlen(src)</B>.
288
 
 
289
 
<P>
290
 
 
291
 
The
292
 
<I>dstlen</I>
293
 
 
294
 
parameter of
295
 
<I>satot</I>
296
 
 
297
 
specifies the size of the
298
 
<I>dst</I>
299
 
 
300
 
parameter;
301
 
under no circumstances are more than
302
 
<I>dstlen</I>
303
 
 
304
 
bytes written to
305
 
<I>dst</I>.
306
 
 
307
 
A result which will not fit is truncated.
308
 
<I>Dstlen</I>
309
 
 
310
 
can be zero, in which case
311
 
<I>dst</I>
312
 
 
313
 
need not be valid and no result is written,
314
 
but the return value is unaffected;
315
 
in all other cases, the (possibly truncated) result is NUL-terminated.
316
 
The
317
 
<B>&lt;<A HREF="file:///usr/include/freeswan.h">freeswan.h</A>&gt;</B>
318
 
 
319
 
header file defines a constant,
320
 
<B>SATOT_BUF</B>,
321
 
 
322
 
which is the size of a buffer just large enough for worst-case results.
323
 
<P>
324
 
 
325
 
The
326
 
<I>format</I>
327
 
 
328
 
parameter of
329
 
<I>satot</I>
330
 
 
331
 
specifies what format is to be used for the conversion.
332
 
The value
333
 
<B>0</B>
334
 
 
335
 
(not the ASCII character
336
 
<B>'0'</B>,
337
 
 
338
 
but a zero value)
339
 
specifies a reasonable default
340
 
(currently
341
 
lowercase protocol prefix, lowercase hexadecimal SPI,
342
 
dotted-decimal or colon-hex address).
343
 
The value
344
 
<B>'f'</B>
345
 
 
346
 
is similar except that the SPI is padded with
347
 
<B>0</B>s
348
 
 
349
 
to a fixed 32-bit width, to ease aligning displayed tables.
350
 
<P>
351
 
 
352
 
<I>Ttosa</I>
353
 
 
354
 
returns
355
 
<B>NULL</B>
356
 
 
357
 
for success and
358
 
a pointer to a string-literal error message for failure;
359
 
see DIAGNOSTICS.
360
 
<I>Satot</I>
361
 
 
362
 
returns
363
 
<B>0</B>
364
 
 
365
 
for a failure, and otherwise
366
 
always returns the size of buffer which would 
367
 
be needed to
368
 
accommodate the full conversion result, including terminating NUL;
369
 
it is the caller's responsibility to check this against the size of
370
 
the provided buffer to determine whether truncation has occurred.
371
 
<P>
372
 
 
373
 
There is also, temporarily, support for some obsolete
374
 
forms of SA specifier which lack the address-family indicator.
375
 
<A NAME="lbAE">&nbsp;</A>
376
 
<H2>SEE ALSO</H2>
377
 
 
378
 
<A HREF="/cgi-bin/man/man2html?3+ipsec_ttoul">ipsec_ttoul</A>(3), <A HREF="/cgi-bin/man/man2html?3+ipsec_ttoaddr">ipsec_ttoaddr</A>(3), <A HREF="/cgi-bin/man/man2html?3+ipsec_samesaid">ipsec_samesaid</A>(3), <A HREF="/cgi-bin/man/man2html?3+inet">inet</A>(3)
379
 
<A NAME="lbAF">&nbsp;</A>
380
 
<H2>DIAGNOSTICS</H2>
381
 
 
382
 
Fatal errors in
383
 
<I>ttosa</I>
384
 
 
385
 
are:
386
 
empty input;
387
 
input too small to be a legal SA specifier;
388
 
no
389
 
<B>@</B>
390
 
 
391
 
in input;
392
 
unknown protocol prefix;
393
 
conversion error in
394
 
<I>ttoul</I>
395
 
 
396
 
or
397
 
<I>ttoaddr</I>.
398
 
 
399
 
<P>
400
 
 
401
 
Fatal errors in
402
 
<I>satot</I>
403
 
 
404
 
are:
405
 
unknown format.
406
 
<A NAME="lbAG">&nbsp;</A>
407
 
<H2>HISTORY</H2>
408
 
 
409
 
Written for the FreeS/WAN project by Henry Spencer.
410
 
<A NAME="lbAH">&nbsp;</A>
411
 
<H2>BUGS</H2>
412
 
 
413
 
The restriction of text-to-binary error reports to literal strings
414
 
(so that callers don't need to worry about freeing them or copying them)
415
 
does limit the precision of error reporting.
416
 
<P>
417
 
 
418
 
The text-to-binary error-reporting convention lends itself
419
 
to slightly obscure code,
420
 
because many readers will not think of NULL as signifying success.
421
 
A good way to make it clearer is to write something like:
422
 
<P>
423
 
 
424
 
<DL COMPACT><DT><DD>
425
 
<PRE>
426
 
<B>const char *error;</B>
427
 
 
428
 
<B>error = ttosa( /* ... */ );</B>
429
 
<B>if (error != NULL) {</B>
430
 
<B>        /* something went wrong */</B>
431
 
</PRE>
432
 
 
433
 
</DL>
434
 
 
435
 
<P>
436
 
 
437
 
<HR>
438
 
<A NAME="index">&nbsp;</A><H2>Index</H2>
439
 
<DL>
440
 
<DT><A HREF="#lbAB">NAME</A><DD>
441
 
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
442
 
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
443
 
<DT><A HREF="#lbAE">SEE ALSO</A><DD>
444
 
<DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
445
 
<DT><A HREF="#lbAG">HISTORY</A><DD>
446
 
<DT><A HREF="#lbAH">BUGS</A><DD>
447
 
</DL>
448
 
<HR>
449
 
This document was created by
450
 
<A HREF="/cgi-bin/man/man2html">man2html</A>,
451
 
using the manual pages.<BR>
452
 
Time: 10:29:41 GMT, June 17, 2004
453
 
</BODY>
454
 
</HTML>