summaryrefslogtreecommitdiff
path: root/kerberosIV/krb/krb_realmofhost.3
blob: 93793078ae8695515f546c06f501c7a672b89712 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
.\"
.\" This source code is no longer held under any constraint of USA
.\" `cryptographic laws' since it was exported legally.  The cryptographic
.\" functions were removed from the code and a "Bones" distribution was
.\" made.  A Commodity Jurisdiction Request #012-94 was filed with the
.\" USA State Department, who handed it to the Commerce department.  The
.\" code was determined to fall under General License GTDA under ECCN 5D96G,
.\" and hence exportable.  The cryptographic interfaces were re-added by Eric
.\" Young, and then KTH proceeded to maintain the code in the free world.
.\"
.\"Copyright (C) 1989 by the Massachusetts Institute of Technology
.\"
.\"Export of this software from the United States of America is assumed
.\"to require a specific license from the United States Government.
.\"It is the responsibility of any person or organization contemplating
.\"export to obtain such a license before exporting.
.\"
.\"WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
.\"distribute this software and its documentation for any purpose and
.\"without fee is hereby granted, provided that the above copyright
.\"notice appear in all copies and that both that copyright notice and
.\"this permission notice appear in supporting documentation, and that
.\"the name of M.I.T. not be used in advertising or publicity pertaining
.\"to distribution of the software without specific, written prior
.\"permission.  M.I.T. makes no representations about the suitability of
.\"this software for any purpose.  It is provided "as is" without express
.\"or implied warranty.
.\"
.\"	$OpenBSD: krb_realmofhost.3,v 1.5 1999/05/12 13:26:47 aaron Exp $
.TH KRB_REALMOFHOST 3 "Kerberos Version 4.0" "MIT Project Athena"
.SH NAME
krb_realmofhost, krb_get_phost, krb_get_krbhst, krb_get_admhst,
krb_get_lrealm \- additional Kerberos utility routines
.SH SYNOPSIS
.nf
.nj
.ft B
#include <kerberosIV/krb.h>
#include <kerberosIV/des.h>
#include <kerberosIV/netinet/in.h>
.PP
.ft B
char *krb_realmofhost(host)
char *host;
.PP
.ft B
char *krb_get_phost(alias)
char *alias;
.PP
.ft B
krb_get_krbhst(host,realm,n)
char *host;
char *realm;
int n;
.PP
.ft B
krb_get_admhst(host,realm,n)
char *host;
char *realm;
int n;
.PP
.ft B
krb_get_lrealm(realm,n)
char *realm;
int n;
.fi
.ft R
.SH DESCRIPTION
.I krb_realmofhost
returns the Kerberos realm of the host
.IR host ,
as determined by the translation table
.IR /etc/krb.realms .
.I host
should be the fully qualified domain-style primary host name of the host
in question.  In order to prevent certain security attacks, this routine
must either have 
.I a priori
knowledge of a host's realm, or obtain such information securely.
.PP
The format of the translation file is described by 
.IR krb.realms (5).
If
.I host
exactly matches a host_name line, the corresponding realm
is returned.
Otherwise, if the domain portion of
.I host
matches a domain_name line, the corresponding realm
is returned.
If
.I host
contains a domain, but no translation is found,
.IR host 's
domain is converted to upper-case and returned.
If 
.I host
contains no discernable domain, or an error occurs,
the local realm name, as supplied by 
.IR krb_get_lrealm (3),
is returned.
.PP
.I krb_get_phost
converts the hostname
.I alias
(which can be either an official name or an alias) into the instance
name to be used in obtaining Kerberos tickets for most services,
including the Berkeley rcmd suite (rlogin, rcp, rsh).
.br
The current convention is to return the first segment of the official
domain-style name after conversion to lower case.
.PP
.I krb_get_krbhst
fills in
.I host
with the hostname of the
.IR n th
host running a Kerberos key distribution center (KDC)
for realm
.IR realm ,
as specified in the configuration file (\fI/etc/krb.conf\fR).
The configuration file is described by 
.IR krb.conf (5).
If the host is successfully filled in, the routine
returns KSUCCESS.
If the file cannot be opened, and
.I n
equals 1, then the value of KRB_HOST as defined in
.I <krb.h>
is filled in, and KSUCCESS is returned.  If there are fewer than
.I n
hosts running a Kerberos KDC for the requested realm, or the
configuration file is malformed, the routine
returns KFAILURE.
.PP
.I krb_get_admhst
fills in
.I host
with the hostname of the
.IR n th
host running a Kerberos KDC database administration server
for realm
.IR realm ,
as specified in the configuration file (\fI/etc/krb.conf\fR).
If the file cannot be opened or is malformed, or there are fewer than
.I n
hosts running a Kerberos KDC database administration server,
the routine returns KFAILURE.
.PP
The character arrays used as return values for
.IR krb_get_krbhst ,
.IR krb_get_admhst ,
should be large enough to
hold any hostname (MAXHOSTNAMELEN from <sys/param.h>).
.PP
.I krb_get_lrealm
fills in
.I realm
with the
.IR n th
realm of the local host, as specified in the configuration file.
.I realm
should be at least REALM_SZ (from
.IR <krb.h>) characters long.
.PP
.SH SEE ALSO
kerberos(3), krb.conf(5), krb.realms(5)
.SH FILES
.TP 20n
/etc/krb.realms
translation file for host-to-realm mapping.
.TP
/etc/krb.conf
local realm-name and realm/server configuration file.
.SH BUGS
The current convention for instance names is too limited; the full
domain name should be used.
.PP
.I krb_get_lrealm
currently only supports 
.I n
= 1.  It should really consult the user's ticket cache to determine the
user's current realm, rather than consulting a file on the host.