crypto/dist/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 .\" $Heimdal: krb5_address.3 17461 2006-05-05 13:13:18Z lha $
  33 .\" $NetBSD$
  34 .\"
  35 .Dd May  1, 2006
  36 .Dt KRB5_ADDRESS 3
  37 .Os
  38 .Sh NAME
  39 .Nm krb5_address ,
  40 .Nm krb5_addresses ,
  41 .Nm krb5_sockaddr2address ,
  42 .Nm krb5_sockaddr2port ,
  43 .Nm krb5_addr2sockaddr ,
  44 .Nm krb5_max_sockaddr_size ,
  45 .Nm krb5_sockaddr_uninteresting ,
  46 .Nm krb5_h_addr2sockaddr ,
  47 .Nm krb5_h_addr2addr ,
  48 .Nm krb5_anyaddr ,
  49 .Nm krb5_print_address ,
  50 .Nm krb5_parse_address ,
  51 .Nm krb5_address_order ,
  52 .Nm krb5_address_compare ,
  53 .Nm krb5_address_search ,
  54 .Nm krb5_free_address ,
  55 .Nm krb5_free_addresses ,
  56 .Nm krb5_copy_address ,
  57 .Nm krb5_copy_addresses ,
  58 .Nm krb5_append_addresses ,
  59 .Nm krb5_make_addrport
  60 .Nd mange addresses in Kerberos
  61 .Sh LIBRARY
  62 Kerberos 5 Library (libkrb5, -lkrb5)
  63 .Sh SYNOPSIS
  64 .In krb5/krb5.h
  65 .Pp
  66 .Ft krb5_error_code
  67 .Fo krb5_sockaddr2address
  68 .Fa "krb5_context context"
  69 .Fa "const struct sockaddr *sa"
  70 .Fa "krb5_address *addr"
  71 .Fc
  72 .Ft krb5_error_code
  73 .Fo krb5_sockaddr2port
  74 .Fa "krb5_context context"
  75 .Fa "const struct sockaddr *sa"
  76 .Fa "int16_t *port"
  77 .Fc
  78 .Ft krb5_error_code
  79 .Fo krb5_addr2sockaddr
  80 .Fa "krb5_context context"
  81 .Fa "const krb5_address *addr"
  82 .Fa "struct sockaddr *sa"
  83 .Fa "krb5_socklen_t *sa_size"
  84 .Fa "int port"
  85 .Fc
  86 .Ft size_t
  87 .Fo krb5_max_sockaddr_size
  88 .Fa "void"
  89 .Fc
  90 .Ft "krb5_boolean"
  91 .Fo krb5_sockaddr_uninteresting
  92 .Fa "const struct sockaddr *sa"
  93 .Fc
  94 .Ft krb5_error_code
  95 .Fo krb5_h_addr2sockaddr
  96 .Fa "krb5_context context"
  97 .Fa "int af"
  98 .Fa "const char *addr"
  99 .Fa "struct sockaddr *sa"
 100 .Fa "krb5_socklen_t *sa_size"
 101 .Fa "int port"
 102 .Fc
 103 .Ft krb5_error_code
 104 .Fo krb5_h_addr2addr
 105 .Fa "krb5_context context"
 106 .Fa "int af"
 107 .Fa "const char *haddr"
 108 .Fa "krb5_address *addr"
 109 .Fc
 110 .Ft krb5_error_code
 111 .Fo krb5_anyaddr
 112 .Fa "krb5_context context"
 113 .Fa "int af"
 114 .Fa "struct sockaddr *sa"
 115 .Fa "krb5_socklen_t *sa_size"
 116 .Fa "int port"
 117 .Fc
 118 .Ft krb5_error_code
 119 .Fo krb5_print_address
 120 .Fa "const krb5_address *addr"
 121 .Fa "char *str"
 122 .Fa "size_t len"
 123 .Fa "size_t *ret_len"
 124 .Fc
 125 .Ft krb5_error_code
 126 .Fo krb5_parse_address
 127 .Fa "krb5_context context"
 128 .Fa "const char *string"
 129 .Fa "krb5_addresses *addresses"
 130 .Fc
 131 .Ft int
 132 .Fo "krb5_address_order"
 133 .Fa "krb5_context context"
 134 .Fa "const krb5_address *addr1"
 135 .Fa "const krb5_address *addr2"
 136 .Fc
 137 .Ft "krb5_boolean"
 138 .Fo krb5_address_compare
 139 .Fa "krb5_context context"
 140 .Fa "const krb5_address *addr1"
 141 .Fa "const krb5_address *addr2"
 142 .Fc
 143 .Ft "krb5_boolean"
 144 .Fo krb5_address_search
 145 .Fa "krb5_context context"
 146 .Fa "const krb5_address *addr"
 147 .Fa "const krb5_addresses *addrlist"
 148 .Fc
 149 .Ft krb5_error_code
 150 .Fo krb5_free_address
 151 .Fa "krb5_context context"
 152 .Fa "krb5_address *address"
 153 .Fc
 154 .Ft krb5_error_code
 155 .Fo krb5_free_addresses
 156 .Fa "krb5_context context"
 157 .Fa "krb5_addresses *addresses"
 158 .Fc
 159 .Ft krb5_error_code
 160 .Fo krb5_copy_address
 161 .Fa "krb5_context context"
 162 .Fa "const krb5_address *inaddr"
 163 .Fa "krb5_address *outaddr"
 164 .Fc
 165 .Ft krb5_error_code
 166 .Fo krb5_copy_addresses
 167 .Fa "krb5_context context"
 168 .Fa "const krb5_addresses *inaddr"
 169 .Fa "krb5_addresses *outaddr"
 170 .Fc
 171 .Ft krb5_error_code
 172 .Fo krb5_append_addresses
 173 .Fa "krb5_context context"
 174 .Fa "krb5_addresses *dest"
 175 .Fa "const krb5_addresses *source"
 176 .Fc
 177 .Ft krb5_error_code
 178 .Fo krb5_make_addrport
 179 .Fa "krb5_context context"
 180 .Fa "krb5_address **res"
 181 .Fa "const krb5_address *addr"
 182 .Fa "int16_t port"
 183 .Fc
 184 .Sh DESCRIPTION
 185 The
 186 .Li krb5_address
 187 structure holds a address that can be used in Kerberos API
 188 calls. There are help functions to set and extract address information
 189 of the address.
 190 .Pp
 191 The
 192 .Li krb5_addresses
 193 structure holds a set of krb5_address:es.
 194 .Pp
 195 .Fn krb5_sockaddr2address
 196 stores a address a
 197 .Li "struct sockaddr"
 198 .Fa sa
 199 in the krb5_address
 200 .Fa addr .
 201 .Pp
 202 .Fn krb5_sockaddr2port
 203 extracts a
 204 .Fa port
 205 (if possible) from a
 206 .Li "struct sockaddr"
 207 .Fa sa .
 208 .Pp
 209 .Fn krb5_addr2sockaddr
 210 sets the
 211 struct sockaddr
 212 .Fa sockaddr
 213 from
 214 .Fa addr
 215 and
 216 .Fa port .
 217 The argument
 218 .Fa sa_size
 219 should initially contain the size of the
 220 .Fa sa ,
 221 and after the call, it will contain the actual length of the address.
 222 .Pp
 223 .Fn krb5_max_sockaddr_size
 224 returns the max size of the
 225 .Li struct sockaddr
 226 that the Kerberos library will return.
 227 .Pp
 228 .Fn krb5_sockaddr_uninteresting
 229 returns
 230 .Dv TRUE
 231 for all
 232 .Fa sa
 233 that the kerberos library thinks are uninteresting.
 234 One example are link local addresses.
 235 .Pp
 236 .Fn krb5_h_addr2sockaddr
 237 initializes a
 238 .Li "struct sockaddr"
 239 .Fa sa
 240 from
 241 .Fa af
 242 and the
 243 .Li "struct hostent"
 244 (see
 245 .Xr gethostbyname 3 )
 246 .Fa h_addr_list
 247 component.
 248 The argument
 249 .Fa sa_size
 250 should initially contain the size of the
 251 .Fa sa ,
 252 and after the call, it will contain the actual length of the address.
 253 .Pp
 254 .Fn krb5_h_addr2addr
 255 works like
 256 .Fn krb5_h_addr2sockaddr
 257 with the exception that it operates on a
 258 .Li krb5_address
 259 instead of a
 260 .Li struct sockaddr .
 261 .Pp
 262 .Fn krb5_anyaddr
 263 fills in a
 264 .Li "struct sockaddr"
 265 .Fa sa
 266 that can be used to
 267 .Xr bind 2
 268 to.
 269 The argument
 270 .Fa sa_size
 271 should initially contain the size of the
 272 .Fa sa ,
 273 and after the call, it will contain the actual length of the address.
 274 .Pp
 275 .Fn krb5_print_address
 276 prints the address in
 277 .Fa addr
 278 to the string
 279 .Fa string
 280 that have the length
 281 .Fa len .
 282 If
 283 .Fa ret_len
 284 is not
 285 .Dv NULL ,
 286 it will be filled with the length of the string if size were unlimited (not
 287 including the final
 288 .Ql \e0 ) .
 289 .Pp
 290 .Fn krb5_parse_address
 291 Returns the resolved hostname in
 292 .Fa string
 293 to the
 294 .Li krb5_addresses
 295 .Fa addresses .
 296 .Pp
 297 .Fn krb5_address_order
 298 compares the addresses
 299 .Fa addr1
 300 and
 301 .Fa addr2
 302 so that it can be used for sorting addresses. If the addresses are the
 303 same address
 304 .Fa krb5_address_order
 305 will return 0.
 306 .Pp
 307 .Fn krb5_address_compare
 308 compares the addresses
 309 .Fa addr1
 310 and
 311 .Fa addr2 .
 312 Returns
 313 .Dv TRUE
 314 if the two addresses are the same.
 315 .Pp
 316 .Fn krb5_address_search
 317 checks if the address
 318 .Fa addr
 319 is a member of the address set list
 320 .Fa addrlist .
 321 .Pp
 322 .Fn krb5_free_address
 323 frees the data stored in the
 324 .Fa address
 325 that is alloced with any of the krb5_address functions.
 326 .Pp
 327 .Fn krb5_free_addresses
 328 frees the data stored in the
 329 .Fa addresses
 330 that is alloced with any of the krb5_address functions.
 331 .Pp
 332 .Fn krb5_copy_address
 333 copies the content of address
 334 .Fa inaddr
 335 to
 336 .Fa outaddr .
 337 .Pp
 338 .Fn krb5_copy_addresses
 339 copies the content of the address list
 340 .Fa inaddr
 341 to
 342 .Fa outaddr .
 343 .Pp
 344 .Fn krb5_append_addresses
 345 adds the set of addresses in
 346 .Fa source
 347 to
 348 .Fa dest .
 349 While copying the addresses, duplicates are also sorted out.
 350 .Pp
 351 .Fn krb5_make_addrport
 352 allocates and creates an
 353 krb5_address in
 354 .Fa res
 355 of type KRB5_ADDRESS_ADDRPORT from
 356 .Fa ( addr , port ) .
 357 .Sh SEE ALSO
 358 .Xr krb5 3 ,
 359 .Xr krb5.conf 5 ,
 360 .Xr kerberos 8