c50c15a4a5
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@2967 ec53bebd-3082-4978-b11e-865c3cabbd6b
167 lines
4.6 KiB
Groff
167 lines
4.6 KiB
Groff
.\" Copyright (c) 1997 Kungliga Tekniska Högskolan
|
|
.\" $Id$
|
|
.Dd August 8, 1997
|
|
.Dt KRB5_425_CONV_PRINCIPAL 3
|
|
.Os HEIMDAL
|
|
.Sh NAME
|
|
.Nm krb5_425_conv_principal ,
|
|
.Nm krb5_524_conv_principal
|
|
.Nd Converts to and from version 4 principals
|
|
|
|
.Sh SYNOPSIS
|
|
.Fd #include <krb5.h>
|
|
|
|
.Ft krb5_error_code
|
|
.Fn krb5_425_conv_principal "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_principal *princ"
|
|
|
|
.Ft krb5_error_code
|
|
.Fn krb5_524_conv_principal "krb5_context context" "const krb5_principal principal" "char *name" "char *instance" "char *realm"
|
|
|
|
.Sh DESCRIPTION
|
|
|
|
Converting between version 4 and version 5 principals can at best be
|
|
described as a mess.
|
|
.Pp
|
|
A version 4 principal consists of a name, an instance, and a realm. A
|
|
version 5 principal consists of one or more components, and a
|
|
realm. In some cases also the first component/name will differ between
|
|
version 4 and version 5. Furthermore the second component of a host
|
|
principal will be the fully qualified domain name of the host in
|
|
question, while the instance of a version 4 principal will only
|
|
contain the first component. Because of these problems the conversion
|
|
between principals will have to be site customized.
|
|
.Pp
|
|
.Fn krb5_425_conv_principal
|
|
will try to convert a version 4 principal, given by
|
|
.Fa name ,
|
|
.Fa instance ,
|
|
and
|
|
.Fa realm ,
|
|
to a version 5 principal. To do this it will look up the name in
|
|
.Pa krb5.conf .
|
|
It first looks in the
|
|
.Li v4_name_convert/host
|
|
binding, which should contain a list of version 4 names whose instance
|
|
should be treated as a hostname. This list can be specified for each
|
|
realm (in the
|
|
.Li realms
|
|
section), or in the
|
|
.Li libdefaults
|
|
section. If the name is found the first component of the principal
|
|
will be value of this binding. The instance is then first looked up in
|
|
.Li v4_instance_convert
|
|
for the specified realm. If found the resulting value will be used as
|
|
instance (this can be used for special cases). If not found you can
|
|
optionally have the instance looked up (with
|
|
.Fn gethostbyname ) .
|
|
This is a time consuming, error prone, and unsafe operation, and it is
|
|
not turned on by default. You can turn on this feature by setting
|
|
.Li v4_instance_resolve
|
|
to true in the
|
|
.Li libdefaults
|
|
section. As a final fallback you can, for each realm, include a
|
|
.Li default_realm
|
|
that will be appended to the instance without further checks.
|
|
.Pp
|
|
On the other hand, if the name is not found in a
|
|
.Li host
|
|
section, it is looked up in a
|
|
.Li v4_name_convert/plain
|
|
binding. If found here the name will be converted, but the instance
|
|
will be untouched.
|
|
.Pp
|
|
.Fn krb5_524_conv_principal
|
|
basically does the opposite of
|
|
.Fn krb5_425_conv_principal ,
|
|
it just doesn't have to look up any names, but will instead truncate
|
|
instances found to belong to a host principal. The
|
|
.Fa name ,
|
|
.Fa instance ,
|
|
and
|
|
.Fa realm
|
|
should be at least 40 characters long.
|
|
|
|
.Sh EXAMPLES
|
|
|
|
Since this is confusing an example is in place.
|
|
.Pp
|
|
Assume that we have the
|
|
.Dq foo.com ,
|
|
and
|
|
.Dq bar.com
|
|
domains that have shared a single version 4 realm, FOO.COM. The version 4
|
|
.Pa krb.realms
|
|
file looked like:
|
|
.Bd -literal -offset indent
|
|
foo.com FOO.COM
|
|
\&.foo.com FOO.COM
|
|
\&.bar.com FOO.COM
|
|
.Ed
|
|
.Pp
|
|
A
|
|
.Pa krb5.conf
|
|
file that covers this case might look like:
|
|
.Bd -literal -offset indent
|
|
[libdefaults]
|
|
v4_name_convert = {
|
|
host = {
|
|
rcmd = host
|
|
ftp = ftp
|
|
pop = pop
|
|
}
|
|
}
|
|
v4_instance_resolve = yes
|
|
[realms]
|
|
FOO.COM = {
|
|
kdc = kerberos.foo.com
|
|
v4_instance_convert = {
|
|
foo = foo.com
|
|
}
|
|
default_domain = foo.com
|
|
}
|
|
.Ed
|
|
.Pp
|
|
With this setup and the following host table:
|
|
.Bd -literal -offset indent
|
|
foo.com
|
|
a-host.foo.com
|
|
b-host.bar.com
|
|
.Ed
|
|
the following conversions will be made:
|
|
.Bd -literal -offset indent
|
|
rcmd.a-host \(-> host/a-host.foo.com
|
|
ftp.b-host \(-> ftp/b-host.bar.com
|
|
pop.foo \(-> pop/foo.com
|
|
ftp.other \(-> ftp/other.foo.com
|
|
other.a-host \(-> other/a-host
|
|
.Ed
|
|
.Pp
|
|
The first three are what you expect. If you remove the
|
|
.Dq default_domain ,
|
|
the fourth entry will result in an error (since the host
|
|
.Dq other
|
|
can't be found). Even if
|
|
.Dq a-host
|
|
is a valid host name, the last entry will not be converted, since the
|
|
.Dq other
|
|
name is not known to represent a host-type principal.
|
|
If you turn off
|
|
.Dq v4_instance_resolve
|
|
the second example will result in
|
|
.Dq ftp/b-host.foo.com
|
|
(because of the default domain). And all of this is of course only
|
|
valid if you have working name resolving.
|
|
|
|
.Sh BUGS
|
|
You have to set up your
|
|
.Pa krb5.conf
|
|
correctly to have any of this work.
|
|
|
|
.Sh SEE ALSO
|
|
.Xr krb5_build_principal 3 ,
|
|
.Xr krb5_free_principal 3 ,
|
|
.Xr krb5_parse_name 3 ,
|
|
.Xr krb5_sname_to_principal 3 ,
|
|
.Xr krb5_unparse_name 3 ,
|
|
.Xr krb5.conf 5
|