1KRB5_KRBHST_INIT(3)      BSD Library Functions Manual      KRB5_KRBHST_INIT(3)
2

NAME

4     krb5_krbhst_init, krb5_krbhst_init_flags, krb5_krbhst_next,
5     krb5_krbhst_next_as_string, krb5_krbhst_reset, krb5_krbhst_free,
6     krb5_krbhst_format_string, krb5_krbhst_get_addrinfo — lookup Kerberos KDC
7     hosts
8

LIBRARY

10     Kerberos 5 Library (libkrb5, -lkrb5)
11

SYNOPSIS

13     #include <krb5.h>
14
15     krb5_error_code
16     krb5_krbhst_init(krb5_context context, const char *realm,
17         unsigned int type, krb5_krbhst_handle *handle);
18
19     krb5_error_code
20     krb5_krbhst_init_flags(krb5_context context, const char *realm,
21         unsigned int type, int flags, krb5_krbhst_handle *handle);
22
23     krb5_error_code
24     krb5_krbhst_next(krb5_context context, krb5_krbhst_handle handle,
25         krb5_krbhst_info **host);
26
27     krb5_error_code
28     krb5_krbhst_next_as_string(krb5_context context,
29         krb5_krbhst_handle handle, char *hostname, size_t hostlen);
30
31     void
32     krb5_krbhst_reset(krb5_context context, krb5_krbhst_handle handle);
33
34     void
35     krb5_krbhst_free(krb5_context context, krb5_krbhst_handle handle);
36
37     krb5_error_code
38     krb5_krbhst_format_string(krb5_context context,
39         const krb5_krbhst_info *host, char *hostname, size_t hostlen);
40
41     krb5_error_code
42     krb5_krbhst_get_addrinfo(krb5_context context, krb5_krbhst_info *host,
43         struct addrinfo **ai);
44

DESCRIPTION

46     These functions are used to sequence through all Kerberos hosts of a par‐
47     ticular realm and service. The service type can be the KDCs, the adminis‐
48     trative servers, the password changing servers, or the servers for Ker‐
49     beros 4 ticket conversion.
50
51     First a handle to a particular service is obtained by calling
52     krb5_krbhst_init() (or krb5_krbhst_init_flags()) with the realm of inter‐
53     est and the type of service to lookup. The type can be one of:
54
55           KRB5_KRBHST_KDC
56           KRB5_KRBHST_ADMIN
57           KRB5_KRBHST_CHANGEPW
58           KRB5_KRBHST_KRB524
59
60     The handle is returned to the caller, and should be passed to the other
61     functions.
62
63     The flag argument to krb5_krbhst_init_flags is the same flags as
64     krb5_send_to_kdc_flags() uses.  Possible values are:
65
66           KRB5_KRBHST_FLAGS_MASTER     only talk to master (readwrite) KDC
67           KRB5_KRBHST_FLAGS_LARGE_MSG  this is a large message, so use trans‐
68                                        port that can handle that.
69
70     For each call to krb5_krbhst_next() information on a new host is
71     returned. The former function returns in host a pointer to a structure
72     containing information about the host, such as protocol, hostname, and
73     port:
74
75           typedef struct krb5_krbhst_info {
76               enum { KRB5_KRBHST_UDP,
77                      KRB5_KRBHST_TCP,
78                      KRB5_KRBHST_HTTP } proto;
79               unsigned short port;
80               struct addrinfo *ai;
81               struct krb5_krbhst_info *next;
82               char hostname[1];
83           } krb5_krbhst_info;
84
85     The related function, krb5_krbhst_next_as_string(), return the same
86     information as a URL-like string.
87
88     When there are no more hosts, these functions return KRB5_KDC_UNREACH.
89
90     To re-iterate over all hosts, call krb5_krbhst_reset() and the next call
91     to krb5_krbhst_next() will return the first host.
92
93     When done with the handle, krb5_krbhst_free() should be called.
94
95     To use a krb5_krbhst_info, there are two functions:
96     krb5_krbhst_format_string() that will return a printable representation
97     of that struct and krb5_krbhst_get_addrinfo() that will return a struct
98     addrinfo that can then be used for communicating with the server men‐
99     tioned.
100

EXAMPLES

102     The following code will print the KDCs of the realm “MY.REALM”:
103
104           krb5_krbhst_handle handle;
105           char host[MAXHOSTNAMELEN];
106           krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
107           while(krb5_krbhst_next_as_string(context, handle,
108                                            host, sizeof(host)) == 0)
109               printf("%s\n", host);
110           krb5_krbhst_free(context, handle);
111

SEE ALSO

113     getaddrinfo(3), krb5_get_krbhst(3), krb5_send_to_kdc_flags(3)
114

HISTORY

116     These functions first appeared in Heimdal 0.3g.
117
118HEIMDAL                          May 10, 2005                          HEIMDAL
Impressum