Import of Heimdal Kerberos from KTH repository circa 2002/02/17.

1 files changed, 120 insertions, 0 deletions

diff --git a/crypto/heimdal/lib/krb5/krb5_krbhst_init.3 b/crypto/heimdal/lib/krb5/krb5_krbhst_init.3
new file mode 100644
index 0000000..109c64c
--- /dev/null
+++ b/crypto/heimdal/lib/krb5/krb5_krbhst_init.3
@@ -0,0 +1,120 @@
+.\" Copyright (c) 2001 Kungliga Tekniska Högskolan
+.\" $Id: krb5_krbhst_init.3,v 1.3 2001/11/09 09:36:24 joda Exp $
+.Dd June 17, 2001
+.Dt KRB5_KRBHST_INIT 3
+.Os HEIMDAL
+.Sh NAME
+.Nm krb5_krbhst_init ,
+.Nm krb5_krbhst_next ,
+.Nm krb5_krbhst_next_as_string ,
+.Nm krb5_krbhst_reset ,
+.Nm krb5_krbhst_free ,
+.Nm krb5_krbhst_format_string ,
+.Nm krb5_krbhst_get_addrinfo
+.Nd lookup Kerberos KDC hosts
+.Sh SYNOPSIS
+.Fd #include <krb5.h>
+
+.Ft krb5_error_code
+.Fn krb5_krbhst_init "krb5_context context" "const char *realm" "unsigned int type" "krb5_krbhst_handle *handle"
+.Ft krb5_error_code
+.Fn "krb5_krbhst_next" "krb5_context context" "krb5_krbhst_handle handle" "krb5_krbhst_info **host"
+.Ft krb5_error_code
+.Fn krb5_krbhst_next_as_string "krb5_context context" "krb5_krbhst_handle handle" "char *hostname" "size_t hostlen"
+.Ft void
+.Fn krb5_krbhst_reset "krb5_context context" "krb5_krbhst_handle handle"
+.Ft void
+.Fn krb5_krbhst_free "krb5_context context" "krb5_krbhst_handle handle"
+.Ft krb5_error_code
+.Fn krb5_krbhst_format_string "krb5_context context" "const krb5_krbhst_info *host" "char *hostname" "size_t hostlen"
+.Ft krb5_error_code
+.Fn krb5_krbhst_get_addrinfo "krb5_context context" "krb5_krbhst_info *host" "struct addrinfo **ai"
+.Sh DESCRIPTION
+These functions are used to sequence through all Kerberos hosts of a
+particular realm and service. The service type can be the KDCs, the
+administrative servers, the password changing servers, or the servers
+for Kerberos 4 ticket conversion.
+.Pp
+First a handle to a particular service is obtained by calling
+.Fn krb5_krbhst_init 
+with the 
+.Fa realm
+of interest and the type of service to lookup. The 
+.Fa type
+can be one of:
+.Pp
+.Bl -hang -compact -offset indent
+.It KRB5_KRBHST_KDC
+.It KRB5_KRBHST_ADMIN
+.It KRB5_KRBHST_CHANGEPW
+.It KRB5_KRBHST_KRB524
+.El
+.Pp
+The
+.Fa handle
+is returned to the caller, and should be passed to the other
+functions.
+.Pp
+For each call to 
+.Fn krb5_krbhst_next
+information a new host is returned. The former function returns in
+.Fa host
+a pointer to a structure containing information about the host, such
+as protocol, hostname, and port:
+.Bd -literal -offset indent
+typedef struct krb5_krbhst_info {
+    enum { KRB5_KRBHST_UDP,
+	   KRB5_KRBHST_TCP,
+	   KRB5_KRBHST_HTTP } proto;
+    unsigned short port;
+    struct addrinfo *ai;
+    struct krb5_krbhst_info *next;
+    char hostname[1];
+} krb5_krbhst_info;
+.Ed
+.Pp
+The related function, 
+.Fn krb5_krbhst_next_as_string ,
+return the same information as a url-like string.
+.Pp
+When there are no more hosts, these functions return
+.Dv KRB5_KDC_UNREACH .
+.Pp
+To re-iterate over all hosts, call
+.Fn krb5_krbhst_reset
+and the next call to 
+.Fn krb5_krbhst_next
+will return the first host.
+.Pp
+When done with the handle, 
+.Fn krb5_krbhst_free
+should be called.
+.Pp
+To use a
+.Va krb5_krbhst_info ,
+there are two functions:
+.Fn krb5_krbhst_format_string
+that will return a printable representation of that struct
+and
+.Fn krb5_krbhst_get_addrinfo
+that will return a
+.Va struct addrinfo
+that can then be used for communicating with the server mentioned.
+.Sh EXAMPLE
+The following code will print the KDCs of the realm 
+.Dq MY.REALM .
+.Bd -literal -offset indent
+krb5_krbhst_handle handle;
+char host[MAXHOSTNAMELEN];
+krb5_krbhst_init(context, "MY.REALM", KRB5_KRBHST_KDC, &handle);
+while(krb5_krbhst_next_as_string(context, handle, 
+				 host, sizeof(host)) == 0)
+    printf("%s\\n", host);
+krb5_krbhst_free(context, handle);
+.Ed
+.\" .Sh BUGS
+.Sh HISTORY
+These functions first appeared in Heimdal 0.3g.
+.Sh SEE ALSO
+.Xr getaddrinfo 3 ,
+.Xr krb5_get_krbhst 3