freeswan/doc/manpage.d/ipsec_satoa.3.html

   1 Content-type: text/html
   2
   3 <HTML><HEAD><TITLE>Manpage of IPSEC_ATOSA</TITLE>
   4 </HEAD><BODY>
   5 <H1>IPSEC_ATOSA</H1>
   6 Section: C Library Functions (3)<BR>Updated: 11 June 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">&nbsp;</A>
  11 <H2>NAME</H2>
  12
  13 ipsec atosa, satoa - convert IPSEC Security Association IDs to and from ASCII
  14 <A NAME="lbAC">&nbsp;</A>
  15 <H2>SYNOPSIS</H2>
  16
  17 <B>#include &lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
  18
  19 <P>
  20 <B>const char *atosa(const char *src, size_t srclen,</B>
  21
  22 <BR>
  23 &nbsp;
  24 <B>struct sa_id *sa);</B>
  25
  26 <BR>
  27
  28 <B>size_t satoa(struct sa_id sa, int format,</B>
  29
  30 <BR>
  31 &nbsp;
  32 <B>char *dst, size_t dstlen);</B>
  33
  34 <P>
  35 <B>struct sa_id {</B>
  36
  37 <BR>
  38 &nbsp;
  39 <B>struct in_addr dst;</B>
  40
  41 <BR>
  42 &nbsp;
  43 <B>ipsec_spi_t spi;</B>
  44
  45 <BR>
  46 &nbsp;
  47 <B>int proto;</B>
  48
  49 <BR>
  50
  51 <B>};</B>
  52
  53 <A NAME="lbAD">&nbsp;</A>
  54 <H2>DESCRIPTION</H2>
  55
  56 These functions are obsolete; see
  57 <I><A HREF="ipsec_ttosa.3.html">ipsec_ttosa</A></I>(3)
  58
  59 for their replacements.
  60 <P>
  61
  62 <I>Atosa</I>
  63
  64 converts an ASCII Security Association (SA) specifier into an
  65 <B>sa_id</B>
  66
  67 structure (containing
  68 a destination-host address
  69 in network byte order,
  70 an SPI number in network byte order, and
  71 a protocol code).
  72 <I>Satoa</I>
  73
  74 does the reverse conversion, back to an ASCII SA specifier.
  75 <P>
  76
  77 An SA is specified in ASCII with a mail-like syntax, e.g.
  78 <B><A HREF="mailto:esp507@1.2.3.4">esp507@1.2.3.4</A></B>.
  79
  80 An SA specifier contains
  81 a protocol prefix (currently
  82 <B>ah</B>,
  83
  84 <B>esp</B>,
  85
  86 or
  87 <B>tun</B>),
  88
  89 an unsigned integer SPI number,
  90 and an IP address.
  91 The SPI number can be decimal or hexadecimal
  92 (with
  93 <B>0x</B>
  94
  95 prefix), as accepted by
  96 <I><A HREF="ipsec_atoul.3.html">ipsec_atoul</A></I>(3).
  97
  98 The IP address can be any form accepted by
  99 <I><A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A></I>(3),
 100
 101 e.g. dotted-decimal address or DNS name.
 102 <P>
 103
 104 As a special case, the SA specifier
 105 <B>%passthrough</B>
 106
 107 signifies the special SA used to indicate that packets should be
 108 passed through unaltered.
 109 (At present, this is a synonym for
 110 <B><A HREF="mailto:tun0x0@0.0.0.0">tun0x0@0.0.0.0</A></B>,
 111
 112 but that is subject to change without notice.)
 113 This form is known to both
 114 <I>atosa</I>
 115
 116 and
 117 <I>satoa</I>,
 118
 119 so the internal form of
 120 <B>%passthrough</B>
 121
 122 is never visible.
 123 <P>
 124
 125 The
 126 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 127
 128 header file supplies the
 129 <B>sa_id</B>
 130
 131 structure, as well as a data type
 132 <B>ipsec_spi_t</B>
 133
 134 which is an unsigned 32-bit integer.
 135 (There is no consistency between kernel and user on what such a type
 136 is called, hence the header hides the differences.)
 137 <P>
 138
 139 The protocol code uses the same numbers that IP does.
 140 For user convenience, given the difficulty in acquiring the exact set of
 141 protocol names used by the kernel,
 142 <B>&lt;<A HREF="file:/usr/include/freeswan.h">freeswan.h</A>&gt;</B>
 143
 144 defines the names
 145 <B>SA_ESP</B>,
 146
 147 <B>SA_AH</B>,
 148
 149 and
 150 <B>SA_IPIP</B>
 151
 152 to have the same values as the kernel names
 153 <B>IPPROTO_ESP</B>,
 154
 155 <B>IPPROTO_AH</B>,
 156
 157 and
 158 <B>IPPROTO_IPIP</B>.
 159
 160 <P>
 161
 162 The
 163 <I>srclen</I>
 164
 165 parameter of
 166 <I>atosa</I>
 167
 168 specifies the length of the ASCII string pointed to by
 169 <I>src</I>;
 170
 171 it is an error for there to be anything else
 172 (e.g., a terminating NUL) within that length.
 173 As a convenience for cases where an entire NUL-terminated string is
 174 to be converted,
 175 a
 176 <I>srclen</I>
 177
 178 value of
 179 <B>0</B>
 180
 181 is taken to mean
 182 <B>strlen(src)</B>.
 183
 184 <P>
 185
 186 The
 187 <I>dstlen</I>
 188
 189 parameter of
 190 <I>satoa</I>
 191
 192 specifies the size of the
 193 <I>dst</I>
 194
 195 parameter;
 196 under no circumstances are more than
 197 <I>dstlen</I>
 198
 199 bytes written to
 200 <I>dst</I>.
 201
 202 A result which will not fit is truncated.
 203 <I>Dstlen</I>
 204
 205 can be zero, in which case
 206 <I>dst</I>
 207
 208 need not be valid and no result is written,
 209 but the return value is unaffected;
 210 in all other cases, the (possibly truncated) result is NUL-terminated.
 211 The
 212 <I>freeswan.h</I>
 213
 214 header file defines a constant,
 215 <B>SATOA_BUF</B>,
 216
 217 which is the size of a buffer just large enough for worst-case results.
 218 <P>
 219
 220 The
 221 <I>format</I>
 222
 223 parameter of
 224 <I>satoa</I>
 225
 226 specifies what format is to be used for the conversion.
 227 The value
 228 <B>0</B>
 229
 230 (not the ASCII character
 231 <B>'0'</B>,
 232
 233 but a zero value)
 234 specifies a reasonable default
 235 (currently
 236 lowercase protocol prefix, lowercase hexadecimal SPI, dotted-decimal address).
 237 The value
 238 <B>d</B>
 239
 240 causes the SPI to be generated in decimal instead.
 241 <P>
 242
 243 <I>Atosa</I>
 244
 245 returns
 246 <B>NULL</B>
 247
 248 for success and
 249 a pointer to a string-literal error message for failure;
 250 see DIAGNOSTICS.
 251 <I>Satoa</I>
 252
 253 returns
 254 <B>0</B>
 255
 256 for a failure, and otherwise
 257 always returns the size of buffer which would
 258 be needed to
 259 accommodate the full conversion result, including terminating NUL;
 260 it is the caller's responsibility to check this against the size of
 261 the provided buffer to determine whether truncation has occurred.
 262 <A NAME="lbAE">&nbsp;</A>
 263 <H2>SEE ALSO</H2>
 264
 265 <A HREF="ipsec_atoul.3.html">ipsec_atoul</A>(3), <A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A>(3), <A HREF="inet.3.html">inet</A>(3)
 266 <A NAME="lbAF">&nbsp;</A>
 267 <H2>DIAGNOSTICS</H2>
 268
 269 Fatal errors in
 270 <I>atosa</I>
 271
 272 are:
 273 empty input;
 274 input too small to be a legal SA specifier;
 275 no
 276 <B>@</B>
 277
 278 in input;
 279 unknown protocol prefix;
 280 conversion error in
 281 <I>atoul</I>
 282
 283 or
 284 <I>atoaddr</I>.
 285
 286 <P>
 287
 288 Fatal errors in
 289 <I>satoa</I>
 290
 291 are:
 292 unknown format; unknown protocol code.
 293 <A NAME="lbAG">&nbsp;</A>
 294 <H2>HISTORY</H2>
 295
 296 Written for the FreeS/WAN project by Henry Spencer.
 297 <A NAME="lbAH">&nbsp;</A>
 298 <H2>BUGS</H2>
 299
 300 The
 301 <B>tun</B>
 302
 303 protocol code is a FreeS/WANism which may eventually disappear.
 304 <P>
 305
 306 The restriction of ASCII-to-binary error reports to literal strings
 307 (so that callers don't need to worry about freeing them or copying them)
 308 does limit the precision of error reporting.
 309 <P>
 310
 311 The ASCII-to-binary error-reporting convention lends itself
 312 to slightly obscure code,
 313 because many readers will not think of NULL as signifying success.
 314 A good way to make it clearer is to write something like:
 315 <P>
 316
 317 <DL COMPACT><DT><DD>
 318 <PRE>
 319 <B>const char *error;</B>
 320
 321 <B>error = atoaddr( /* ... */ );</B>
 322 <B>if (error != NULL) {</B>
 323 <B>        /* something went wrong */</B>
 324 </PRE>
 325
 326 </DL>
 327
 328 <P>
 329
 330 <HR>
 331 <A NAME="index">&nbsp;</A><H2>Index</H2>
 332 <DL>
 333 <DT><A HREF="#lbAB">NAME</A><DD>
 334 <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
 335 <DT><A HREF="#lbAD">DESCRIPTION</A><DD>
 336 <DT><A HREF="#lbAE">SEE ALSO</A><DD>
 337 <DT><A HREF="#lbAF">DIAGNOSTICS</A><DD>
 338 <DT><A HREF="#lbAG">HISTORY</A><DD>
 339 <DT><A HREF="#lbAH">BUGS</A><DD>
 340 </DL>
 341 <HR>
 342 This document was created by
 343 <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>,
 344 using the manual pages.<BR>
 345 Time: 05:09:32 GMT, June 19, 2001
 346 </BODY>
 347 </HTML>