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