crypto/heimdal-0.6.3/lib/krb5/krb5_425_conv_principal.3

   1 .\" Copyright (c) 1997-2002 Kungliga Tekniska Högskolan
   2 .\" (Royal Institute of Technology, Stockholm, Sweden).
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" 3. Neither the name of the Institute nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Id: krb5_425_conv_principal.3,v 1.10 2003/04/16 13:58:13 lha Exp $
  33 .\"
  34 .Dd April 11, 1999
  35 .Dt KRB5_425_CONV_PRINCIPAL 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_425_conv_principal ,
  39 .Nm krb5_425_conv_principal_ext ,
  40 .Nm krb5_524_conv_principal
  41 .Nd converts to and from version 4 principals
  42 .Sh LIBRARY
  43 Kerberos 5 Library (libkrb5, -lkrb5)
  44 .Sh SYNOPSIS
  45 .In krb5.h
  46 .Ft krb5_error_code
  47 .Fn krb5_425_conv_principal "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_principal *principal"
  48 .Ft krb5_error_code
  49 .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"
  50 .Ft krb5_error_code
  51 .Fn krb5_524_conv_principal "krb5_context context" "const krb5_principal principal" "char *name" "char *instance" "char *realm"
  52 .Sh DESCRIPTION
  53 Converting between version 4 and version 5 principals can at best be
  54 described as a mess.
  55 .Pp
  56 A version 4 principal consists of a name, an instance, and a realm. A
  57 version 5 principal consists of one or more components, and a
  58 realm. In some cases also the first component/name will differ between
  59 version 4 and version 5.  Furthermore the second component of a host
  60 principal will be the fully qualified domain name of the host in
  61 question, while the instance of a version 4 principal will only
  62 contain the first part (short hostname).  Because of these problems
  63 the conversion between principals will have to be site customized.
  64 .Pp
  65 .Fn krb5_425_conv_principal_ext
  66 will try to convert a version 4 principal, given by
  67 .Fa name ,
  68 .Fa instance ,
  69 and
  70 .Fa realm ,
  71 to a version 5 principal. This can result in several possible
  72 principals, and if
  73 .Fa func
  74 is non-NULL, it will be called for each candidate principal.
  75 .Fa func
  76 should return true if the principal was
  77 .Dq good .
  78 To accomplish this,
  79 .Fn krb5_425_conv_principal_ext
  80 will look up the name in
  81 .Pa krb5.conf .
  82 It first looks in the
  83 .Li v4_name_convert/host
  84 subsection, which should contain a list of version 4 names whose
  85 instance should be treated as a hostname. This list can be specified
  86 for each realm (in the
  87 .Li realms
  88 section), or in the
  89 .Li libdefaults
  90 section.  If the name is found the resulting name of the principal
  91 will be the value of this binding. The instance is then first looked
  92 up in
  93 .Li v4_instance_convert
  94 for the specified realm. If found the resulting value will be used as
  95 instance (this can be used for special cases), no further attempts
  96 will be made to find a conversion if this fails (with
  97 .Fa func ) .
  98 If the
  99 .Fa resolve
 100 parameter is true, the instance will be looked up with
 101 .Fn gethostbyname .
 102 This can be a time consuming, error prone, and unsafe operation.  Next
 103 a list of hostnames will be created from the instance and the
 104 .Li v4_domains
 105 variable, which should contain a list of possible domains for the
 106 specific realm.
 107 .Pp
 108 On the other hand, if the name is not found in a
 109 .Li host
 110 section, it is looked up in a
 111 .Li v4_name_convert/plain
 112 binding. If found here the name will be converted, but the instance
 113 will be untouched.
 114 .Pp
 115 This list of default host-type conversions is compiled-in:
 116 .Bd -literal -offset indent
 117 v4_name_convert = {
 118         host = {
 119                 ftp = ftp
 120                 hprop = hprop
 121                 imap = imap
 122                 pop = pop
 123                 rcmd = host
 124                 smtp = smtp
 125         }
 126 }
 127 .Ed
 128 .Pp
 129 It will only be used if there isn't an entry for these names in the
 130 config file, so you can override these defaults.
 131 .Pp
 132 .Fn krb5_425_conv_principal
 133 will call
 134 .Fn krb5_425_conv_principal_ext
 135 with
 136 .Dv NULL
 137 as
 138 .Fa func ,
 139 and the value of
 140 .Li v4_instance_resolve
 141 (from the
 142 .Li libdefaults
 143 section) as
 144 .Fa resolve .
 145 .Pp
 146 .Fn krb5_524_conv_principal
 147 basically does the opposite of
 148 .Fn krb5_425_conv_principal ,
 149 it just doesn't have to look up any names, but will instead truncate
 150 instances found to belong to a host principal. The
 151 .Fa name ,
 152 .Fa instance ,
 153 and
 154 .Fa realm
 155 should be at least 40 characters long.
 156 .Sh EXAMPLES
 157 Since this is confusing an example is in place.
 158 .Pp
 159 Assume that we have the
 160 .Dq foo.com ,
 161 and
 162 .Dq bar.com
 163 domains that have shared a single version 4 realm, FOO.COM. The version 4
 164 .Pa krb.realms
 165 file looked like:
 166 .Bd -literal -offset indent
 167 foo.com         FOO.COM
 168 \&.foo.com      FOO.COM
 169 \&.bar.com      FOO.COM
 170 .Ed
 171 .Pp
 172 A
 173 .Pa krb5.conf
 174 file that covers this case might look like:
 175 .Bd -literal -offset indent
 176 [libdefaults]
 177         v4_instance_resolve = yes
 178 [realms]
 179         FOO.COM = {
 180                 kdc = kerberos.foo.com
 181                 v4_instance_convert = {
 182                         foo = foo.com
 183                 }
 184                 v4_domains = foo.com
 185         }
 186 .Ed
 187 .Pp
 188 With this setup and the following host table:
 189 .Bd -literal -offset indent
 190 foo.com
 191 a-host.foo.com
 192 b-host.bar.com
 193 .Ed
 194 the following conversions will be made:
 195 .Bd -literal -offset indent
 196 rcmd.a-host     \(-> host/a-host.foo.com
 197 ftp.b-host      \(-> ftp/b-host.bar.com
 198 pop.foo         \(-> pop/foo.com
 199 ftp.other       \(-> ftp/other.foo.com
 200 other.a-host    \(-> other/a-host
 201 .Ed
 202 .Pp
 203 The first three are what you expect. If you remove the
 204 .Dq v4_domains ,
 205 the fourth entry will result in an error (since the host
 206 .Dq other
 207 can't be found). Even if
 208 .Dq a-host
 209 is a valid host name, the last entry will not be converted, since the
 210 .Dq other
 211 name is not known to represent a host-type principal.
 212 If you turn off
 213 .Dq v4_instance_resolve
 214 the second example will result in
 215 .Dq ftp/b-host.foo.com
 216 (because of the default domain). And all of this is of course only
 217 valid if you have working name resolving.
 218 .Sh SEE ALSO
 219 .Xr krb5_build_principal 3 ,
 220 .Xr krb5_free_principal 3 ,
 221 .Xr krb5_parse_name 3 ,
 222 .Xr krb5_sname_to_principal 3 ,
 223 .Xr krb5_unparse_name 3 ,
 224 .Xr krb5.conf 5