crypto/kerberosIV/man/krb_realmofhost.3

   1 .\" $Id: krb_realmofhost.3,v 1.2 1996/06/12 21:29:23 bg Exp $
   2 .\" $FreeBSD: src/crypto/kerberosIV/man/krb_realmofhost.3,v 1.2 2000/02/24 20:21:15 markm Exp $
   3 .\" Copyright 1989 by the Massachusetts Institute of Technology.
   4 .\"
   5 .\" For copying and distribution information,
   6 .\" please see the file <mit-copyright.h>.
   7 .\"
   8 .TH KRB_REALMOFHOST 3 "Kerberos Version 4.0" "MIT Project Athena"
   9 .SH NAME
  10 krb_realmofhost, krb_get_phost, krb_get_krbhst, krb_get_admhst,
  11 krb_get_lrealm \- additional Kerberos utility routines
  12 .SH SYNOPSIS
  13 .nf
  14 .nj
  15 .ft B
  16 #include <krb.h>
  17 #include <openssl/des.h>
  18 #include <netinet/in.h>
  19 .PP
  20 .ft B
  21 char *krb_realmofhost(host)
  22 char *host;
  23 .PP
  24 .ft B
  25 char *krb_get_phost(alias)
  26 char *alias;
  27 .PP
  28 .ft B
  29 krb_get_krbhst(host,realm,n)
  30 char *host;
  31 char *realm;
  32 int n;
  33 .PP
  34 .ft B
  35 krb_get_admhst(host,realm,n)
  36 char *host;
  37 char *realm;
  38 int n;
  39 .PP
  40 .ft B
  41 krb_get_lrealm(realm,n)
  42 char *realm;
  43 int n;
  44 .fi
  45 .ft R
  46 .SH DESCRIPTION
  47 .I krb_realmofhost
  48 returns the Kerberos realm of the host
  49 .IR host ,
  50 as determined by the translation table
  51 .IR /etc/krb.realms .
  52 .I host
  53 should be the fully-qualified domain-style primary host name of the host
  54 in question.  In order to prevent certain security attacks, this routine
  55 must either have
  56 .I a priori
  57 knowledge of a host's realm, or obtain such information securely.
  58 .PP
  59 The format of the translation file is described by
  60 .IR krb.realms (5).
  61 If
  62 .I host
  63 exactly matches a host_name line, the corresponding realm
  64 is returned.
  65 Otherwise, if the domain portion of
  66 .I host
  67 matches a domain_name line, the corresponding realm
  68 is returned.
  69 If
  70 .I host
  71 contains a domain, but no translation is found,
  72 .IR host 's
  73 domain is converted to upper-case and returned.
  74 If
  75 .I host
  76 contains no discernable domain, or an error occurs,
  77 the local realm name, as supplied by
  78 .IR krb_get_lrealm (3),
  79 is returned.
  80 .PP
  81 .I krb_get_phost
  82 converts the hostname
  83 .I alias
  84 (which can be either an official name or an alias) into the instance
  85 name to be used in obtaining Kerberos tickets for most services,
  86 including the Berkeley rcmd suite (rlogin, rcp, rsh).
  87 .br
  88 The current convention is to return the first segment of the official
  89 domain-style name after conversion to lower case.
  90 .PP
  91 .I krb_get_krbhst
  92 fills in
  93 .I host
  94 with the hostname of the
  95 .IR n th
  96 host running a Kerberos key distribution center (KDC)
  97 for realm
  98 .IR realm ,
  99 as specified in the configuration file (\fI/etc/krb.conf\fR).
 100 The configuration file is described by
 101 .IR krb.conf (5).
 102 If the host is successfully filled in, the routine
 103 returns KSUCCESS.
 104 If the file cannot be opened, and
 105 .I n
 106 equals 1, then the value of KRB_HOST as defined in
 107 .I <krb.h>
 108 is filled in, and KSUCCESS is returned.  If there are fewer than
 109 .I n
 110 hosts running a Kerberos KDC for the requested realm, or the
 111 configuration file is malformed, the routine
 112 returns KFAILURE.
 113 .PP
 114 .I krb_get_admhst
 115 fills in
 116 .I host
 117 with the hostname of the
 118 .IR n th
 119 host running a Kerberos KDC database administration server
 120 for realm
 121 .IR realm ,
 122 as specified in the configuration file (\fI/etc/krb.conf\fR).
 123 If the file cannot be opened or is malformed, or there are fewer than
 124 .I n
 125 hosts running a Kerberos KDC database administration server,
 126 the routine returns KFAILURE.
 127 .PP
 128 The character arrays used as return values for
 129 .IR krb_get_krbhst ,
 130 .IR krb_get_admhst ,
 131 should be large enough to
 132 hold any hostname (MAXHOSTNAMELEN from <sys/param.h>).
 133 .PP
 134 .I krb_get_lrealm
 135 fills in
 136 .I realm
 137 with the
 138 .IR n th
 139 realm of the local host, as specified in the configuration file.
 140 .I realm
 141 should be at least REALM_SZ (from
 142 .IR <krb.h>) characters long.
 143 .PP
 144 .SH SEE ALSO
 145 kerberos(3), krb.conf(5), krb.realms(5)
 146 .SH FILES
 147 .TP 20n
 148 /etc/krb.realms
 149 translation file for host-to-realm mapping.
 150 .TP
 151 /etc/krb.conf
 152 local realm-name and realm/server configuration file.
 153 .SH BUGS
 154 The current convention for instance names is too limited; the full
 155 domain name should be used.
 156 .PP
 157 .I krb_get_lrealm
 158 currently only supports
 159 .I n
 160 = 1.  It should really consult the user's ticket cache to determine the
 161 user's current realm, rather than consulting a file on the host.