← Back to branch summary

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

« back to all changes in this revision

Viewing changes to lib/libopenswan/ttoaddr.3

  • 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:
lib/libopenswan/ttoaddr.3
 
1
.TH IPSEC_TTOADDR 3 "28 Sept 2001"
 
2
.\" RCSID $Id: ttoaddr.3,v 1.12 2004/04/09 18:00:37 mcr Exp $
 
3
.SH NAME
 
4
ipsec ttoaddr, tnatoaddr, addrtot \- convert Internet addresses to and from text
 
5
.br
 
6
ipsec ttosubnet, subnettot \- convert subnet/mask text form to and from addresses
 
7
.SH SYNOPSIS
 
8
.B "#include <freeswan.h>
 
9
.sp
 
10
.B "const char *ttoaddr(const char *src, size_t srclen,"
 
11
.ti +1c
 
12
.B "int af, ip_address *addr);"
 
13
.br
 
14
.B "const char *tnatoaddr(const char *src, size_t srclen,"
 
15
.ti +1c
 
16
.B "int af, ip_address *addr);"
 
17
.br
 
18
.B "size_t addrtot(const ip_address *addr, int format,"
 
19
.ti +1c
 
20
.B "char *dst, size_t dstlen);"
 
21
.sp
 
22
.B "const char *ttosubnet(const char *src, size_t srclen,"
 
23
.ti +1c
 
24
.B "int af, ip_subnet *dst);"
 
25
.br
 
26
.B "size_t subnettot(const ip_subnet *sub, int format,"
 
27
.ti +1c
 
28
.B "char *dst, size_t dstlen);"
 
29
.SH DESCRIPTION
 
30
.I Ttoaddr
 
31
converts a text-string name or numeric address into a binary address
 
32
(in network byte order).
 
33
.I Tnatoaddr
 
34
does the same conversion,
 
35
but the only text forms it accepts are
 
36
the ``official'' forms of
 
37
numeric address (dotted-decimal for IPv4, colon-hex for IPv6).
 
38
.I Addrtot
 
39
does the reverse conversion, from binary address back to a text form.
 
40
.I Ttosubnet
 
41
and
 
42
.I subnettot
 
43
do likewise for the ``address/mask'' form used to write a
 
44
specification of a subnet.
 
45
.PP
 
46
An IPv4 address is specified in text as a
 
47
dotted-decimal address (e.g.
 
48
.BR 1.2.3.4 ),
 
49
an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
 
50
.BR 0x01020304 ,
 
51
which is synonymous with
 
52
.BR 1.2.3.4 ),
 
53
an eight-digit host-order hexadecimal number with a
 
54
.B 0h
 
55
prefix (e.g.
 
56
.BR 0h01020304 ,
 
57
which is synonymous with
 
58
.B 1.2.3.4
 
59
on a big-endian host and
 
60
.B 4.3.2.1
 
61
on a little-endian host),
 
62
a DNS name to be looked up via
 
63
.IR gethostbyname (3),
 
64
or an old-style network name to be looked up via
 
65
.IR getnetbyname (3).
 
66
.PP
 
67
A dotted-decimal address may be incomplete, in which case
 
68
text-to-binary conversion implicitly appends
 
69
as many instances of
 
70
.B .0
 
71
as necessary to bring it up to four components.
 
72
The components of a dotted-decimal address are always taken as
 
73
decimal, and leading zeros are ignored.
 
74
For example,
 
75
.B 10
 
76
is synonymous with
 
77
.BR 10.0.0.0 ,
 
78
and
 
79
.B 128.009.000.032
 
80
is synonymous with
 
81
.BR 128.9.0.32
 
82
(the latter example is verbatim from RFC 1166).
 
83
The result of applying
 
84
.I addrtot
 
85
to an IPv4 address is always complete and does not contain leading zeros.
 
86
.PP
 
87
Use of hexadecimal addresses is
 
88
.B strongly
 
89
.BR discouraged ;
 
90
they are included only to save hassles when dealing with
 
91
the handful of perverted programs which already print 
 
92
network addresses in hexadecimal.
 
93
.PP
 
94
An IPv6 address is specified in text with
 
95
colon-hex notation (e.g.
 
96
.BR 0:56:78ab:22:33:44:55:66 ),
 
97
colon-hex with
 
98
.B ::
 
99
abbreviating at most one subsequence of multiple zeros (e.g.
 
100
.BR 99:ab::54:068 ,
 
101
which is synonymous with
 
102
.BR 99:ab:0:0:0:0:54:68 ),
 
103
or a DNS name to be looked up via
 
104
.IR gethostbyname (3).
 
105
The result of applying
 
106
.I addrtot
 
107
to an IPv6 address will use
 
