← Back to branch summary

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

« back to all changes in this revision

Viewing changes to linux/lib/libfreeswan/atoaddr.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:
linux/lib/libfreeswan/atoaddr.3
1
 
.TH IPSEC_ATOADDR 3 "11 June 2001"
2
 
.\" RCSID $Id: atoaddr.3,v 1.12 2002/04/24 07:36:42 mcr Exp $
3
 
.SH NAME
4
 
ipsec atoaddr, addrtoa \- convert Internet addresses to and from ASCII
5
 
.br
6
 
ipsec atosubnet, subnettoa \- convert subnet/mask ASCII form to and from addresses
7
 
.SH SYNOPSIS
8
 
.B "#include <freeswan.h>
9
 
.sp
10
 
.B "const char *atoaddr(const char *src, size_t srclen,"
11
 
.ti +1c
12
 
.B "struct in_addr *addr);"
13
 
.br
14
 
.B "size_t addrtoa(struct in_addr addr, int format,"
15
 
.ti +1c
16
 
.B "char *dst, size_t dstlen);"
17
 
.sp
18
 
.B "const char *atosubnet(const char *src, size_t srclen,"
19
 
.ti +1c
20
 
.B "struct in_addr *addr, struct in_addr *mask);"
21
 
.br
22
 
.B "size_t subnettoa(struct in_addr addr, struct in_addr mask,"
23
 
.ti +1c
24
 
.B "int format, char *dst, size_t dstlen);"
25
 
.SH DESCRIPTION
26
 
These functions are obsolete; see
27
 
.IR ipsec_ttoaddr (3)
28
 
for their replacements.
29
 
.PP
30
 
.I Atoaddr
31
 
converts an ASCII name or dotted-decimal address into a binary address
32
 
(in network byte order).
33
 
.I Addrtoa
34
 
does the reverse conversion, back to an ASCII dotted-decimal address.
35
 
.I Atosubnet
36
 
and
37
 
.I subnettoa
38
 
do likewise for the ``address/mask'' ASCII form used to write a
39
 
specification of a subnet.
40
 
.PP
41
 
An address is specified in ASCII as a
42
 
dotted-decimal address (e.g.
43
 
.BR 1.2.3.4 ),
44
 
an eight-digit network-order hexadecimal number with the usual C prefix (e.g.
45
 
.BR 0x01020304 ,
46
 
which is synonymous with
47
 
.BR 1.2.3.4 ),
48
 
an eight-digit host-order hexadecimal number with a
49
 
.B 0h
50
 
prefix (e.g.
51
 
.BR 0h01020304 ,
52
 
which is synonymous with
53
 
.B 1.2.3.4
54
 
on a big-endian host and
55
 
.B 4.3.2.1
56
 
on a little-endian host),
57
 
a DNS name to be looked up via
58
 
.IR gethostbyname (3),
59
 
or an old-style network name to be looked up via
60
 
.IR getnetbyname (3).
61
 
.PP
62
 
A dotted-decimal address may be incomplete, in which case
63
 
ASCII-to-binary conversion implicitly appends
64
 
as many instances of
65
 
.B .0
66
 
as necessary to bring it up to four components.
67
 
The components of a dotted-decimal address are always taken as
68
 
decimal, and leading zeros are ignored.
69
 
For example,
70
 
.B 10
71
 
is synonymous with
72
 
.BR 10.0.0.0 ,
73
 
and
74
 
.B 128.009.000.032
75
 
is synonymous with
76
 
.BR 128.9.0.32
77
 
(the latter example is verbatim from RFC 1166).
78
 
The result of
79
 
.I addrtoa
80
 
is always complete and does not contain leading zeros.
81
 
.PP
82
 
The letters in
83
 
a hexadecimal address may be uppercase or lowercase or any mixture thereof.
84
 
Use of hexadecimal addresses is
85
 
.B strongly
86
 
.BR discouraged ;
87
 
they are included only to save hassles when dealing with
88
 
the handful of perverted programs which already print 
89
 
network addresses in hexadecimal.
90
 
.PP
91
 
DNS names may be complete (optionally terminated with a ``.'')
92
 
or incomplete, and are looked up as specified by local system configuration
93
 
(see
94
 
.IR resolver (5)).
95
 
The
96
 
.I h_addr
97
 
value returned by
98
 
.IR gethostbyname (3)
99
 
is used,
100
 
so with current DNS implementations,
101
 
the result when the name corresponds to more than one address is
102
 
difficult to predict.
103
 
Name lookup resorts to
104
 
.IR getnetbyname (3)
105
 
only if
106
 
.IR gethostbyname (3)
107
 
fails.
108
 
.PP
109
 
A subnet specification is of the form \fInetwork\fB/\fImask\fR.
110
 
The
111
 
.I network
112
 
and
113
 
.I mask
114
 
can be any form acceptable to
115
 
.IR atoaddr .
116
 
In addition, the
117
 
.I mask
118
 
can be a decimal integer (leading zeros ignored) giving a bit count,
119
 
in which case
120
 
it stands for a mask with that number of high bits on and all others off
121
 
(e.g.,
122
 
.B 24
123
 
means
124
 
.BR 255.255.255.0 ).
125
 
In any case, the mask must be contiguous
126
 
(a sequence of high bits on and all remaining low bits off).
127
 
As a special case, the subnet specification
128
 
.B %default
129
 
is a synonym for
130
 
.BR 0.0.0.0/0 .
131
 
.PP
132
 
.I Atosubnet
133
 
