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