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.