[thirdparty/strongswan.git] / doc / manpage.d / ipsec_satot.3.html

Content-type: text/html

<HTML><HEAD><TITLE>Manpage of IPSEC_TTOSA</TITLE>
</HEAD><BODY>
<H1>IPSEC_TTOSA</H1>
Section: C Library Functions (3)<BR>Updated: 26 Nov 2001<BR><A HREF="#index">Index</A>
<A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR>


<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>

ipsec ttosa, satot - convert IPsec Security Association IDs to and from text
<BR>

ipsec initsaid - initialize an SA ID
<A NAME="lbAC">&nbsp;</A>
<H2>SYNOPSIS</H2>

<B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

<P>
<B>typedef struct {</B>

<BR>
&nbsp;
<B>ip_address dst;</B>

<BR>
&nbsp;
<B>ipsec_spi_t spi;</B>

<BR>
&nbsp;
<B>int proto;</B>

<BR>

<B>} ip_said;</B>

<P>
<B>const char *ttosa(const char *src, size_t srclen,</B>

<BR>
&nbsp;
<B>ip_said *sa);</B>

<BR>

<B>size_t satot(const ip_said *sa, int format,</B>

<BR>
&nbsp;
<B>char *dst, size_t dstlen);</B>

<BR>

<B>void initsaid(const ip_address *addr, ipsec_spi_t spi,</B>

<BR>
&nbsp;
<B>int proto, ip_said *dst);</B>

<A NAME="lbAD">&nbsp;</A>
<H2>DESCRIPTION</H2>

<I>Ttosa</I>

converts an ASCII Security Association (SA) specifier into an
<B>ip_said</B>

structure (containing
a destination-host address
in network byte order,
an SPI number in network byte order, and
a protocol code).
<I>Satot</I>

does the reverse conversion, back to a text SA specifier.
<I>Initsaid</I>

initializes an
<B>ip_said</B>

from separate items of information.
<P>

An SA is specified in text with a mail-like syntax, e.g.
<B><A HREF="mailto:esp.5a7@1.2.3.4">esp.5a7@1.2.3.4</A></B>.

An SA specifier contains
a protocol prefix (currently
<B>ah</B>,

<B>esp</B>,

<B>tun</B>,

<B>comp</B>,

or
<B>int</B>),

a single character indicating the address family
(<B>.</B>

for IPv4,
<B>:</B>

for IPv6),
an unsigned integer SPI number in hexadecimal (with no
<B>0x</B>

prefix),
and an IP address.
The IP address can be any form accepted by
<I><A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A></I>(3),

e.g. dotted-decimal IPv4 address,
colon-hex IPv6 address,
or DNS name.
<P>

As a special case, the SA specifier
<B>%passthrough4</B>

or
<B>%passthrough6</B>

signifies the special SA used to indicate that packets should be
passed through unaltered.
(At present, these are synonyms for
<B><A HREF="mailto:tun.0@0.0.0.0">tun.0@0.0.0.0</A></B>

and
<B>tun:0@::</B>

respectively,
but that is subject to change without notice.)
<B>%passthrough</B>

is a historical synonym for
<B>%passthrough4</B>.

These forms are known to both
<I>ttosa</I>

and
<I>satot</I>,

so the internal representation is never visible.
<P>

Similarly, the SA specifiers
<B>%pass</B>,

<B>%drop</B>,

<B>%reject</B>,

<B>%hold</B>,

<B>%trap</B>,

and
<B>%trapsubnet</B>

signify special ``magic'' SAs used to indicate that packets should be
passed, dropped, rejected (dropped with ICMP notification),
held,
and trapped (sent up to
<I><A HREF="ipsec_pluto.8.html">ipsec_pluto</A></I>(8),

with either of two forms of
<B>%hold</B>

automatically installed)
respectively.
These forms too are known to both routines,
so the internal representation of the magic SAs should never be visible.
<P>

The
<B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

header file supplies the
<B>ip_said</B>

structure, as well as a data type
<B>ipsec_spi_t</B>

which is an unsigned 32-bit integer.
(There is no consistency between kernel and user on what such a type
is called, hence the header hides the differences.)
<P>

The protocol code uses the same numbers that IP does.
For user convenience, given the difficulty in acquiring the exact set of
protocol names used by the kernel,
<B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

defines the names
<B>SA_ESP</B>,

<B>SA_AH</B>,

<B>SA_IPIP</B>,

and
<B>SA_COMP</B>

to have the same values as the kernel names
<B>IPPROTO_ESP</B>,

<B>IPPROTO_AH</B>,

