crypto/external/bsd/heimdal/dist/doc/kerberos4.texi

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