crypto/heimdal/lib/krb5/krb5_address.3

   1 .\" Copyright (c) 2003, 2005 - 2006 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id: krb5_address.3 17461 2006-05-05 13:13:18Z lha $
  33 .\"
  34 .Dd May  1, 2006
  35 .Dt KRB5_ADDRESS 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_address ,
  39 .Nm krb5_addresses ,
  40 .Nm krb5_sockaddr2address ,
  41 .Nm krb5_sockaddr2port ,
  42 .Nm krb5_addr2sockaddr ,
  43 .Nm krb5_max_sockaddr_size ,
  44 .Nm krb5_sockaddr_uninteresting ,
  45 .Nm krb5_h_addr2sockaddr ,
  46 .Nm krb5_h_addr2addr ,
  47 .Nm krb5_anyaddr ,
  48 .Nm krb5_print_address ,
  49 .Nm krb5_parse_address ,
  50 .Nm krb5_address_order ,
  51 .Nm krb5_address_compare ,
  52 .Nm krb5_address_search ,
  53 .Nm krb5_free_address ,
  54 .Nm krb5_free_addresses ,
  55 .Nm krb5_copy_address ,
  56 .Nm krb5_copy_addresses ,
  57 .Nm krb5_append_addresses ,
  58 .Nm krb5_make_addrport
  59 .Nd mange addresses in Kerberos
  60 .Sh LIBRARY
  61 Kerberos 5 Library (libkrb5, -lkrb5)
  62 .Sh SYNOPSIS
  63 .In krb5.h
  64 .Pp
  65 .Ft krb5_error_code
  66 .Fo krb5_sockaddr2address
  67 .Fa "krb5_context context"
  68 .Fa "const struct sockaddr *sa"
  69 .Fa "krb5_address *addr"
  70 .Fc
  71 .Ft krb5_error_code
  72 .Fo krb5_sockaddr2port
  73 .Fa "krb5_context context"
  74 .Fa "const struct sockaddr *sa"
  75 .Fa "int16_t *port"
  76 .Fc
  77 .Ft krb5_error_code
  78 .Fo krb5_addr2sockaddr
  79 .Fa "krb5_context context"
  80 .Fa "const krb5_address *addr"
  81 .Fa "struct sockaddr *sa"
  82 .Fa "krb5_socklen_t *sa_size"
  83 .Fa "int port"
  84 .Fc
  85 .Ft size_t
  86 .Fo krb5_max_sockaddr_size
  87 .Fa "void"
  88 .Fc
  89 .Ft "krb5_boolean"
  90 .Fo krb5_sockaddr_uninteresting
  91 .Fa "const struct sockaddr *sa"
  92 .Fc
  93 .Ft krb5_error_code
  94 .Fo krb5_h_addr2sockaddr
  95 .Fa "krb5_context context"
  96 .Fa "int af"
  97 .Fa "const char *addr"
  98 .Fa "struct sockaddr *sa"
  99 .Fa "krb5_socklen_t *sa_size"
 100 .Fa "int port"
 101 .Fc
 102 .Ft krb5_error_code
 103 .Fo krb5_h_addr2addr
 104 .Fa "krb5_context context"
 105 .Fa "int af"
 106 .Fa "const char *haddr"
 107 .Fa "krb5_address *addr"
 108 .Fc
 109 .Ft krb5_error_code
 110 .Fo krb5_anyaddr
 111 .Fa "krb5_context context"
 112 .Fa "int af"
 113 .Fa "struct sockaddr *sa"
 114 .Fa "krb5_socklen_t *sa_size"
 115 .Fa "int port"
 116 .Fc
 117 .Ft krb5_error_code
 118 .Fo krb5_print_address
 119 .Fa "const krb5_address *addr"
 120 .Fa "char *str"
 121 .Fa "size_t len"
 122 .Fa "size_t *ret_len"
 123 .Fc
 124 .Ft krb5_error_code
 125 .Fo krb5_parse_address
 126 .Fa "krb5_context context"
 127 .Fa "const char *string"
 128 .Fa "krb5_addresses *addresses"
 129 .Fc
 130 .Ft int
 131 .Fo "krb5_address_order"
 132 .Fa "krb5_context context"
 133 .Fa "const krb5_address *addr1"
 134 .Fa "const krb5_address *addr2"
 135 .Fc
 136 .Ft "krb5_boolean"
 137 .Fo krb5_address_compare
 138 .Fa "krb5_context context"
 139 .Fa "const krb5_address *addr1"
 140 .Fa "const krb5_address *addr2"
 141 .Fc
 142 .Ft "krb5_boolean"
 143 .Fo krb5_address_search
 144 .Fa "krb5_context context"
 145 .Fa "const krb5_address *addr"
 146 .Fa "const krb5_addresses *addrlist"
 147 .Fc
 148 .Ft krb5_error_code
 149 .Fo krb5_free_address
 150 .Fa "krb5_context context"
 151 .Fa "krb5_address *address"
 152 .Fc
 153 .Ft krb5_error_code
 154 .Fo krb5_free_addresses
 155 .Fa "krb5_context context"
 156 .Fa "krb5_addresses *addresses"
 157 .Fc
 158 .Ft krb5_error_code
 159 .Fo krb5_copy_address
 160 .Fa "krb5_context context"
 161 .Fa "const krb5_address *inaddr"
 162 .Fa "krb5_address *outaddr"
 163 .Fc
 164 .Ft krb5_error_code
 165 .Fo krb5_copy_addresses
 166 .Fa "krb5_context context"
 167 .Fa "const krb5_addresses *inaddr"
 168 .Fa "krb5_addresses *outaddr"
 169 .Fc
 170 .Ft krb5_error_code
 171 .Fo krb5_append_addresses
 172 .Fa "krb5_context context"
 173 .Fa "krb5_addresses *dest"
 174 .Fa "const krb5_addresses *source"
 175 .Fc
 176 .Ft krb5_error_code
 177 .Fo krb5_make_addrport
 178 .Fa "krb5_context context"
 179 .Fa "krb5_address **res"
 180 .Fa "const krb5_address *addr"
 181 .Fa "int16_t port"
 182 .Fc
 183 .Sh DESCRIPTION
 184 The
 185 .Li krb5_address
 186 structure holds a address that can be used in Kerberos API
 187 calls. There are help functions to set and extract address information
 188 of the address.
 189 .Pp
 190 The
 191 .Li krb5_addresses
 192 structure holds a set of krb5_address:es.
 193 .Pp
 194 .Fn krb5_sockaddr2address
 195 stores a address a
 196 .Li "struct sockaddr"
 197 .Fa sa
 198 in the krb5_address
 199 .Fa addr .
 200 .Pp
 201 .Fn krb5_sockaddr2port
 202 extracts a
 203 .Fa port
 204 (if possible) from a
 205 .Li "struct sockaddr"
 206 .Fa sa .
 207 .Pp
 208 .Fn krb5_addr2sockaddr
 209 sets the
 210 struct sockaddr
 211 .Fa sockaddr
 212 from
 213 .Fa addr
 214 and
 215 .Fa port .
 216 The argument
 217 .Fa sa_size
 218 should initially contain the size of the
 219 .Fa sa ,
 220 and after the call, it will contain the actual length of the address.
 221 .Pp
 222 .Fn krb5_max_sockaddr_size
 223 returns the max size of the
 224 .Li struct sockaddr
 225 that the Kerberos library will return.
 226 .Pp
 227 .Fn krb5_sockaddr_uninteresting
 228 returns
 229 .Dv TRUE
 230 for all
 231 .Fa sa
 232 that the kerberos library thinks are uninteresting.
 233 One example are link local addresses.
 234 .Pp
 235 .Fn krb5_h_addr2sockaddr
 236 initializes a
 237 .Li "struct sockaddr"
 238 .Fa sa
 239 from
 240 .Fa af
 241 and the
 242 .Li "struct hostent"
 243 (see
 244 .Xr gethostbyname 3 )
 245 .Fa h_addr_list
 246 component.
 247 The argument
 248 .Fa sa_size
 249 should initially contain the size of the
 250 .Fa sa ,
 251 and after the call, it will contain the actual length of the address.
 252 .Pp
 253 .Fn krb5_h_addr2addr
 254 works like
 255 .Fn krb5_h_addr2sockaddr
 256 with the exception that it operates on a
 257 .Li krb5_address
 258 instead of a
 259 .Li struct sockaddr .
 260 .Pp
 261 .Fn krb5_anyaddr
 262 fills in a
 263 .Li "struct sockaddr"
 264 .Fa sa
 265 that can be used to
 266 .Xr bind 2
 267 to.
 268 The argument
 269 .Fa sa_size
 270 should initially contain the size of the
 271 .Fa sa ,
 272 and after the call, it will contain the actual length of the address.
 273 .Pp
 274 .Fn krb5_print_address
 275 prints the address in
 276 .Fa addr
 277 to the string
 278 .Fa string
 279 that have the length
 280 .Fa len .
 281 If
 282 .Fa ret_len
 283 is not
 284 .Dv NULL ,
 285 it will be filled with the length of the string if size were unlimited (not
 286 including the final
 287 .Ql \e0 ) .
 288 .Pp
 289 .Fn krb5_parse_address
 290 Returns the resolved hostname in
 291 .Fa string
 292 to the
 293 .Li krb5_addresses
 294 .Fa addresses .
 295 .Pp
 296 .Fn krb5_address_order
 297 compares the addresses
 298 .Fa addr1
 299 and
 300 .Fa addr2
 301 so that it can be used for sorting addresses. If the addresses are the
 302 same address
 303 .Fa krb5_address_order
 304 will return 0.
 305 .Pp
 306 .Fn krb5_address_compare
 307 compares the addresses
 308 .Fa addr1
 309 and
 310 .Fa addr2 .
 311 Returns
 312 .Dv TRUE
 313 if the two addresses are the same.
 314 .Pp
 315 .Fn krb5_address_search
 316 checks if the address
 317 .Fa addr
 318 is a member of the address set list
 319 .Fa addrlist .
 320 .Pp
 321 .Fn krb5_free_address
 322 frees the data stored in the
 323 .Fa address
 324 that is alloced with any of the krb5_address functions.
 325 .Pp
 326 .Fn krb5_free_addresses
 327 frees the data stored in the
 328 .Fa addresses
 329 that is alloced with any of the krb5_address functions.
 330 .Pp
 331 .Fn krb5_copy_address
 332 copies the content of address
 333 .Fa inaddr
 334 to
 335 .Fa outaddr .
 336 .Pp
 337 .Fn krb5_copy_addresses
 338 copies the content of the address list
 339 .Fa inaddr
 340 to
 341 .Fa outaddr .
 342 .Pp
 343 .Fn krb5_append_addresses
 344 adds the set of addresses in
 345 .Fa source
 346 to
 347 .Fa dest .
 348 While copying the addresses, duplicates are also sorted out.
 349 .Pp
 350 .Fn krb5_make_addrport
 351 allocates and creates an
 352 krb5_address in
 353 .Fa res
 354 of type KRB5_ADDRESS_ADDRPORT from
 355 .Fa ( addr , port ) .
 356 .Sh SEE ALSO
 357 .Xr krb5 3 ,
 358 .Xr krb5.conf 5 ,
 359 .Xr kerberos 8