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
12Kerberos 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
22Converting between version 4 and version 5 principals can at best be
23described as a mess.
24.Pp
25A version 4 principal consists of a name, an instance, and a realm. A
26version 5 principal consists of one or more components, and a
27realm. In some cases also the first component/name will differ between
28version 4 and version 5. Furthermore the second component of a host
29principal will be the fully qualified domain name of the host in
30question, while the instance of a version 4 principal will only
31contain the first part (short hostname). Because of these problems
32the conversion between principals will have to be site customized.
33.Pp
34.Fn krb5_425_conv_principal_ext
35will try to convert a version 4 principal, given by
36.Fa name ,
37.Fa instance ,
38and
39.Fa realm ,
40to a version 5 principal. This can result in several possible
41principals, and if
42.Fa func
43is non-NULL, it will be called for each candidate principal.
44.Fa func
45should return true if the principal was
46.Dq good .
47To accomplish this,
48.Fn krb5_425_conv_principal_ext
49will look up the name in
50.Pa krb5.conf .
51It first looks in the
52.Li v4_name_convert/host
53subsection, which should contain a list of version 4 names whose
54instance should be treated as a hostname. This list can be specified
55for each realm (in the
56.Li realms
57section), or in the
58.Li libdefaults
59section. If the name is found the resulting name of the principal
60will be the value of this binding. The instance is then first looked
61up in
62.Li v4_instance_convert
63for the specified realm. If found the resulting value will be used as
64instance (this can be used for special cases), no further attempts
65will be made to find a conversion if this fails (with
66.Fa func ) .
67If the
68.Fa resolve
69parameter is true, the instance will be looked up with
70.Fn gethostbyname .
71This can be a time consuming, error prone, and unsafe operation. Next
72a list of hostnames will be created from the instance and the
73.Li v4_domains
74variable, which should contain a list of possible domains for the
75specific realm.
76.Pp
77On the other hand, if the name is not found in a
78.Li host
79section, it is looked up in a
80.Li v4_name_convert/plain
81binding. If found here the name will be converted, but the instance
82will be untouched.
83.Pp
84This list of default host-type conversions is compiled-in:
85.Bd -literal -offset indent
86v4_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
98It will only be used if there isn't an entry for these names in the
99config file, so you can override these defaults.
100.Pp
101.Fn krb5_425_conv_principal
102will call
103.Fn krb5_425_conv_principal_ext
104with
105.Dv NULL
106as
107.Fa func ,
108and the value of
109.Li v4_instance_resolve
110(from the
111.Li libdefaults
112section) as
113.Fa resolve .
114.Pp
115.Fn krb5_524_conv_principal
116basically does the opposite of
117.Fn krb5_425_conv_principal ,
118it just doesn't have to look up any names, but will instead truncate
119instances found to belong to a host principal. The
120.Fa name ,
121.Fa instance ,
122and
123.Fa realm
124should be at least 40 characters long.
125.Sh EXAMPLES
126Since this is confusing an example is in place.
127.Pp
128Assume that we have the
129.Dq foo.com ,
130and
131.Dq bar.com
132domains that have shared a single version 4 realm, FOO.COM. The version 4
133.Pa krb.realms
134file looked like:
135.Bd -literal -offset indent
136foo.com FOO.COM
137\&.foo.com FOO.COM
138\&.bar.com FOO.COM
139.Ed
140.Pp
141A
142.Pa krb5.conf
143file 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
157With this setup and the following host table:
158.Bd -literal -offset indent
159foo.com
160a-host.foo.com
161b-host.bar.com
162.Ed
163the following conversions will be made:
164.Bd -literal -offset indent
165rcmd.a-host \(-> host/a-host.foo.com
166ftp.b-host \(-> ftp/b-host.bar.com
167pop.foo \(-> pop/foo.com
168ftp.other \(-> ftp/other.foo.com
169other.a-host \(-> other/a-host
170.Ed
171.Pp
172The first three are what you expect. If you remove the
173.Dq v4_domains ,
174the fourth entry will result in an error (since the host
175.Dq other
176can't be found). Even if
177.Dq a-host
178is a valid host name, the last entry will not be converted, since the
179.Dq other
180name is not known to represent a host-type principal.
181If you turn off
182.Dq v4_instance_resolve
183the 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
186valid 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
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
12Kerberos 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
22Converting between version 4 and version 5 principals can at best be
23described as a mess.
24.Pp
25A version 4 principal consists of a name, an instance, and a realm. A
26version 5 principal consists of one or more components, and a
27realm. In some cases also the first component/name will differ between
28version 4 and version 5. Furthermore the second component of a host
29principal will be the fully qualified domain name of the host in
30question, while the instance of a version 4 principal will only
31contain the first part (short hostname). Because of these problems
32the conversion between principals will have to be site customized.
33.Pp
34.Fn krb5_425_conv_principal_ext
35will try to convert a version 4 principal, given by
36.Fa name ,
37.Fa instance ,
38and
39.Fa realm ,
40to a version 5 principal. This can result in several possible
41principals, and if
42.Fa func
43is non-NULL, it will be called for each candidate principal.
44.Fa func
45should return true if the principal was
46.Dq good .
47To accomplish this,
48.Fn krb5_425_conv_principal_ext
49will look up the name in
50.Pa krb5.conf .
51It first looks in the
52.Li v4_name_convert/host
53subsection, which should contain a list of version 4 names whose
54instance should be treated as a hostname. This list can be specified
55for each realm (in the
56.Li realms
57section), or in the
58.Li libdefaults
59section. If the name is found the resulting name of the principal
60will be the value of this binding. The instance is then first looked
61up in
62.Li v4_instance_convert
63for the specified realm. If found the resulting value will be used as
64instance (this can be used for special cases), no further attempts
65will be made to find a conversion if this fails (with
66.Fa func ) .
67If the
68.Fa resolve
69parameter is true, the instance will be looked up with
70.Fn gethostbyname .
71This can be a time consuming, error prone, and unsafe operation. Next
72a list of hostnames will be created from the instance and the
73.Li v4_domains
74variable, which should contain a list of possible domains for the
75specific realm.
76.Pp
77On the other hand, if the name is not found in a
78.Li host
79section, it is looked up in a
80.Li v4_name_convert/plain
81binding. If found here the name will be converted, but the instance
82will be untouched.
83.Pp
84This list of default host-type conversions is compiled-in:
85.Bd -literal -offset indent
86v4_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
98It will only be used if there isn't an entry for these names in the
99config file, so you can override these defaults.
100.Pp
101.Fn krb5_425_conv_principal
102will call
103.Fn krb5_425_conv_principal_ext
104with
105.Dv NULL
106as
107.Fa func ,
108and the value of
109.Li v4_instance_resolve
110(from the
111.Li libdefaults
112section) as
113.Fa resolve .
114.Pp
115.Fn krb5_524_conv_principal
116basically does the opposite of
117.Fn krb5_425_conv_principal ,
118it just doesn't have to look up any names, but will instead truncate
119instances found to belong to a host principal. The
120.Fa name ,
121.Fa instance ,
122and
123.Fa realm
124should be at least 40 characters long.
125.Sh EXAMPLES
126Since this is confusing an example is in place.
127.Pp
128Assume that we have the
129.Dq foo.com ,
130and
131.Dq bar.com
132domains that have shared a single version 4 realm, FOO.COM. The version 4
133.Pa krb.realms
134file looked like:
135.Bd -literal -offset indent
136foo.com FOO.COM
137\&.foo.com FOO.COM
138\&.bar.com FOO.COM
139.Ed
140.Pp
141A
142.Pa krb5.conf
143file 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
157With this setup and the following host table:
158.Bd -literal -offset indent
159foo.com
160a-host.foo.com
161b-host.bar.com
162.Ed
163the following conversions will be made:
164.Bd -literal -offset indent
165rcmd.a-host \(-> host/a-host.foo.com
166ftp.b-host \(-> ftp/b-host.bar.com
167pop.foo \(-> pop/foo.com
168ftp.other \(-> ftp/other.foo.com
169other.a-host \(-> other/a-host
170.Ed
171.Pp
172The first three are what you expect. If you remove the
173.Dq v4_domains ,
174the fourth entry will result in an error (since the host
175.Dq other
176can't be found). Even if
177.Dq a-host
178is a valid host name, the last entry will not be converted, since the
179.Dq other
180name is not known to represent a host-type principal.
181If you turn off
182.Dq v4_instance_resolve
183the 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
186valid 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