crypto/heimdal-0.6.3/lib/krb5/krb5_address.3

   1 .\" Copyright (c) 2003 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,v 1.4 2003/04/16 13:58:12 lha Exp $
  33 .\"
  34 .Dd March 11, 2002
  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 .Fa Sa_size
 217 should be initially contain the size of the
 218 .Fa sa ,
 219 and after the call, it will contain the actual length of the address.
 220 .Pp
 221 .Fn krb5_max_sockaddr_size
 222 returns the max size of the
 223 .Li struct sockaddr
 224 that the Kerberos library will return.
 225 .Pp
 226 .Fn krb5_sockaddr_uninteresting
 227 returns
 228 .Dv TRUE
 229 for all
 230 .Fa sa
 231 that for that the kerberos library thinks are uninteresting.
 232 One example are link local addresses.
 233 .Pp
 234 .Fn krb5_h_addr2sockaddr
 235 initializes a
 236 .Li "struct sockaddr"
 237 .Fa sa
 238 from
 239 .Fa af
 240 and the
 241 .Li "struct hostent"
 242 (see
 243 .Xr gethostbyname 3 )
 244 .Fa h_addr_list
 245 component.
 246 .Fa Sa_size
 247 should be initially contain the size of the
 248 .Fa sa ,
 249 and after the call, it will contain the actual length of the address.
 250 .Fa sa
 251 argument.
 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 .Xf bind 3
 267 to.
 268 .Fa Sa_size
 269 should be initially contain the size of the
 270 .Fa sa ,
 271 and after the call, it will contain the actual length of the address.
 272 .Pp
 273 .Fn krb5_print_address
 274 prints the address in
 275 .Fa addr
 276 to the a string
 277 .Fa string
 278 that have the length
 279 .Fa len .
 280 If
 281 .Fa ret_len
 282 if not
 283 .Dv NULL ,
 284 it will be filled in length of the string.
 285 .Pp
 286 .Fn krb5_parse_address
 287 Returns the resolving a hostname in
 288 .Fa string
 289 to the
 290 .Li krb5_addresses
 291 .Fa addresses .
 292 .Pp
 293 .Fn krb5_address_order
 294 compares to addresses
 295 .Fa addr1
 296 and
 297 .Fa addr2
 298 so that it can be used for sorting addresses. If the addresses are the
 299 same address
 300 .Fa krb5_address_order will be return 0.
 301 .Pp
 302 .Fn krb5_address_compare
 303 compares the addresses
 304 .Fa addr1
 305 and
 306 .Fa addr2 .
 307 returns
 308 .Dv TRUE
 309 if the two addresses are the same.
 310 .Pp
 311 .Fn krb5_address_search
 312 checks if the address
 313 .Fa addr
 314 is a member of the address set list
 315 .Fa addrlist .
 316 .Pp
 317 .Fn krb5_free_address
 318 frees the data stored in the
 319 .Fa address
 320 that is alloced with any of the krb5_address functions.
 321 .Pp
 322 .Fn krb5_free_addresses
 323 frees the data stored in the
 324 .Fa addresses
 325 that is alloced with any of the krb5_address functions.
 326 .Pp
 327 .Fn krb5_copy_address
 328 copies the content of address
 329 .Fa inaddr
 330 to
 331 .Fa outaddr .
 332 .Pp
 333 .Fn krb5_copy_addresses
 334 copies the content of the address list
 335 .Fa inaddr
 336 to
 337 .Fa outaddr .
 338 .Pp
 339 .Fn krb5_append_addresses
 340 adds the set of addresses in
 341 .Fa source
 342 to
 343 .Fa dest .
 344 While copying the addresses, duplicates are also sorted out.
 345 .Pp
 346 .Fn krb5_make_addrport
 347 allocates and creates an
 348 krb5_address in
 349 .Fa res
 350 of type KRB5_ADDRESS_ADDRPORT from
 351 .Fa ( addr , port ) .
 352 .Sh SEE ALSO
 353 .Xr krb5 3 ,
 354 .Xr krb5.conf 5 ,
 355 .Xr kerberos 8