| blob | 49028f42660c610ada8756201f62f7e1ffe1eadd |
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 .\" $Id$
33 .\"
34 .Dd September 3, 2003
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 -\*(Gt host/a-host.foo.com
197 ftp.b-host -\*(Gt ftp/b-host.bar.com
198 pop.foo -\*(Gt pop/foo.com
199 ftp.other -\*(Gt ftp/other.foo.com
200 other.a-host -\*(Gt 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