Merge from vendor branch GCC:
[dragonfly.git] / crypto / heimdal-0.6.3 / doc / kerberos4.texi
1 @c $Id: kerberos4.texi,v 1.16 2001/07/19 17:17:46 assar Exp $
2
3 @node Kerberos 4 issues, Windows 2000 compatability, Things in search for a better place, Top
4 @comment  node-name,  next,  previous,  up
5 @chapter Kerberos 4 issues
6
7 If compiled with version 4 support, the KDC can serve requests from a
8 Kerberos 4 client. There are a few things you must do for this to work.
9
10 The KDC will also have kaserver emulation and be able to handle
11 AFS-clients that use @code{klog}.
12
13 @menu
14 * Principal conversion issues::  
15 * Converting a version 4 database::  
16 * kaserver::
17 @end menu
18
19 @node Principal conversion issues, Converting a version 4 database, Kerberos 4 issues, Kerberos 4 issues
20 @section Principal conversion issues
21
22 First, Kerberos 4 and Kerberos 5 principals are different. A version 4
23 principal consists of a name, an instance, and a realm. A version 5
24 principal has one or more components, and a realm (the terms ``name''
25 and ``instance'' are still used, for the first and second component,
26 respectively).    Also, in some cases the name of a version 4 principal
27 differs from the first component of the corresponding version 5
28 principal. One notable example is the ``host'' type principals, where
29 the version 4 name is @samp{rcmd} (for ``remote command''), and the
30 version 5 name is @samp{host}. For the class of principals that has a
31 hostname as instance, there is an other major difference, Kerberos 4
32 uses only the first component of the hostname, whereas Kerberos 5 uses
33 the fully qualified hostname.
34
35 Because of this it can be hard or impossible to correctly convert a
36 version 4 principal to a version 5 principal @footnote{the other way is
37 not always trivial either, but usually easier}. The biggest problem is
38 to know if the conversion resulted in a valid principal. To give an
39 example, suppose you want to convert the principal @samp{rcmd.foo}.
40
41 The @samp{rcmd} name suggests that the instance is a hostname (even if
42 there are exceptions to this rule). To correctly convert the instance
43 @samp{foo} to a hostname, you have to know which host it is referring
44 to. You can to this by either guessing (from the realm) which domain
45 name to append, or you have to have a list of possible hostnames. In the
46 simplest cases you can cover most principals with the first rule. If you
47 have several domains sharing a single realm this will not usually
48 work. If the exceptions are few you can probably come by with a lookup
49 table for the exceptions.
50
51 In a complex scenario you will need some kind of host lookup mechanism.
52 Using DNS for this is tempting, but DNS is error prone, slow and unsafe
53 @footnote{at least until secure DNS is commonly available}.
54
55 Fortunately, the KDC has a trump on hand: it can easily tell if a
56 principal exists in the database. The KDC will use
57 @code{krb5_425_conv_principal_ext} to convert principals when handling
58 to version 4 requests.
59
60 @node Converting a version 4 database, kaserver , Principal conversion issues, Kerberos 4 issues
61 @section Converting a version 4 database
62
63 If you want to convert an existing version 4 database, the principal
64 conversion issue arises too.
65
66 If you decide to convert your database once and for all, you will only
67 have to do this conversion once. It is also possible to run a version 5
68 KDC as a slave to a version 4 KDC. In this case this conversion will
69 happen every time the database is propagated.  When doing this
70 conversion, there are a few things to look out for. If you have stale
71 entries in the database, these entries will not be converted. This might
72 be because these principals are not used anymore, or it might be just
73 because the principal couldn't be converted.
74
75 You might also see problems with a many-to-one mapping of
76 principals. For instance, if you are using DNS lookups and you have two
77 principals @samp{rcmd.foo} and @samp{rcmd.bar}, where `foo' is a CNAME
78 for `bar', the resulting principals will be the same. Since the
79 conversion function can't tell which is correct, these conflicts will
80 have to be resolved manually.
81
82 @subsection Conversion example
83
84 Given the following set of hosts and services:
85
86 @example
87 foo.se          rcmd
88 mail.foo.se     rcmd, pop
89 ftp.bar.se      rcmd, ftp
90 @end example
91
92 you have a database that consists of the following principals:
93
94 @samp{rcmd.foo}, @samp{rcmd.mail}, @samp{pop.mail}, @samp{rcmd.ftp}, and
95 @samp{ftp.ftp}.
96
97 lets say you also got these extra principals: @samp{rcmd.gone},
98 @samp{rcmd.old-mail}, where @samp{gone.foo.se} was a machine that has
99 now passed away, and @samp{old-mail.foo.se} was an old mail machine that
100 is now a CNAME for @samp{mail.foo.se}.
101
102 When you convert this database you want the following conversions to be
103 done:
104 @example
105 rcmd.foo         host/foo.se
106 rcmd.mail        host/mail.foo.se
107 pop.mail         pop/mail.foo.se
108 rcmd.ftp         host/ftp.bar.se
109 ftp.ftp          ftp/ftp.bar.se
110 rcmd.gone        @i{removed}
111 rcmd.old-mail    @i{removed}
112 @end example
113
114 A @file{krb5.conf} that does this looks like:
115
116 @example
117 [realms]
118         FOO.SE = @{
119                 v4_name_convert = @{
120                         host = @{
121                                 ftp = ftp
122                                 pop = pop
123                                 rcmd = host
124                         @}
125                 @}
126                 v4_instance_convert = @{
127                         foo = foo.se
128                         ftp = ftp.bar.se
129                 @}
130                 default_domain = foo.se
131         @}
132 @end example
133
134 The @samp{v4_name_convert} section says which names should be considered
135 having an instance consisting of a hostname, and it also says how the
136 names should be converted (for instance @samp{rcmd} should be converted
137 to @samp{host}). The @samp{v4_instance_convert} section says how a
138 hostname should be qualified (this is just a hosts-file in
139 disguise). Host-instances that aren't covered by
140 @samp{v4_instance_convert} are qualified by appending the contents of
141 the @samp{default_domain}.
142
143 Actually, this example doesn't work. Or rather, it works to well. Since
144 it has no way of knowing which hostnames are valid and which are not, it
145 will happily convert @samp{rcmd.gone} to @samp{host/gone.foo.se}. This
146 isn't a big problem, but if you have run your kerberos realm for a few
147 years, chances are big that you have quite a few `junk' principals.
148
149 If you don't want this you can remove the @samp{default_domain}
150 statement, but then you will have to add entries for @emph{all} your hosts
151 in the @samp{v4_instance_convert} section.
152
153 Instead of doing this you can use DNS to convert instances. This is not
154 a solution without problems, but it is probably easier than adding lots
155 of static host entries. 
156
157 To enable DNS lookup you should turn on @samp{v4_instance_resolve} in
158 the @samp{[libdefaults]} section.
159
160 @subsection Converting a database
161
162 The database conversion is done with @samp{hprop}. You can run this
163 command to propagate the database to the machine called
164 @samp{slave-server} (which should be running a @samp{hpropd}).
165
166 @example
167 hprop --source=krb4-db --master-key=/.m slave-server
168 @end example
169
170 This command can also be to use for converting the v4 database on the
171 server:
172
173 @example
174 hprop -n --source=krb4-db -d /var/kerberos/principal --master-key=/.m | hpropd -n
175 @end example
176
177 @section Version 4 Kadmin
178
179 @samp{kadmind} can act as a version 4 kadmind, and you can do most
180 operations, but with some restrictions (since the version 4 kadmin
181 protocol is, lets say, very ad hoc.) One example is that it only passes
182 des keys when creating principals and changing passwords (modern kpasswd
183 clients do send the password, so it's possible to to password quality
184 checks). Because of this you can only create principals with des keys,
185 and you can't set any flags or do any other fancy stuff.
186
187 To get this to work, you have to add another entry to inetd (since
188 version 4 uses port 751, not 749).
189
190 @emph{And then there are a many more things you can do; more on this in
191 a later version of this manual. Until then, UTSL.}
192
193 @node kaserver, , Converting a version 4 database, Kerberos 4 issues
194 @section kaserver
195
196 @subsection kaserver emulation
197
198 The Heimdal kdc can emulate a kaserver. The kaserver is a Kerberos 4
199 server with pre-authentication using Rx as the on-wire protocol. The kdc
200 contains a minimalistic Rx implementation.
201
202 There are three parts of the kaserver; KAA (Authentication), KAT (Ticket
203 Granting), and KAM (Maintenance). The KAA interface and KAT interface
204 both passes over DES encrypted data-blobs (just like the
205 Kerberos-protocol) and thus do not need any other protection.  The KAM
206 interface uses @code{rxkad} (Kerberos authentication layer for Rx) for
207 security and data protection, and is used for example for changing
208 passwords.  This part is not implemented in the kdc.
209
210 Another difference between the ka-protocol and the Kerberos 4 protocol
211 is that the pass-phrase is salted with the cellname in the @code{string to
212 key} function in the ka-protocol, while in the Kerberos 4 protocol there
213 is no salting of the password at all. To make sure AFS-compatible keys
214 are added to each principals when they are created or their password are
215 changed, @samp{afs3-salt} should be added to
216 @samp{[kadmin]default_keys}.
217
218 @subsection Transarc AFS Windows client
219
220 The Transarc Windows client uses Kerberos 4 to obtain tokens, and thus
221 does not need a kaserver. The Windows client assumes that the Kerberos
222 server is on the same machine as the AFS-database server. If you do not
223 like to do that you can add a small program that runs on the database
224 servers that forward all kerberos requests to the real kerberos
225 server. A program that does this is @code{krb-forward}
226 (@url{ftp://ftp.stacken.kth.se/pub/projekts/krb-forward}).