108
.B ::
 
109
abbreviation if possible,
 
110
and will not contain leading zeros.
 
111
.PP
 
112
The letters in hexadecimal
 
113
may be uppercase or lowercase or any mixture thereof.
 
114
.PP
 
115
DNS names may be complete (optionally terminated with a ``.'')
 
116
or incomplete, and are looked up as specified by local system configuration
 
117
(see
 
118
.IR resolver (5)).
 
119
The
 
120
.I h_addr
 
121
value returned by
 
122
.IR gethostbyname2 (3)
 
123
is used,
 
124
so with current DNS implementations,
 
125
the result when the name corresponds to more than one address is
 
126
difficult to predict.
 
127
IPv4 name lookup resorts to
 
128
.IR getnetbyname (3)
 
129
only if
 
130
.IR gethostbyname2 (3)
 
131
fails.
 
132
.PP
 
133
A subnet specification is of the form \fInetwork\fB/\fImask\fR.
 
134
The
 
135
.I network
 
136
and
 
137
.I mask
 
138
can be any form acceptable to
 
139
.IR ttoaddr .
 
140
In addition, and preferably, the
 
141
.I mask
 
142
can be a decimal integer (leading zeros ignored) giving a bit count,
 
143
in which case
 
144
it stands for a mask with that number of high bits on and all others off
 
145
(e.g.,
 
146
.B 24
 
147
in IPv4 means
 
148
.BR 255.255.255.0 ).
 
149
In any case, the mask must be contiguous
 
150
(a sequence of high bits on and all remaining low bits off).
 
151
As a special case, the subnet specification
 
152
.B %default
 
153
is a synonym for
 
154
.B 0.0.0.0/0
 
155
or
 
156
.B ::/0
 
157
in IPv4 or IPv6 respectively.
 
158
.PP
 
159
.I Ttosubnet
 
160
ANDs the mask with the address before returning,
 
161
so that any non-network bits in the address are turned off
 
162
(e.g.,
 
163
.B 10.1.2.3/24
 
164
is synonymous with
 
165
.BR 10.1.2.0/24 ).
 
166
.I Subnettot
 
167
always generates the decimal-integer-bit-count
 
168
form of the mask,
 
169
with no leading zeros.
 
170
.PP
 
171
The
 
172
.I srclen
 
173
parameter of
 
174
.I ttoaddr
 
175
and
 
176
.I ttosubnet
 
177
specifies the length of the text string pointed to by
 
178
.IR src ;
 
179
it is an error for there to be anything else
 
180
(e.g., a terminating NUL) within that length.
 
181
As a convenience for cases where an entire NUL-terminated string is
 
182
to be converted,
 
183
a
 
184
.I srclen
 
185
value of
 
186
.B 0
 
187
is taken to mean
 
188
.BR strlen(src) .
 
189
.PP
 
190
The
 
191
.I af
 
192
parameter of
 
193
.I ttoaddr
 
194
and
 
195
.I ttosubnet
 
196
specifies the address family of interest.
 
197
It should be either
 
198
.B AF_INET
 
199
or
 
200
.BR AF_INET6 .
 
201
.PP
 
202
The
 
203
.I dstlen
 
204
parameter of
 
205
.I addrtot
 
206
and
 
207
.I subnettot
 
208
specifies the size of the
 
209
.I dst
 
210
parameter;
 
211
under no circumstances are more than
 
212
.I dstlen
 
213
bytes written to
 
214
.IR dst .
 
215
A result which will not fit is truncated.
 
216
.I Dstlen
 
217
can be zero, in which case
 
218
.I dst
 
219
need not be valid and no result is written,
 
220
but the return value is unaffected;
 
221
in all other cases, the (possibly truncated) result is NUL-terminated.
 
222
The
 
223
.I freeswan.h
 
224
header file defines constants,
 
225
.B ADDRTOT_BUF
 
226
and
 
227
.BR SUBNETTOT_BUF ,
 
228
which are the sizes of buffers just large enough for worst-case results.
 
229
.PP
 
230
The
 
231
.I format
 
232
parameter of
 
233
.I addrtot
 
234
and
 
235
.I subnettot
 
236
specifies what format is to be used for the conversion.
 
237
The value
 
238
.B 0
 
239
(not the character
 
240
.BR '0' ,
 
241
but a zero value)
 
242
specifies a reasonable default,
 
243
and is in fact the only format currently available in
 
244
.IR subnettot .
 
245
.I Addrtot
 
246
also accepts format values
 
247
.B 'r'
 
248
(signifying a text form suitable for DNS reverse lookups,
 
249
e.g.
 
250
.B 4.3.2.1.IN-ADDR.ARPA.
 
251
for IPv4 and
 
252
RFC 2874 format for IPv6),
 
