1.\" Copyright (c) 1997 Kungliga Tekniska H�gskolan 2.\" $Id: krb5_425_conv_principal.3,v 1.4 2001/01/26 22:43:21 assar 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 SYNOPSIS 12.Fd #include <krb5.h> 13.Ft krb5_error_code 14.Fn krb5_425_conv_principal "krb5_context context" "const char *name" "const char *instance" "const char *realm" "krb5_principal *principal" 15.Ft krb5_error_code 16.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" 17.Ft krb5_error_code 18.Fn krb5_524_conv_principal "krb5_context context" "const krb5_principal principal" "char *name" "char *instance" "char *realm" 19.Sh DESCRIPTION 20Converting between version 4 and version 5 principals can at best be 21described as a mess. 22.Pp 23A version 4 principal consists of a name, an instance, and a realm. A 24version 5 principal consists of one or more components, and a 25realm. In some cases also the first component/name will differ between 26version 4 and version 5. Furthermore the second component of a host 27principal will be the fully qualified domain name of the host in 28question, while the instance of a version 4 principal will only 29contain the first component. Because of these problems the conversion 30between principals will have to be site customized. 31.Pp 32.Fn krb5_425_conv_principal_ext 33will try to convert a version 4 principal, given by 34.Fa name , 35.Fa instance , 36and 37.Fa realm , 38to a version 5 principal. This can result in several possible 39principals, and if 40.Fa func 41is non-NULL, it will be called for each candidate principal. 42.Fa func 43should return true if the principal was 44.Dq good . 45To accomplish this, 46.Fn krb5_425_conv_principal_ext 47will look up the name in 48.Pa krb5.conf . 49It first looks in the 50.Li v4_name_convert/host 51subsection, which should contain a list of version 4 names whose 52instance should be treated as a hostname. This list can be specified 53for each realm (in the 54.Li realms 55section), or in the 56.Li libdefaults 57section. If the name is found the resulting name of the principal 58will be the value of this binding. The instance is then first looked 59up in 60.Li v4_instance_convert 61for the specified realm. If found the resulting value will be used as 62instance (this can be used for special cases), no further attempts 63will be made to find a conversion if this fails (with 64.Fa func ) . 65If the 66.Fa resolve 67parameter is true, the instance will be looked up with 68.Fn gethostbyname . 69This can be a time consuming, error prone, and unsafe operation. Next 70a list of hostnames will be created from the instance and the 71.Li v4_domains 72variable, which should contain a list of possible domains for the 73specific realm. 74.Pp 75On the other hand, if the name is not found in a 76.Li host 77section, it is looked up in a 78.Li v4_name_convert/plain 79binding. If found here the name will be converted, but the instance 80will be untouched. 81.Pp 82This list of default host-type conversions is compiled-in: 83.Bd -literal -offset indent 84v4_name_convert = { 85 host = { 86 ftp = ftp 87 hprop = hprop 88 pop = pop 89 rcmd = host 90 } 91} 92.Ed 93.Pp 94It will only be used if there isn't an entry for these names in the 95config file, so you can override these defaults. 96.Pp 97.Fn krb5_425_conv_principal 98will call 99.Fn krb5_425_conv_principal_ext 100with 101.Dv NULL 102as 103.Fa func , 104and the value of 105.Li v4_instance_resolve 106(from the 107.Li libdefaults 108section) as 109.Fa resolve . 110.Pp 111.Fn krb5_524_conv_principal 112basically does the opposite of 113.Fn krb5_425_conv_principal , 114it just doesn't have to look up any names, but will instead truncate 115instances found to belong to a host principal. The 116.Fa name , 117.Fa instance , 118and 119.Fa realm 120should be at least 40 characters long. 121.Sh EXAMPLES 122Since this is confusing an example is in place. 123.Pp 124Assume that we have the 125.Dq foo.com , 126and 127.Dq bar.com 128domains that have shared a single version 4 realm, FOO.COM. The version 4 129.Pa krb.realms 130file looked like: 131.Bd -literal -offset indent 132foo.com FOO.COM 133\&.foo.com FOO.COM 134\&.bar.com FOO.COM 135.Ed 136.Pp 137A 138.Pa krb5.conf 139file that covers this case might look like: 140.Bd -literal -offset indent 141[libdefaults] 142 v4_instance_resolve = yes 143[realms] 144 FOO.COM = { 145 kdc = kerberos.foo.com 146 v4_instance_convert = { 147 foo = foo.com 148 } 149 v4_domains = foo.com 150 } 151.Ed 152.Pp 153With this setup and the following host table: 154.Bd -literal -offset indent 155foo.com 156a-host.foo.com 157b-host.bar.com 158.Ed 159the following conversions will be made: 160.Bd -literal -offset indent 161rcmd.a-host \(-> host/a-host.foo.com 162ftp.b-host \(-> ftp/b-host.bar.com 163pop.foo \(-> pop/foo.com 164ftp.other \(-> ftp/other.foo.com 165other.a-host \(-> other/a-host 166.Ed 167.Pp 168The first three are what you expect. If you remove the 169.Dq v4_domains , 170the fourth entry will result in an error (since the host 171.Dq other 172can't be found). Even if 173.Dq a-host 174is a valid host name, the last entry will not be converted, since the 175.Dq other 176name is not known to represent a host-type principal. 177If you turn off 178.Dq v4_instance_resolve 179the second example will result in 180.Dq ftp/b-host.foo.com 181(because of the default domain). And all of this is of course only 182valid if you have working name resolving. 183.Sh SEE ALSO 184.Xr krb5_build_principal 3 , 185.Xr krb5_free_principal 3 , 186.Xr krb5_parse_name 3 , 187.Xr krb5_sname_to_principal 3 , 188.Xr krb5_unparse_name 3 , 189.Xr krb5.conf 5 190