crypto/heimdal/lib/krb5/krb5_krbhst_init.3

   1 .\" Copyright (c) 2001-2005 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$
  33 .\"
  34 .Dd May 10, 2005
  35 .Dt KRB5_KRBHST_INIT 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_krbhst_init ,
  39 .Nm krb5_krbhst_init_flags ,
  40 .Nm krb5_krbhst_next ,
  41 .Nm krb5_krbhst_next_as_string ,
  42 .Nm krb5_krbhst_reset ,
  43 .Nm krb5_krbhst_free ,
  44 .Nm krb5_krbhst_format_string ,
  45 .Nm krb5_krbhst_get_addrinfo
  46 .Nd lookup Kerberos KDC hosts
  47 .Sh LIBRARY
  48 Kerberos 5 Library (libkrb5, -lkrb5)
  49 .Sh SYNOPSIS
  50 .In krb5.h
  51 .Ft krb5_error_code
  52 .Fn krb5_krbhst_init "krb5_context context" "const char *realm" "unsigned int type" "krb5_krbhst_handle *handle"
  53 .Ft krb5_error_code
  54 .Fn krb5_krbhst_init_flags "krb5_context context" "const char *realm" "unsigned int type" "int flags" "krb5_krbhst_handle *handle"
  55 .Ft krb5_error_code
  56 .Fn "krb5_krbhst_next" "krb5_context context" "krb5_krbhst_handle handle" "krb5_krbhst_info **host"
  57 .Ft krb5_error_code
  58 .Fn krb5_krbhst_next_as_string "krb5_context context" "krb5_krbhst_handle handle" "char *hostname" "size_t hostlen"
  59 .Ft void
  60 .Fn krb5_krbhst_reset "krb5_context context" "krb5_krbhst_handle handle"
  61 .Ft void
  62 .Fn krb5_krbhst_free "krb5_context context" "krb5_krbhst_handle handle"
  63 .Ft krb5_error_code
  64 .Fn krb5_krbhst_format_string "krb5_context context" "const krb5_krbhst_info *host" "char *hostname" "size_t hostlen"
  65 .Ft krb5_error_code
  66 .Fn krb5_krbhst_get_addrinfo "krb5_context context" "krb5_krbhst_info *host" "struct addrinfo **ai"
  67 .Sh DESCRIPTION
  68 These functions are used to sequence through all Kerberos hosts of a
  69 particular realm and service. The service type can be the KDCs, the
  70 administrative servers, the password changing servers, or the servers
  71 for Kerberos 4 ticket conversion.
  72 .Pp
  73 First a handle to a particular service is obtained by calling
  74 .Fn krb5_krbhst_init
  75 (or
  76 .Fn krb5_krbhst_init_flags )
  77 with the
  78 .Fa realm
  79 of interest and the type of service to lookup. The
  80 .Fa type
  81 can be one of:
  82 .Pp
  83 .Bl -tag -width Ds -compact -offset indent
  84 .It KRB5_KRBHST_KDC
  85 .It KRB5_KRBHST_ADMIN
  86 .It KRB5_KRBHST_CHANGEPW
  87 .It KRB5_KRBHST_KRB524
  88 .El
  89 .Pp
  90 The
  91 .Fa handle
  92 is returned to the caller, and should be passed to the other
  93 functions.
  94 .Pp
  95 The
  96 .Fa flag
  97 argument to
  98 .Nm krb5_krbhst_init_flags
  99 is the same flags as
 100 .Fn krb5_send_to_kdc_flags
 101 uses.
 102 Possible values are:
 103 .Pp
 104 .Bl -tag -width KRB5_KRBHST_FLAGS_LARGE_MSG -compact -offset indent
 105 .It KRB5_KRBHST_FLAGS_MASTER
 106 only talk to master (readwrite) KDC
 107 .It KRB5_KRBHST_FLAGS_LARGE_MSG
 108 this is a large message, so use transport that can handle that.
 109 .El
 110 .Pp
 111 For each call to
 112 .Fn krb5_krbhst_next
 113 information on a new host is returned. The former function returns in
 114 .Fa host
 115 a pointer to a structure containing information about the host, such
 116 as protocol, hostname, and port:
 117 .Bd -literal -offset indent
 118 typedef struct krb5_krbhst_info {
 119     enum { KRB5_KRBHST_UDP,
 120            KRB5_KRBHST_TCP,
 121            KRB5_KRBHST_HTTP } proto;
 122     unsigned short port;
 123     struct addrinfo *ai;
 124     struct krb5_krbhst_info *next;
 125     char hostname[1];
 126 } krb5_krbhst_info;
 127 .Ed
 128 .Pp
 129 The related function,
 130 .Fn krb5_krbhst_next_as_string ,
 131 return the same information as a URL-like string.
 132 .Pp
 133 When there are no more hosts, these functions return
 134 .Dv KRB5_KDC_UNREACH .
 135 .Pp
 136 To re-iterate over all hosts, call
 137 .Fn krb5_krbhst_reset
 138 and the next call to
 139 .Fn krb5_krbhst_next
 140 will return the first host.
 141 .Pp
 142 When done with the handle,
 143 .Fn krb5_krbhst_free
 144 should be called.
 145 .Pp
 146 To use a
 147 .Va krb5_krbhst_info ,
 148 there are two functions:
 149 .Fn krb5_krbhst_format_string
 150 that will return a printable representation of that struct
 151 and
 152 .Fn krb5_krbhst_get_addrinfo
 153 that will return a
 154 .Va struct addrinfo
 155 that can then be used for communicating with the server mentioned.
 156 .Sh EXAMPLES
 157 The following code will print the KDCs of the realm
 158 .Dq MY.REALM :
 159 .Bd -literal -offset indent
 160 krb5_krbhst_handle handle;
 161 char host[MAXHOSTNAMELEN];
 162 krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
 163 while(krb5_krbhst_next_as_string(context, handle,
 164                                  host, sizeof(host)) == 0)
 165     printf("%s\\n", host);
 166 krb5_krbhst_free(context, handle);
 167 .Ed
 168 .\" .Sh BUGS
 169 .Sh SEE ALSO
 170 .Xr getaddrinfo 3 ,
 171 .Xr krb5_get_krbhst 3 ,
 172 .Xr krb5_send_to_kdc_flags 3
 173 .Sh HISTORY
 174 These functions first appeared in Heimdal 0.3g.