doc/kerberos4.texi

   1 @c $Id$
   2
   3 @node Kerberos 4 issues, Windows compatibility, Things in search for a better place, Top
   4 @comment  node-name,  next,  previous,  up
   5 @chapter Kerberos 4 issues
   6
   7 Kerberos 4 KDC and KA server have been moved.
   8
   9 For more about AFS, see the section @xref{AFS}.
  10
  11 @menu
  12 * Principal conversion issues::
  13 * Converting a version 4 database::
  14 @end menu
  15
  16 @node Principal conversion issues, Converting a version 4 database, Kerberos 4 issues, Kerberos 4 issues
  17 @section Principal conversion issues
  18
  19 First, Kerberos 4 and Kerberos 5 principals are different. A version 4
  20 principal consists of a name, an instance, and a realm. A version 5
  21 principal has one or more components, and a realm (the terms ``name''
  22 and ``instance'' are still used, for the first and second component,
  23 respectively).    Also, in some cases the name of a version 4 principal
  24 differs from the first component of the corresponding version 5
  25 principal. One notable example is the ``host'' type principals, where
  26 the version 4 name is @samp{rcmd} (for ``remote command''), and the
  27 version 5 name is @samp{host}. For the class of principals that has a
  28 hostname as instance, there is an other major difference, Kerberos 4
  29 uses only the first component of the hostname, whereas Kerberos 5 uses
  30 the fully qualified hostname.
  31
  32 Because of this it can be hard or impossible to correctly convert a
  33 version 4 principal to a version 5 principal @footnote{the other way is
  34 not always trivial either, but usually easier}. The biggest problem is
  35 to know if the conversion resulted in a valid principal. To give an
  36 example, suppose you want to convert the principal @samp{rcmd.foo}.
  37
  38 The @samp{rcmd} name suggests that the instance is a hostname (even if
  39 there are exceptions to this rule). To correctly convert the instance
  40 @samp{foo} to a hostname, you have to know which host it is referring
  41 to. You can to this by either guessing (from the realm) which domain
  42 name to append, or you have to have a list of possible hostnames. In the
  43 simplest cases you can cover most principals with the first rule. If you
  44 have several domains sharing a single realm this will not usually
  45 work. If the exceptions are few you can probably come by with a lookup
  46 table for the exceptions.
  47
  48 In a complex scenario you will need some kind of host lookup mechanism.
  49 Using DNS for this is tempting, but DNS is error prone, slow and unsafe
  50 @footnote{at least until secure DNS is commonly available}.
  51
  52 Fortunately, the KDC has a trump on hand: it can easily tell if a
  53 principal exists in the database. The KDC will use
  54 @code{krb5_425_conv_principal_ext} to convert principals when handling
  55 to version 4 requests.
  56
  57 @node Converting a version 4 database, , Principal conversion issues, Kerberos 4 issues
  58 @section Converting a version 4 database
  59
  60 If you want to convert an existing version 4 database, the principal
  61 conversion issue arises too.
  62
  63 If you decide to convert your database once and for all, you will only
  64 have to do this conversion once. It is also possible to run a version 5
  65 KDC as a slave to a version 4 KDC. In this case this conversion will
  66 happen every time the database is propagated.  When doing this
  67 conversion, there are a few things to look out for. If you have stale
  68 entries in the database, these entries will not be converted. This might
  69 be because these principals are not used anymore, or it might be just
  70 because the principal couldn't be converted.
  71
  72 You might also see problems with a many-to-one mapping of
  73 principals. For instance, if you are using DNS lookups and you have two
  74 principals @samp{rcmd.foo} and @samp{rcmd.bar}, where `foo' is a CNAME
  75 for `bar', the resulting principals will be the same. Since the
  76 conversion function can't tell which is correct, these conflicts will
  77 have to be resolved manually.
  78
  79 @subsection Conversion example
  80
  81 Given the following set of hosts and services:
  82
  83 @example
  84 foo.se          rcmd
  85 mail.foo.se     rcmd, pop
  86 ftp.bar.se      rcmd, ftp
  87 @end example
  88
  89 you have a database that consists of the following principals:
  90
  91 @samp{rcmd.foo}, @samp{rcmd.mail}, @samp{pop.mail}, @samp{rcmd.ftp}, and
  92 @samp{ftp.ftp}.
  93
  94 lets say you also got these extra principals: @samp{rcmd.gone},
  95 @samp{rcmd.old-mail}, where @samp{gone.foo.se} was a machine that has
  96 now passed away, and @samp{old-mail.foo.se} was an old mail machine that
  97 is now a CNAME for @samp{mail.foo.se}.
  98
  99 When you convert this database you want the following conversions to be
 100 done:
 101 @example
 102 rcmd.foo         host/foo.se
 103 rcmd.mail        host/mail.foo.se
 104 pop.mail         pop/mail.foo.se
 105 rcmd.ftp         host/ftp.bar.se
 106 ftp.ftp          ftp/ftp.bar.se
 107 rcmd.gone        @i{removed}
 108 rcmd.old-mail    @i{removed}
 109 @end example
 110
 111 A @file{krb5.conf} that does this looks like:
 112
 113 @example
 114 [realms]
 115         FOO.SE = @{
 116                 v4_name_convert = @{
 117                         host = @{
 118                                 ftp = ftp
 119                                 pop = pop
 120                                 rcmd = host
 121                         @}
 122                 @}
 123                 v4_instance_convert = @{
 124                         foo = foo.se
 125                         ftp = ftp.bar.se
 126                 @}
 127                 default_domain = foo.se
 128         @}
 129 @end example
 130
 131 The @samp{v4_name_convert} section says which names should be considered
 132 having an instance consisting of a hostname, and it also says how the
 133 names should be converted (for instance @samp{rcmd} should be converted
 134 to @samp{host}). The @samp{v4_instance_convert} section says how a
 135 hostname should be qualified (this is just a hosts-file in
 136 disguise). Host-instances that aren't covered by
 137 @samp{v4_instance_convert} are qualified by appending the contents of
 138 the @samp{default_domain}.
 139
 140 Actually, this example doesn't work. Or rather, it works to well. Since
 141 it has no way of knowing which hostnames are valid and which are not, it
 142 will happily convert @samp{rcmd.gone} to @samp{host/gone.foo.se}. This
 143 isn't a big problem, but if you have run your kerberos realm for a few
 144 years, chances are big that you have quite a few `junk' principals.
 145
 146 If you don't want this you can remove the @samp{default_domain}
 147 statement, but then you will have to add entries for @emph{all} your hosts
 148 in the @samp{v4_instance_convert} section.
 149
 150 Instead of doing this you can use DNS to convert instances. This is not
 151 a solution without problems, but it is probably easier than adding lots
 152 of static host entries.
 153
 154 To enable DNS lookup you should turn on @samp{v4_instance_resolve} in
 155 the @samp{[libdefaults]} section.
 156
 157 @subsection Converting a database
 158
 159 The database conversion is done with @samp{hprop}. You can run this
 160 command to propagate the database to the machine called
 161 @samp{slave-server} (which should be running a @samp{hpropd}).
 162
 163 @example
 164 hprop --source=krb4-db --master-key=/.m slave-server
 165 @end example
 166
 167 This command can also be to use for converting the v4 database on the
 168 server:
 169
 170 @example
 171 hprop -n --source=krb4-db -d /var/kerberos/principal --master-key=/.m | hpropd -n
 172 @end example
 173