crypto/dist/heimdal/lib/krb5/krb5_425_conv_principal.3

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