crypto/heimdal-0.6.3/lib/krb5/krb5_425_conv_principal.cat3

   1
   2 KRB5_425_CONV_PRINCIPAL(3) UNIX Programmer's Manual KRB5_425_CONV_PRINCIPAL(3)
   3
   4 N\bNA\bAM\bME\bE
   5      k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl, k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl_\b_e\bex\bxt\bt,
   6      k\bkr\brb\bb5\b5_\b_5\b52\b24\b4_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl - converts to and from version 4 principals
   7
   8 L\bLI\bIB\bBR\bRA\bAR\bRY\bY
   9      Kerberos 5 Library (libkrb5, -lkrb5)
  10
  11 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
  12      _\bk_\br_\bb_\b5_\b__\be_\br_\br_\bo_\br_\b__\bc_\bo_\bd_\be
  13      k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl(_\bk_\br_\bb_\b5_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt _\bc_\bo_\bn_\bt_\be_\bx_\bt, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be,
  14              _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\ba_\bl_\bm,
  15              _\bk_\br_\bb_\b5_\b__\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl _\b*_\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl)
  16
  17      _\bk_\br_\bb_\b5_\b__\be_\br_\br_\bo_\br_\b__\bc_\bo_\bd_\be
  18      k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl_\b_e\bex\bxt\bt(_\bk_\br_\bb_\b5_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt _\bc_\bo_\bn_\bt_\be_\bx_\bt, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be,
  19              _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\br_\be_\ba_\bl_\bm,
  20              _\bk_\br_\bb_\b5_\b__\bb_\bo_\bo_\bl_\be_\ba_\bn _\b(_\b*_\bf_\bu_\bn_\bc_\b)_\b(_\bk_\br_\bb_\b5_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt_\b, _\bk_\br_\bb_\b5_\b__\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl_\b),
  21              _\bk_\br_\bb_\b5_\b__\bb_\bo_\bo_\bl_\be_\ba_\bn _\br_\be_\bs_\bo_\bl_\bv_\be, _\bk_\br_\bb_\b5_\b__\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl _\b*_\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl)
  22
  23      _\bk_\br_\bb_\b5_\b__\be_\br_\br_\bo_\br_\b__\bc_\bo_\bd_\be
  24      k\bkr\brb\bb5\b5_\b_5\b52\b24\b4_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl(_\bk_\br_\bb_\b5_\b__\bc_\bo_\bn_\bt_\be_\bx_\bt _\bc_\bo_\bn_\bt_\be_\bx_\bt,
  25              _\bc_\bo_\bn_\bs_\bt _\bk_\br_\bb_\b5_\b__\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl _\bp_\br_\bi_\bn_\bc_\bi_\bp_\ba_\bl, _\bc_\bh_\ba_\br _\b*_\bn_\ba_\bm_\be, _\bc_\bh_\ba_\br _\b*_\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be,
  26              _\bc_\bh_\ba_\br _\b*_\br_\be_\ba_\bl_\bm)
  27
  28 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  29      Converting between version 4 and version 5 principals can at best be de-
  30      scribed as a mess.
  31
  32      A version 4 principal consists of a name, an instance, and a realm. A
  33      version 5 principal consists of one or more components, and a realm. In
  34      some cases also the first component/name will differ between version 4
  35      and version 5.  Furthermore the second component of a host principal will
  36      be the fully qualified domain name of the host in question, while the in-
  37      stance of a version 4 principal will only contain the first part (short
  38      hostname).  Because of these problems the conversion between principals
  39      will have to be site customized.
  40
  41      k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl_\b_e\bex\bxt\bt() will try to convert a version 4 principal,
  42      given by _\bn_\ba_\bm_\be, _\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be, and _\br_\be_\ba_\bl_\bm, to a version 5 principal. This can
  43      result in several possible principals, and if _\bf_\bu_\bn_\bc is non-NULL, it will
  44      be called for each candidate principal.  _\bf_\bu_\bn_\bc should return true if the
  45      principal was ``good''. To accomplish this, k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl_\b_e\bex\bxt\bt()
  46      will look up the name in _\bk_\br_\bb_\b5_\b._\bc_\bo_\bn_\bf. It first looks in the
  47      v4_name_convert/host subsection, which should contain a list of version 4
  48      names whose instance should be treated as a hostname. This list can be
  49      specified for each realm (in the realms section), or in the libdefaults
  50      section.  If the name is found the resulting name of the principal will
  51      be the value of this binding. The instance is then first looked up in
  52      v4_instance_convert for the specified realm. If found the resulting value
  53      will be used as instance (this can be used for special cases), no further
  54      attempts will be made to find a conversion if this fails (with _\bf_\bu_\bn_\bc). If
  55      the _\br_\be_\bs_\bo_\bl_\bv_\be parameter is true, the instance will be looked up with
  56      g\bge\bet\bth\bho\bos\bst\btb\bby\byn\bna\bam\bme\be().  This can be a time consuming, error prone, and unsafe
  57      operation.  Next a list of hostnames will be created from the instance
  58      and the v4_domains variable, which should contain a list of possible do-
  59      mains for the specific realm.
  60
  61      On the other hand, if the name is not found in a host section, it is
  62      looked up in a v4_name_convert/plain binding. If found here the name will
  63      be converted, but the instance will be untouched.
  64
  65
  66      This list of default host-type conversions is compiled-in:
  67
  68            v4_name_convert = {
  69                    host = {
  70                            ftp = ftp
  71                            hprop = hprop
  72                            imap = imap
  73                            pop = pop
  74                            rcmd = host
  75                            smtp = smtp
  76                    }
  77            }
  78
  79      It will only be used if there isn't an entry for these names in the con-
  80      fig file, so you can override these defaults.
  81
  82      k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl() will call k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl_\b_e\bex\bxt\bt() with
  83      NULL as _\bf_\bu_\bn_\bc, and the value of v4_instance_resolve (from the libdefaults
  84      section) as _\br_\be_\bs_\bo_\bl_\bv_\be.
  85
  86      k\bkr\brb\bb5\b5_\b_5\b52\b24\b4_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl() basically does the opposite of
  87      k\bkr\brb\bb5\b5_\b_4\b42\b25\b5_\b_c\bco\bon\bnv\bv_\b_p\bpr\bri\bin\bnc\bci\bip\bpa\bal\bl(), it just doesn't have to look up any names, but
  88      will instead truncate instances found to belong to a host principal. The
  89      _\bn_\ba_\bm_\be, _\bi_\bn_\bs_\bt_\ba_\bn_\bc_\be, and _\br_\be_\ba_\bl_\bm should be at least 40 characters long.
  90
  91 E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
  92      Since this is confusing an example is in place.
  93
  94      Assume that we have the ``foo.com'', and ``bar.com'' domains that have
  95      shared a single version 4 realm, FOO.COM. The version 4 _\bk_\br_\bb_\b._\br_\be_\ba_\bl_\bm_\bs file
  96      looked like:
  97
  98            foo.com         FOO.COM
  99            .foo.com        FOO.COM
 100            .bar.com        FOO.COM
 101
 102      A _\bk_\br_\bb_\b5_\b._\bc_\bo_\bn_\bf file that covers this case might look like:
 103
 104            [libdefaults]
 105                    v4_instance_resolve = yes
 106            [realms]
 107                    FOO.COM = {
 108                            kdc = kerberos.foo.com
 109                            v4_instance_convert = {
 110                                    foo = foo.com
 111                            }
 112                            v4_domains = foo.com
 113                    }
 114
 115      With this setup and the following host table:
 116
 117            foo.com
 118            a-host.foo.com
 119            b-host.bar.com
 120      the following conversions will be made:
 121
 122            rcmd.a-host     -> host/a-host.foo.com
 123            ftp.b-host      -> ftp/b-host.bar.com
 124            pop.foo         -> pop/foo.com
 125            ftp.other       -> ftp/other.foo.com
 126            other.a-host    -> other/a-host
 127
 128      The first three are what you expect. If you remove the ``v4_domains'',
 129      the fourth entry will result in an error (since the host ``other'' can't
 130      be found). Even if ``a-host'' is a valid host name, the last entry will
 131      not be converted, since the ``other'' name is not known to represent a
 132      host-type principal.  If you turn off ``v4_instance_resolve'' the second
 133      example will result in ``ftp/b-host.foo.com'' (because of the default do-
 134      main). And all of this is of course only valid if you have working name
 135      resolving.
 136
 137 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 138      krb5_build_principal(3),  krb5_free_principal(3),  krb5_parse_name(3),
 139      krb5_sname_to_principal(3),  krb5_unparse_name(3),  krb5.conf(5)
 140
 141  HEIMDAL                        April 11, 1999                               3