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
48Kerberos 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
68These functions are used to sequence through all Kerberos hosts of a
69particular realm and service. The service type can be the KDCs, the
70administrative servers, the password changing servers, or the servers
71for Kerberos 4 ticket conversion.
72.Pp
73First a handle to a particular service is obtained by calling
74.Fn krb5_krbhst_init
75(or
76.Fn krb5_krbhst_init_flags )
77with the
78.Fa realm
79of interest and the type of service to lookup. The
80.Fa type
81can 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
90The
91.Fa handle
92is returned to the caller, and should be passed to the other
93functions.
94.Pp
95The
96.Fa flag
97argument to
98.Nm krb5_krbhst_init_flags
99is the same flags as
100.Fn krb5_send_to_kdc_flags
101uses.
102Possible values are:
103.Pp
104.Bl -tag -width KRB5_KRBHST_FLAGS_LARGE_MSG -compact -offset indent
105.It KRB5_KRBHST_FLAGS_MASTER
106only talk to master (readwrite) KDC
107.It KRB5_KRBHST_FLAGS_LARGE_MSG
108this is a large message, so use transport that can handle that.
109.El
110.Pp
111For each call to
112.Fn krb5_krbhst_next
113information on a new host is returned. The former function returns in
114.Fa host
115a pointer to a structure containing information about the host, such
116as protocol, hostname, and port:
117.Bd -literal -offset indent
118typedef 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
129The related function,
130.Fn krb5_krbhst_next_as_string ,
131return the same information as a URL-like string.
132.Pp
133When there are no more hosts, these functions return
134.Dv KRB5_KDC_UNREACH .
135.Pp
136To re-iterate over all hosts, call
137.Fn krb5_krbhst_reset
138and the next call to
139.Fn krb5_krbhst_next
140will return the first host.
141.Pp
142When done with the handle,
143.Fn krb5_krbhst_free
144should be called.
145.Pp
146To use a
147.Va krb5_krbhst_info ,
148there are two functions:
149.Fn krb5_krbhst_format_string
150that will return a printable representation of that struct
151and
152.Fn krb5_krbhst_get_addrinfo
153that will return a
154.Va struct addrinfo
155that can then be used for communicating with the server mentioned.
156.Sh EXAMPLES
157The following code will print the KDCs of the realm
158.Dq MY.REALM :
159.Bd -literal -offset indent
160krb5_krbhst_handle handle;
161char host[MAXHOSTNAMELEN];
162krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
163while(krb5_krbhst_next_as_string(context, handle,
164				 host, sizeof(host)) == 0)
165    printf("%s\\n", host);
166krb5_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
174These functions first appeared in Heimdal 0.3g.
175