ANDs the mask with the address before returning,
134
 
so that any non-network bits in the address are turned off
135
 
(e.g.,
136
 
.B 10.1.2.3/24
137
 
is synonymous with
138
 
.BR 10.1.2.0/24 ).
139
 
.I Subnettoa
140
 
generates the decimal-integer-bit-count
141
 
form of the mask,
142
 
with no leading zeros,
143
 
unless the mask is non-contiguous.
144
 
.PP
145
 
The
146
 
.I srclen
147
 
parameter of
148
 
.I atoaddr
149
 
and
150
 
.I atosubnet
151
 
specifies the length of the ASCII string pointed to by
152
 
.IR src ;
153
 
it is an error for there to be anything else
154
 
(e.g., a terminating NUL) within that length.
155
 
As a convenience for cases where an entire NUL-terminated string is
156
 
to be converted,
157
 
a
158
 
.I srclen
159
 
value of
160
 
.B 0
161
 
is taken to mean
162
 
.BR strlen(src) .
163
 
.PP
164
 
The
165
 
.I dstlen
166
 
parameter of
167
 
.I addrtoa
168
 
and
169
 
.I subnettoa
170
 
specifies the size of the
171
 
.I dst
172
 
parameter;
173
 
under no circumstances are more than
174
 
.I dstlen
175
 
bytes written to
176
 
.IR dst .
177
 
A result which will not fit is truncated.
178
 
.I Dstlen
179
 
can be zero, in which case
180
 
.I dst
181
 
need not be valid and no result is written,
182
 
but the return value is unaffected;
183
 
in all other cases, the (possibly truncated) result is NUL-terminated.
184
 
The
185
 
.I freeswan.h
186
 
header file defines constants,
187
 
.B ADDRTOA_BUF
188
 
and
189
 
.BR SUBNETTOA_BUF ,
190
 
which are the sizes of buffers just large enough for worst-case results.
191
 
.PP
192
 
The
193
 
.I format
194
 
parameter of
195
 
.I addrtoa
196
 
and
197
 
.I subnettoa
198
 
specifies what format is to be used for the conversion.
199
 
The value
200
 
.B 0
201
 
(not the ASCII character
202
 
.BR '0' ,
203
 
but a zero value)
204
 
specifies a reasonable default,
205
 
and is in fact the only format currently available.
206
 
This parameter is a hedge against future needs.
207
 
.PP
208
 
The ASCII-to-binary functions return NULL for success and
209
 
a pointer to a string-literal error message for failure;
210
 
see DIAGNOSTICS.
211
 
The binary-to-ASCII functions return
212
 
.B 0
213
 
for a failure, and otherwise
214
 
always return the size of buffer which would 
215
 
be needed to
216
 
accommodate the full conversion result, including terminating NUL;
217
 
it is the caller's responsibility to check this against the size of
218
 
the provided buffer to determine whether truncation has occurred.
219
 
.SH SEE ALSO
220
 
inet(3)
221
 
.SH DIAGNOSTICS
222
 
Fatal errors in
223
 
.I atoaddr
224
 
are:
225
 
empty input;
226
 
attempt to allocate temporary storage for a very long name failed;
227
 
name lookup failed;
228
 
syntax error in dotted-decimal form;
229
 
dotted-decimal component too large to fit in 8 bits.
230
 
.PP
231
 
Fatal errors in
232
 
.I atosubnet
233
 
are:
234
 
no
235
 
.B /
236
 
in
237
 
.IR src ;
238
 
.I atoaddr
239
 
error in conversion of
240
 
.I network
241
 
or
242
 
.IR mask ;
243
 
bit-count mask too big;
244
 
mask non-contiguous.
245
 
.PP
246
 
Fatal errors in
247
 
.I addrtoa
248
 
and
249
 
.I subnettoa
250
 
are:
251
 
unknown format.
252
 
.SH HISTORY
253
 
Written for the FreeS/WAN project by Henry Spencer.
254
 
.SH BUGS
255
 
The interpretation of incomplete dotted-decimal addresses
256
 
(e.g.
257
 
.B 10/24
258
 
means
259
 
.BR 10.0.0.0/24 )
260
 
differs from that of some older conversion
261
 
functions, e.g. those of
262
 
.IR inet (3).
263
 
The behavior of the older functions has never been
264
 
particularly consistent or particularly useful.
265
 
.PP
266
 
Ignoring leading zeros in dotted-decimal components and bit counts
267
 
is arguably the most useful behavior in this application,
268
 
but it might occasionally cause confusion with the historical use of leading 
269
 
zeros to denote octal numbers.
270
 
.PP
271
 
It is barely possible that somebody, somewhere,
272
 
might have a legitimate use for non-contiguous subnet masks.
273
 
.PP
274
 
.IR Getnetbyname (3)
275
 
is a historical dreg.
276
 
.PP
277
 
The restriction of ASCII-to-binary error reports to literal strings
278
 
(so that callers don't need to worry about freeing them or copying them)
279
 
does limit the precision of error reporting.
280
 
.PP
281
 
The ASCII-to-binary error-reporting convention lends itself
282
 
to slightly obscure code,
283
 
because many readers will not think of NULL as signifying success.
284
 
A good way to make it clearer is to write something like:
285
 
.PP
286
 
.RS
287
 
.nf
288
 
.B "const char *error;"
289
 
.sp
290
 
.B "error = atoaddr( /* ... */ );"
291
 
.B "if (error != NULL) {"
292
 
.B "        /* something went wrong */"
293
 
.fi
294
 
.RE