253
and
 
254
.B 'R'
 
255
(signifying an alternate reverse-lookup form,
 
256
an error for IPv4 and RFC 1886 format for IPv6).
 
257
Reverse-lookup names always end with a ``.''.
 
258
.PP
 
259
The text-to-binary functions return NULL for success and
 
260
a pointer to a string-literal error message for failure;
 
261
see DIAGNOSTICS.
 
262
The binary-to-text functions return
 
263
.B 0
 
264
for a failure, and otherwise
 
265
always return the size of buffer which would 
 
266
be needed to
 
267
accommodate the full conversion result, including terminating NUL;
 
268
it is the caller's responsibility to check this against the size of
 
269
the provided buffer to determine whether truncation has occurred.
 
270
.SH SEE ALSO
 
271
inet(3)
 
272
.SH DIAGNOSTICS
 
273
Fatal errors in
 
274
.I ttoaddr
 
275
are:
 
276
empty input;
 
277
unknown address family;
 
278
attempt to allocate temporary storage for a very long name failed;
 
279
name lookup failed;
 
280
syntax error in dotted-decimal or colon-hex form;
 
281
dotted-decimal or colon-hex component too large.
 
282
.PP
 
283
Fatal errors in
 
284
.I ttosubnet
 
285
are:
 
286
no
 
287
.B /
 
288
in
 
289
.IR src ;
 
290
.I ttoaddr
 
291
error in conversion of
 
292
.I network
 
293
or
 
294
.IR mask ;
 
295
bit-count mask too big;
 
296
mask non-contiguous.
 
297
.PP
 
298
Fatal errors in
 
299
.I addrtot
 
300
and
 
301
.I subnettot
 
302
are:
 
303
unknown format.
 
304
.SH HISTORY
 
305
Written for the FreeS/WAN project by Henry Spencer.
 
306
.SH BUGS
 
307
The interpretation of incomplete dotted-decimal addresses
 
308
(e.g.
 
309
.B 10/24
 
310
means
 
311
.BR 10.0.0.0/24 )
 
312
differs from that of some older conversion
 
313
functions, e.g. those of
 
314
.IR inet (3).
 
315
The behavior of the older functions has never been
 
316
particularly consistent or particularly useful.
 
317
.PP
 
318
Ignoring leading zeros in dotted-decimal components and bit counts
 
319
is arguably the most useful behavior in this application,
 
320
but it might occasionally cause confusion with the historical use of leading 
 
321
zeros to denote octal numbers.
 
322
.PP
 
323
.I Ttoaddr
 
324
does not support the mixed colon-hex-dotted-decimal
 
325
convention used to embed an IPv4 address in an IPv6 address.
 
326
.PP
 
327
.I Addrtot
 
328
always uses the
 
329
.B ::
 
330
abbreviation (which can appear only once in an address) for the
 
331
.I first
 
332
sequence of multiple zeros in an IPv6 address.
 
333
One can construct addresses (unlikely ones) in which this is suboptimal.
 
334
.PP
 
335
.I Addrtot
 
336
.B 'r'
 
337
conversion of an IPv6 address uses lowercase hexadecimal,
 
338
not the uppercase used in RFC 2874's examples.
 
339
It takes careful reading of RFCs 2874, 2673, and 2234 to realize
 
340
that lowercase is technically legitimate here,
 
341
and there may be software which botches this
 
342
and hence would have trouble with lowercase hex.
 
343
.PP
 
344
Possibly
 
345
.I subnettot
 
346
ought to recognize the
 
347
.B %default
 
348
case and generate that string as its output.
 
349
Currently it doesn't.
 
350
.PP
 
351
It is barely possible that somebody, somewhere,
 
352
might have a legitimate use for non-contiguous subnet masks.
 
353
.PP
 
354
.IR Getnetbyname (3)
 
355
is a historical dreg.
 
356
.PP
 
357
.I Tnatoaddr
 
358
probably should enforce completeness of dotted-decimal addresses.
 
359
.PP
 
360
The restriction of text-to-binary error reports to literal strings
 
361
(so that callers don't need to worry about freeing them or copying them)
 
362
does limit the precision of error reporting.
 
363
.PP
 
364
The text-to-binary error-reporting convention lends itself
 
365
to slightly obscure code,
 
366
because many readers will not think of NULL as signifying success.
 
367
A good way to make it clearer is to write something like:
 
368
.PP
 
369
.RS
 
370
.nf
 
371
.B "const char *error;"
 
372
.sp
 
373
.B "error = ttoaddr( /* ... */ );"
 
374
.B "if (error != NULL) {"
 
375
.B "        /* something went wrong */"
 
376
.fi
 
377
.RE