<B>IPPROTO_IPIP</B>,

and
<B>IPPROTO_COMP</B>.

<P>

<B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

also defines
<B>SA_INT</B>

to have the value
<B>61</B>

(reserved by IANA for ``any host internal protocol'')
and
<B>SPI_PASS</B>,

<B>SPI_DROP</B>,

<B>SPI_REJECT</B>,

<B>SPI_HOLD</B>,

and
<B>SPI_TRAP</B>

to have the values 256-260 (in <I>host</I> byte order) respectively.
These are used in constructing the magic SAs
(which always have address
<B>0.0.0.0</B>).

<P>

If
<I>satot</I>

encounters an unknown protocol code, e.g. 77,
it yields output using a prefix
showing the code numerically, e.g. ``unk77''.
This form is
<I>not</I>

recognized by
<I>ttosa</I>.

<P>

The
<I>srclen</I>

parameter of
<I>ttosa</I>

specifies the length of the string pointed to by
<I>src</I>;

it is an error for there to be anything else
(e.g., a terminating NUL) within that length.
As a convenience for cases where an entire NUL-terminated string is
to be converted,
a
<I>srclen</I>

value of
<B>0</B>

is taken to mean
<B>strlen(src)</B>.

<P>

The
<I>dstlen</I>

parameter of
<I>satot</I>

specifies the size of the
<I>dst</I>

parameter;
under no circumstances are more than
<I>dstlen</I>

bytes written to
<I>dst</I>.

A result which will not fit is truncated.
<I>Dstlen</I>

can be zero, in which case
<I>dst</I>

need not be valid and no result is written,
but the return value is unaffected;
in all other cases, the (possibly truncated) result is NUL-terminated.
The
<B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>

header file defines a constant,
<B>SATOT_BUF</B>,

which is the size of a buffer just large enough for worst-case results.
<P>

The
<I>format</I>

parameter of
<I>satot</I>

specifies what format is to be used for the conversion.
The value
<B>0</B>

(not the ASCII character
<B>'0'</B>,

but a zero value)
specifies a reasonable default
(currently
lowercase protocol prefix, lowercase hexadecimal SPI,
dotted-decimal or colon-hex address).
The value
<B>'f'</B>

is similar except that the SPI is padded with
<B>0</B>s

to a fixed 32-bit width, to ease aligning displayed tables.
<P>

<I>Ttosa</I>

returns
<B>NULL</B>

for success and
a pointer to a string-literal error message for failure;
see DIAGNOSTICS.
<I>Satot</I>

returns
<B>0</B>

for a failure, and otherwise
always returns the size of buffer which would 
be needed to
accommodate the full conversion result, including terminating NUL;
it is the caller's responsibility to check this against the size of
the provided buffer to determine whether truncation has occurred.
<P>

There is also, temporarily, support for some obsolete
forms of SA specifier which lack the address-family indicator.
<A NAME="lbAE">&nbsp;</A>
<H2>SEE ALSO</H2>

<A HREF="ipsec_ttoul.3.html">ipsec_ttoul</A>(3), <A HREF="ipsec_ttoaddr.3.html">ipsec_ttoaddr</A>(3), <A HREF="ipsec_samesaid.3.html">ipsec_samesaid</A>(3), <A HREF="inet.3.html">inet</A>(3)
<A NAME="lbAF">&nbsp;</A>
<H2>DIAGNOSTICS</H2>

Fatal errors in
<I>ttosa</I>

are:
empty input;
input too small to be a legal SA specifier;
no
<B>@</B>

in input;
unknown protocol prefix;
conversion error in
<I>ttoul</I>

or
<I>ttoaddr</I>.

<P>

Fatal errors in
<I>satot</I>

are:
unknown format.
<A NAME="lbAG">&nbsp;</A>
<H2>HISTORY</H2>

Written for the FreeS/WAN project by Henry Spencer.
<A NAME="lbAH">&nbsp;</A>
<H2>BUGS</H2>

The restriction of text-to-binary error reports to literal strings
(so that callers don't need to worry about freeing them or copying them)
does limit the precision of error reporting.
<P>

The text-to-binary error-reporting convention lends itself
to slightly obscure code,
because many readers will not think of NULL as signifying success.
A good way to make it clearer is to write something like:
<P>

<DL COMPACT><DT><DD>
<PRE>
<B>const char *error;</B>

<B>error = ttosa( /* ... */ );</B>
<B>if (error != NULL) {</B>
<B>        /* something went wrong */</B>
</PRE>

</DL>

<P>

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