appl/dceutils/README.original

   1 KERBEROS and DCE INTEROPERABILITY ROUTINES
   2
   3 WHAT'S NEW
   4
   5 When k5dcecon was examining the ticket caches looking to
   6 update one with a newer TGT, it might update the wrong
   7 one for the correct user.  This problem was reported by PNNL,
   8 and is now fixed.
   9
  10 Any Kerberized application can now use a forwarded TGT to establish a
  11 DCE context, or can use a previously established DCE context. This is
  12 both a functional improvement and a performance improvement.
  13
  14 BACKGROUND
  15
  16 The MIT Kerberos 5 Release 1.x and DCE 1.1 can interoperate in a
  17 number of ways. This is possible because:
  18
  19  o DCE used Kerberos 5 internally. Based on the MIT code as of beta 4
  20    or so, with additional changes.
  21
  22  o The DCE security server can act as a K5 KDC, as defined in RFC 1510
  23    and responds on port 88.
  24
  25  o On the clients, DCE and Kerberos use the same format for the ticket
  26    cache, and then can share it. The KRB5CCNAME environment variable points
  27    at the cache.
  28
  29  o On the clients, DCE and Kerberos use the same format for the srvtab
  30    file. DCE refers to is a /krb5/v5srvtab and Kerberos as
  31    /etc/krb5.keytab. They can be symlinked.
  32
  33  o MIT has added many options to the krb5.conf configuration file
  34    which allows newer features of Release 1.0 to be turned off to match
  35    the earlier version of Kerberos upon which DCE is based.
  36
  37  o DCE will accept a externally obtained Kerberos TGT in place of a
  38    password when establishing a DCE context.
  39
  40 There are some areas where they differ, including the following:
  41
  42  o Administration of the database and the keytab files is done by the
  43    DCE routines, rather the the Kerberos kadmin.
  44
  45  o User password changes must be done using the DCE commands. Kpasswd
  46    does not work. (But there are mods to Kerberos to use the v5passwd
  47    with DCE.
  48
  49  o DCE goes beyond authentication only, and provides authorization via
  50    the PAC, and the dce-ptgt tickets stored in the cache. Thus a
  51    Kerberos KDC can not act as a DCE security server.
  52
  53  o A DCE cell and Kerberos realm can cross-realm authenticate, but
  54    there can be no intermediate realms. (There are other problems
  55    in this area as well. But directly connected realms/cells do work.)
  56
  57  o You can't link a module with the DCE library and the Kerberos
  58    library. They have conflicting routines, static data and structures.
  59
  60 One of the main features of DCE is the Distributed File System
  61 DFS. Access to DFS requires authentication and authorization, and when
  62 one uses a Kerberized network utility such as telnet, a forwarded
  63 Kerberos ticket can be used to establish the DCE context to allow
  64 access to DFS.
  65
  66
  67 NEW TO THIS RELEASE
  68
  69 This release introduces sharing of a DCE context, and PAG, and allows
  70 any Kerberized application to establish or share the context. This is
  71 made possible by using an undocumented feature of DCE which is on at
  72 least the Transarc and IBM releases of DCE 1.1.
  73
  74 I am in the process of trying to get this contributed to the general
  75 DCE 1.2.2 release as a patch, so it could be included in other vendors
  76 products.  HP has expressed interest in doing this, as well as the
  77 OpenGroup if the modification is contributed. You can help by
  78 requesting Transarc and/or IBM to submit this modification to the
  79 OpenGroup and ask your vendor to adopt this modification.
  80
  81 The feature is a modification to the setpag() system call which will
  82 allow an authorized process to set the PAG to a specific value, and
  83 thus allow unrelated processes to share the same PAG.
  84
  85 This then allows the Kerberized daemons such as kshd, to exec a DCE
  86 module which established the DCE context. Kshd then sets the
  87 KRB5CCNAME environment variable and then issues the setpag() to use
  88 this context. This solves the linking problem. This is done via the
  89 k5dfspag.c routine.
  90
  91 The k5dfspag.c code is compiled with the lib/krb5/os routines and
  92 included in the libkrb5. A daemon calls krb5_dfs_pag after the
  93 krb5_kuserok has determined that the Kerberos principal and local
  94 userid pair are acceptable. This should be done early so as to give
  95 the daemon access to the home directory which may be located on DFS.
  96 If the .k5login file is used by krb5_kuserok it will need to be
  97 accessed by the daemon and will need special ACL handling.
  98
  99 The krb5_dfs_pag routine will exec the k5dcecon module to do all the
 100 real work. Upon return, if a PAG is obtained, krb5_dfs_pag with set
 101 the PAG for the current process to the returned PAG value. It will
 102 also set the KRB5CCNAME environment as well. Under DCE the PAG value
 103 is the nnnnnnn part of the name of the cache:
 104 FILE:/opt/dcelocal/var/security/creds/dcecred_nnnnnnnn.
 105
 106 The k5dcecon routine will attempt to use TGT which may have been
 107 forwarded, to convert it to a DCE context. If there is no TGT, an
 108 attempt will be made to join an existing PAG for the local userid, and
 109 Kerberos principal. If there are existing PAGs, and a forwarded TGT,
 110 k5dcecon will check the lifetime of the forwarded TGT, and if it is
 111 less than the lifetime of the PAG, it will just join the PAG. If it
 112 is greater, it will refresh the PAG using the forwarded TGT.
 113 This approach has the advantage of not requiring many new tickets from
 114 having to be obtained, and allows one to refresh a DCE context, or use
 115 an already established context.
 116
 117 If the system also has AFS, the AFS krb5_afs_pag should be called
 118 after the krb5_dfs_pag, since cache pointed at via the KRB5CCNAME may
 119 have changed, such as if a DFS PAG has been joined. The AFS code does
 120 not have the capability to join an existing AFS PAG, but can use the
 121 same cache which might already had a
 122 afsx/<afs.cell.name>@<k5.realm.name> service ticket.
 123
 124
 125 WHAT'S IN THIS RELEASE
 126
 127 The k5prelogin, k5dcelogin, k5afslogin (with ak5log) were designed to
 128 be slipped in between telnetd or klogind and login.krb5. They would
 129 use a forwarded Kerberos ticket to establish a DCE context.  They are
 130 the older programs which are included here. They work on all DCE
 131 platforms, and don't take advantage of the undocumented setpag
 132 feature. (A version of k5dcelogin is being included with DCE 1.2.2)
 133
 134 K5dcecon is the new program which can be used to create, update or
 135 join a DCE context. k5dcecon returns KRB5CCNAME string which contains
 136 the PAG.
 137
 138 k5dfspag.c is to be built in the MIT Kerberos 5 release 1.0 patchlevel
 139 1 and added to the libkrb5. It will exec k5dcecon and upon return set
 140 the KRB5CCNAME and PAG. Mods to Kerberized klogind, rshd, telnetd,
 141 ftpd are available to use the k5dfspag.
 142
 143 Testpag.c is a test programs to see if the PAG can be set.
 144
 145 The cpwkey.c routine can be used to change a key in the DCE registry,
 146 by adding the key directly, or by setting the salt/pepper and password
 147 or by providing the key and the pepper. This could be useful when
 148 coping keys from a K4 or AFS database to DCE. It can also be used when
 149 setting a DCE to K5 cross-cell key.  This program is a test program
 150 For mass inserts, it should be rewritten to read from stdin.
 151
 152 K5dcelogin can also be called directly, much like dce_login.
 153 I use the following commands in effect do the same thing as dce_login
 154 and get a forwardable ticket, DCE context and an AFS token:
 155
 156   #!/bin/csh
 157   # simulate a dce_login using krb5 kinit and k5dcelogin
 158   #
 159   setenv KRB5CCNAME FILE:/tmp/krb5cc_p$$
 160   /krb5/bin/kinit -f
 161   exec /krb5/sbin/k5dcelogin /krb5/sbin/k5afslogin /bin/csh
 162   #exec /krb5/sbin/k5dcelogin  /bin/csh
 163
 164 This could be useful in a mixed cell where "AS_REQ" messages are
 165 handled by a K5 KDC, but DCE RPCs are handled by the DCE security
 166 server.
 167
 168 TESTING THE SETPAG
 169
 170 The krb5_dfs_pag routine relies on an undocumented feature which is
 171 in the AIX and Transarc Solaris ports of DCE and has been recently
 172 added to the SGI version.  To test if this feature is present
 173 on some other DFS implementation use the testpag routine.
 174
 175 The testpag routine attempts to set a PAG value to one you supply. It
 176 uses the afs_syscall with the afs_setpag, and passes the supplied
 177 PAG value as the next parameter. On an unmodifed system, this
 178 will be ignored, and a new will be set. You should also check that
 179 if run as a user, you cannot join a PAG owned by another user.
 180 When run as root, any PAG should be usable.
 181
 182 On a machine with DFS running, do a dce_login to get a DCE context and
 183 PAG. ECHO the KRB5CCNAME and look at the nnnnnnnn at the end. It
 184 should look like an 8 char hex value, which may be 41ffxxxx on some
 185 systems.
 186
 187 Su to root and unsetenv KRB5CCNAME. Do a testpag -n nnnnnnnn where
 188 nnnnnnnn is the PAG obtained for the above name.
 189
 190 It should look like this example on an AIX 4.1.4 system:
 191
 192    pembroke# ./testpag -n 63dc9997
 193    calling k5dcepag newpag=63dc9997
 194    PAG returned = 63dc9997
 195
 196 You will be running under a new shell with the PAG and KRB5CCNAME set.
 197 If the PAG returned is the same as the newpag, then it worked. You can
 198 further verify this by doing a DCE klist, cd to DFS and a DCE klist
 199 again. The klist should show some tickets for DFS servers.
 200
 201 If the PAG returned is not the same, and repeated attempts show a
 202 returned PAG decremented by 1 from the previous returned PAG, then
 203 this system does not have the modification For example:
 204
 205    # ./testpag -n 41fffff9
 206    calling k5dcepag newpag=41fffff9
 207    PAG returned = 41fffff8
 208    # ./testpag -n 41fffff9
 209    calling k5dcepag newpag=41fffff9
 210    PAG returned = 41fffff7
 211
 212 In this case the syscall is ignoring the newpag parameter.
 213
 214 Running it with -n 0 should get the next PAG value with or without
 215 this modification.
 216
 217 If the DFS kernel extensions are not installed, you would get
 218 something like this:
 219
 220   caliban.ctd.anl.gov% ./testpag -n 012345678
 221   calling k5dcepag newpag=012345678
 222   Setpag failed with a system error
 223   PAG returned = ffffffff
 224   Not a good pag value
 225
 226 If you DFS implementation does not have this modification, you could
 227 attempt to install it yourself. But this requires source and requires
 228 modifications to the kernel extensions. At the end of this note is an
 229 untested sample using the DCE 1.2.2 source code. You can also contact
 230 your system vendor and ask for this modification.
 231
 232 UNICOS has a similar function setppag(newpag) which can be used to set
 233 the PAG of the parent. Contact me if you are interested.
 234
 235 HOW TO INSTALL
 236
 237 Examine the k5dfspag.c file to make sure the DFS syscalls are correct
 238 for your platform. See the /opt/dcelocal/share/include/dcedfs/syscall.h
 239 on Solaris for example.
 240
 241 You should build the testpag routine and make sure it works before
 242 adding all the other mods. If it fails you can still use the klogind
 243 and telnetd with the k5prelogin and k5dcelogin code.
 244
 245 If you intend to install with a prefix other than /krb5, change:
 246 DPAGAIX and K5DCECON in k5dfspag.c; the three references in
 247 k5prelogin.c; and the DESTDIR in the Makefile.
 248
 249 Get k5101.cdiff.xxxxxx.tar file and install the mods for ANL_DFS_PAG
 250 and ANL_DCE to the MIT Kerberos 5 source. These mods turn on some DCE
 251 related changes and the calls to krb5_dfs_pag.
 252
 253 Symlink or copy the k5dfspag.c to the src/lib/krb5/os directory.
 254
 255 Add the -DANL_DFS_PAG and -DANL_DCE flags to the configuration.
 256
 257 Configure and Build the Kerberos v5.
 258
 259 Modify the k5dce Makefile for your system.
 260
 261 Build the k5dcecon and related programs.
 262
 263 Install both the MIT Kerberos v5 and the k5dcecon and dpagaix if AIX.
 264
 265 The makefile can also build k5dcelogin and k5prelogin.  The install
 266 can install k5dcelogin, k5prelogin and update the links for login.krb5
 267 -> k5prelogin and moving login.krb5 to login.k5. If you will be using
 268 the k5dcecon/k5dfspag with the Kerberos mods, you don't need
 269 k5prelogin, or the links changed, and may not need k5dcelogin.
 270
 271 Note that Transarc has obfuscated the entries to the lib, and
 272 the 1.0.3a is different from the 1.1. You may need to build two
 273 versions of the k5dcelogin and/or k5dcecon one for each.
 274
 275 AIX ONLY
 276
 277 The dpagaix routine is needed for AIX because of the way they do the
 278 syscalls.
 279
 280 The following fix.aix.libdce.mk is not needed if dce 2.1.0.21
 281 has been installed. This PTF exposed the needed entrypoints.
 282
 283 The fix.aix.libdce.mk is a Makefile for AIX 4.x to add the required
 284 external entry points to the libdce.a.  These are needed by k5dcecon
 285 and k5dcelogin.  A bug report was submitted to IBM on this, and it was
 286 rejected. But since DCE 1.2.2 will have a k5dcelogin, this should not
 287 be needed with 1.2.2
 288
 289 Copy /usr/lib/libdce.a to /usr/libdce.a.orig before starting. Copy the
 290 makefile to its own directory. It will create a new libdce.a which you
 291 need to copy back to /usr/lib/libdce.a You will need to reboot the
 292 machine.  See the /usr/lpp/dce/examples/inst/README.AIX for a similar
 293 procedure.  IBM was not responsive in a request to have these added.
 294
 295 UNTESTED KERNEL EXTENSION FOR SETPAG
 296
 297 *** src/file/osi/,osi_pag.c  Wed Oct  2 13:03:05 1996
 298 --- src/file/osi/osi_pag.c   Mon Jul 28 13:53:13 1997
 299 ***************
 300 *** 293,298 ****
 301 --- 293,302 ----
 302       int code;
 303
 304       osi_MakePreemptionRight();
 305 +    /* allow sharing of a PAG by non child processes DEE- 6/6/97 */
 306 +    if (unused && osi_GetUID(osi_getucred()) == 0) {
 307 +     newpag = unused;
 308 +    } else {
 309       osi_mutex_enter(&osi_pagLock);
 310       now = osi_Time();
 311       soonest = osi_firstPagTime +
 312 ***************
 313 *** 309,314 ****
 314 --- 313,319 ----
 315       }
 316       osi_mutex_exit(&osi_pagLock);
 317       newpag = osi_genpag();
 318 +    }
 319       osi_pcred_lock(p);
 320       credp = crcopy(osi_getucred());
 321       code = osi_SetPagInCred(credp, newpag);
 322
 323 Created     07/08/96
 324 Modified    09/30/96
 325 Modified    11/19/96
 326 Modified    12/19/96
 327 Modified    06/20/97
 328 Modified    07/28/97
 329 Modified    02/18/98
 330
 331  Douglas E. Engert  <DEEngert@anl.gov>
 332  Argonne National Laboratory
 333  9700 South Cass Avenue
 334  Argonne, Illinois  60439
 335  (630) 252-5444