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