crypto/heimdal/lib/krb5/krb5_425_conv_principal.3

   1 .\" Copyright (c) 1997-2002 Kungliga Tekniska Högskolan
   2 .\" $Id: krb5_425_conv_principal.3,v 1.8 2002/08/28 15:30:46 joda Exp $
   3 .Dd April 11, 1999
   4 .Dt KRB5_425_CONV_PRINCIPAL 3
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm krb5_425_conv_principal ,
   8 .Nm krb5_425_conv_principal_ext ,
   9 .Nm krb5_524_conv_principal
  10 .Nd converts to and from version 4 principals
  11 .Sh LIBRARY
  12 Kerberos 5 Library (libkrb5, -lkrb5)
  13 .Sh SYNOPSIS
  14 .Fd #include <krb5.h>
  15 .Ft krb5_error_code
  16 .Fn krb5_425_conv_principal "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_principal *principal"
  17 .Ft krb5_error_code
  18 .Fn krb5_425_conv_principal_ext "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_boolean (*func)(krb5_context, krb5_principal)" "krb5_boolean resolve" "krb5_principal *principal"
  19 .Ft krb5_error_code
  20 .Fn krb5_524_conv_principal "krb5_context context" "const krb5_principal principal" "char *name" "char *instance" "char *realm"
  21 .Sh DESCRIPTION
  22 Converting between version 4 and version 5 principals can at best be
  23 described as a mess.
  24 .Pp
  25 A version 4 principal consists of a name, an instance, and a realm. A
  26 version 5 principal consists of one or more components, and a
  27 realm. In some cases also the first component/name will differ between
  28 version 4 and version 5.  Furthermore the second component of a host
  29 principal will be the fully qualified domain name of the host in
  30 question, while the instance of a version 4 principal will only
  31 contain the first part (short hostname).  Because of these problems
  32 the conversion between principals will have to be site customized.
  33 .Pp
  34 .Fn krb5_425_conv_principal_ext
  35 will try to convert a version 4 principal, given by
  36 .Fa name ,
  37 .Fa instance ,
  38 and
  39 .Fa realm ,
  40 to a version 5 principal. This can result in several possible
  41 principals, and if
  42 .Fa func
  43 is non-NULL, it will be called for each candidate principal.
  44 .Fa func
  45 should return true if the principal was
  46 .Dq good .
  47 To accomplish this,
  48 .Fn krb5_425_conv_principal_ext
  49 will look up the name in
  50 .Pa krb5.conf .
  51 It first looks in the
  52 .Li v4_name_convert/host
  53 subsection, which should contain a list of version 4 names whose
  54 instance should be treated as a hostname. This list can be specified
  55 for each realm (in the
  56 .Li realms
  57 section), or in the
  58 .Li libdefaults
  59 section.  If the name is found the resulting name of the principal
  60 will be the value of this binding. The instance is then first looked
  61 up in
  62 .Li v4_instance_convert
  63 for the specified realm. If found the resulting value will be used as
  64 instance (this can be used for special cases), no further attempts
  65 will be made to find a conversion if this fails (with
  66 .Fa func ) .
  67 If the
  68 .Fa resolve
  69 parameter is true, the instance will be looked up with
  70 .Fn gethostbyname .
  71 This can be a time consuming, error prone, and unsafe operation.  Next
  72 a list of hostnames will be created from the instance and the
  73 .Li v4_domains
  74 variable, which should contain a list of possible domains for the
  75 specific realm.
  76 .Pp
  77 On the other hand, if the name is not found in a
  78 .Li host
  79 section, it is looked up in a
  80 .Li v4_name_convert/plain
  81 binding. If found here the name will be converted, but the instance
  82 will be untouched.
  83 .Pp
  84 This list of default host-type conversions is compiled-in:
  85 .Bd -literal -offset indent
  86 v4_name_convert = {
  87         host = {
  88                 ftp = ftp
  89                 hprop = hprop
  90                 imap = imap
  91                 pop = pop
  92                 rcmd = host
  93                 smtp = smtp
  94         }
  95 }
  96 .Ed
  97 .Pp
  98 It will only be used if there isn't an entry for these names in the
  99 config file, so you can override these defaults.
 100 .Pp
 101 .Fn krb5_425_conv_principal
 102 will call
 103 .Fn krb5_425_conv_principal_ext
 104 with
 105 .Dv NULL
 106 as
 107 .Fa func ,
 108 and the value of
 109 .Li v4_instance_resolve
 110 (from the
 111 .Li libdefaults
 112 section) as
 113 .Fa resolve .
 114 .Pp
 115 .Fn krb5_524_conv_principal
 116 basically does the opposite of
 117 .Fn krb5_425_conv_principal ,
 118 it just doesn't have to look up any names, but will instead truncate
 119 instances found to belong to a host principal. The
 120 .Fa name ,
 121 .Fa instance ,
 122 and
 123 .Fa realm
 124 should be at least 40 characters long.
 125 .Sh EXAMPLES
 126 Since this is confusing an example is in place.
 127 .Pp
 128 Assume that we have the
 129 .Dq foo.com ,
 130 and
 131 .Dq bar.com
 132 domains that have shared a single version 4 realm, FOO.COM. The version 4
 133 .Pa krb.realms
 134 file looked like:
 135 .Bd -literal -offset indent
 136 foo.com         FOO.COM
 137 \&.foo.com      FOO.COM
 138 \&.bar.com      FOO.COM
 139 .Ed
 140 .Pp
 141 A
 142 .Pa krb5.conf
 143 file that covers this case might look like:
 144 .Bd -literal -offset indent
 145 [libdefaults]
 146         v4_instance_resolve = yes
 147 [realms]
 148         FOO.COM = {
 149                 kdc = kerberos.foo.com
 150                 v4_instance_convert = {
 151                         foo = foo.com
 152                 }
 153                 v4_domains = foo.com
 154         }
 155 .Ed
 156 .Pp
 157 With this setup and the following host table:
 158 .Bd -literal -offset indent
 159 foo.com
 160 a-host.foo.com
 161 b-host.bar.com
 162 .Ed
 163 the following conversions will be made:
 164 .Bd -literal -offset indent
 165 rcmd.a-host     \(-> host/a-host.foo.com
 166 ftp.b-host      \(-> ftp/b-host.bar.com
 167 pop.foo         \(-> pop/foo.com
 168 ftp.other       \(-> ftp/other.foo.com
 169 other.a-host    \(-> other/a-host
 170 .Ed
 171 .Pp
 172 The first three are what you expect. If you remove the
 173 .Dq v4_domains ,
 174 the fourth entry will result in an error (since the host
 175 .Dq other
 176 can't be found). Even if
 177 .Dq a-host
 178 is a valid host name, the last entry will not be converted, since the
 179 .Dq other
 180 name is not known to represent a host-type principal.
 181 If you turn off
 182 .Dq v4_instance_resolve
 183 the second example will result in
 184 .Dq ftp/b-host.foo.com
 185 (because of the default domain). And all of this is of course only
 186 valid if you have working name resolving.
 187 .Sh SEE ALSO
 188 .Xr krb5_build_principal 3 ,
 189 .Xr krb5_free_principal 3 ,
 190 .Xr krb5_parse_name 3 ,
 191 .Xr krb5_sname_to_principal 3 ,
 192 .Xr krb5_unparse_name 3 ,
 193 .Xr krb5.conf 5