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