1.\" $NetBSD: krb5_krbhst_init.3,v 1.1.1.2 2011/04/14 14:09:23 elric Exp $ 2.\" 3.\" Copyright (c) 2001-2005 Kungliga Tekniska Högskolan 4.\" (Royal Institute of Technology, Stockholm, Sweden). 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" 3. Neither the name of the Institute nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" Id 35.\" 36.Dd May 10, 2005 37.Dt KRB5_KRBHST_INIT 3 38.Os 39.Sh NAME 40.Nm krb5_krbhst_init , 41.Nm krb5_krbhst_init_flags , 42.Nm krb5_krbhst_next , 43.Nm krb5_krbhst_next_as_string , 44.Nm krb5_krbhst_reset , 45.Nm krb5_krbhst_free , 46.Nm krb5_krbhst_format_string , 47.Nm krb5_krbhst_get_addrinfo 48.Nd lookup Kerberos KDC hosts 49.Sh LIBRARY 50Kerberos 5 Library (libkrb5, -lkrb5) 51.Sh SYNOPSIS 52.In krb5/krb5.h 53.Ft krb5_error_code 54.Fn krb5_krbhst_init "krb5_context context" "const char *realm" "unsigned int type" "krb5_krbhst_handle *handle" 55.Ft krb5_error_code 56.Fn krb5_krbhst_init_flags "krb5_context context" "const char *realm" "unsigned int type" "int flags" "krb5_krbhst_handle *handle" 57.Ft krb5_error_code 58.Fn "krb5_krbhst_next" "krb5_context context" "krb5_krbhst_handle handle" "krb5_krbhst_info **host" 59.Ft krb5_error_code 60.Fn krb5_krbhst_next_as_string "krb5_context context" "krb5_krbhst_handle handle" "char *hostname" "size_t hostlen" 61.Ft void 62.Fn krb5_krbhst_reset "krb5_context context" "krb5_krbhst_handle handle" 63.Ft void 64.Fn krb5_krbhst_free "krb5_context context" "krb5_krbhst_handle handle" 65.Ft krb5_error_code 66.Fn krb5_krbhst_format_string "krb5_context context" "const krb5_krbhst_info *host" "char *hostname" "size_t hostlen" 67.Ft krb5_error_code 68.Fn krb5_krbhst_get_addrinfo "krb5_context context" "krb5_krbhst_info *host" "struct addrinfo **ai" 69.Sh DESCRIPTION 70These functions are used to sequence through all Kerberos hosts of a 71particular realm and service. The service type can be the KDCs, the 72administrative servers, the password changing servers, or the servers 73for Kerberos 4 ticket conversion. 74.Pp 75First a handle to a particular service is obtained by calling 76.Fn krb5_krbhst_init 77(or 78.Fn krb5_krbhst_init_flags ) 79with the 80.Fa realm 81of interest and the type of service to lookup. The 82.Fa type 83can be one of: 84.Pp 85.Bl -tag -width Ds -compact -offset indent 86.It KRB5_KRBHST_KDC 87.It KRB5_KRBHST_ADMIN 88.It KRB5_KRBHST_CHANGEPW 89.It KRB5_KRBHST_KRB524 90.El 91.Pp 92The 93.Fa handle 94is returned to the caller, and should be passed to the other 95functions. 96.Pp 97The 98.Fa flag 99argument to 100.Nm krb5_krbhst_init_flags 101is the same flags as 102.Fn krb5_send_to_kdc_flags 103uses. 104Possible values are: 105.Pp 106.Bl -tag -width KRB5_KRBHST_FLAGS_LARGE_MSG -compact -offset indent 107.It KRB5_KRBHST_FLAGS_MASTER 108only talk to master (readwrite) KDC 109.It KRB5_KRBHST_FLAGS_LARGE_MSG 110this is a large message, so use transport that can handle that. 111.El 112.Pp 113For each call to 114.Fn krb5_krbhst_next 115information on a new host is returned. The former function returns in 116.Fa host 117a pointer to a structure containing information about the host, such 118as protocol, hostname, and port: 119.Bd -literal -offset indent 120typedef struct krb5_krbhst_info { 121 enum { KRB5_KRBHST_UDP, 122 KRB5_KRBHST_TCP, 123 KRB5_KRBHST_HTTP } proto; 124 unsigned short port; 125 struct addrinfo *ai; 126 struct krb5_krbhst_info *next; 127 char hostname[1]; 128} krb5_krbhst_info; 129.Ed 130.Pp 131The related function, 132.Fn krb5_krbhst_next_as_string , 133return the same information as a URL-like string. 134.Pp 135When there are no more hosts, these functions return 136.Dv KRB5_KDC_UNREACH . 137.Pp 138To re-iterate over all hosts, call 139.Fn krb5_krbhst_reset 140and the next call to 141.Fn krb5_krbhst_next 142will return the first host. 143.Pp 144When done with the handle, 145.Fn krb5_krbhst_free 146should be called. 147.Pp 148To use a 149.Va krb5_krbhst_info , 150there are two functions: 151.Fn krb5_krbhst_format_string 152that will return a printable representation of that struct 153and 154.Fn krb5_krbhst_get_addrinfo 155that will return a 156.Va struct addrinfo 157that can then be used for communicating with the server mentioned. 158.Sh EXAMPLES 159The following code will print the KDCs of the realm 160.Dq MY.REALM : 161.Bd -literal -offset indent 162krb5_krbhst_handle handle; 163char host[MAXHOSTNAMELEN]; 164krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle); 165while(krb5_krbhst_next_as_string(context, handle, 166 host, sizeof(host)) == 0) 167 printf("%s\\n", host); 168krb5_krbhst_free(context, handle); 169.Ed 170.\" .Sh BUGS 171.Sh SEE ALSO 172.Xr getaddrinfo 3 , 173.Xr krb5_get_krbhst 3 , 174.Xr krb5_send_to_kdc_flags 3 175.Sh HISTORY 176These functions first appeared in Heimdal 0.3g. 177