1 files changed, 198 insertions, 0 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_425_conv_principal.3 b/crypto/heimdal/lib/krb5/krb5_425_conv_principal.3
new file mode 100644
index 0000000..231c3ff
--- /dev/null
+++ b/crypto/heimdal/lib/krb5/krb5_425_conv_principal.3
@@ -0,0 +1,198 @@
+.\" Copyright (c) 1997 Kungliga Tekniska Högskolan
+.\" $Id: krb5_425_conv_principal.3,v 1.3 1999/04/11 01:47:22 joda Exp $
+.Dd April 11, 1999
+.Dt KRB5_425_CONV_PRINCIPAL 3
+.Os HEIMDAL
+.Sh NAME
+.Nm krb5_425_conv_principal ,
+.Nm krb5_425_conv_principal_ext ,
+.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 *principal"
+
+.Ft krb5_error_code
+.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"
+
+.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_ext
+will try to convert a version 4 principal, given by
+.Fa name ,
+.Fa instance ,
+and
+.Fa realm ,
+to a version 5 principal. This can result in several possible
+principals, and if
+.Fa func
+is non-NULL, it will be called for each candidate principal.
+.Fa func
+should return true if the principal was
+.Dq good .
+To accomplish this, 
+.Fn krb5_425_conv_principal_ext 
+will look up the name in
+.Pa krb5.conf .
+It first looks in the 
+.Li v4_name_convert/host
+subsection, 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 resulting name of the principal
+will be the 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), no further attempts
+will be made to find a conversion if this fails (with
+.Fa func ) .
+If the
+.Fa resolve
+parameter is true, the instance will be looked up with
+.Fn gethostbyname .
+This can be a time consuming, error prone, and unsafe operation.  Next
+a list of hostnames will be created from the instance and the
+.Li v4_domains
+variable, which should contain a list of possible domains for the
+specific realm.
+.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
+This list of default host-type conversions is compiled-in:
+.Bd -literal -offset indent
+v4_name_convert = {
+	host = {
+		ftp = ftp
+		hprop = hprop
+		pop = pop
+		rcmd = host
+	}
+}
+.Ed
+.Pp
+It will only be used if there isn't an entry for these names in the
+config file, so you can override these defaults.
+.Pp
+.Fn krb5_425_conv_principal
+will call
+.Fn krb5_425_conv_principal_ext
+with 
+.Dv NULL
+as 
+.Fa func ,
+and the value of
+.Li v4_instance_resolve
+(from the
+.Li libdefaults
+section) as
+.Fa resolve .
+.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_instance_resolve = yes
+[realms]
+	FOO.COM = {
+		kdc = kerberos.foo.com
+		v4_instance_convert = {
+			foo = foo.com
+		}
+		v4_domains = 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 v4_domains ,
+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 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