src/krb524/README

   1 Copyright 1994 by OpenVision Technologies, Inc.
   2
   3 Permission to use, copy, modify, distribute, and sell this software
   4 and its documentation for any purpose is hereby granted without fee,
   5 provided that the above copyright notice appears in all copies and
   6 that both that copyright notice and this permission notice appear in
   7 supporting documentation, and that the name of OpenVision not be used
   8 in advertising or publicity pertaining to distribution of the software
   9 without specific, written prior permission. OpenVision makes no
  10 representations about the suitability of this software for any
  11 purpose.  It is provided "as is" without express or implied warranty.
  12
  13 OPENVISION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  14 INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  15 EVENT SHALL OPENVISION BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  16 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  17 USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  18 OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  19 PERFORMANCE OF THIS SOFTWARE.
  20
  21
  22 Kerberos V5 to Kerberos V4 Credentials Converting Service, ALPHA RELEASE
  23 ========================================================================
  24
  25 krb524 is a service that converts Kerberos V5 credentials into
  26 Kerberos V4 credentials suitable for use with applications that for
  27 whatever reason do not use V5 directly.  The service consists of a
  28 server that has access to the secret key of the Kerberos service for
  29 which credentials will be converted, and a library for use by client
  30 programs that wish to use the server.
  31
  32 The protocol is simple.  Suppose that a client C wishes to obtain V4
  33 credentials for a V5 service S by using the krb524 server.  The
  34 notation {C,S}_n represents a Vn service ticket for S for use by C.
  35
  36 (1) C obtains V5 credentials, including a ticket {C,S}_5, for S by the
  37 normal V5 means.
  38
  39 (2) C transmits {C,S}_5 to KRB524.
  40
  41 (3) KRB524 converts {C,S}_5 into {C,S}_4.
  42
  43 (4) KRB524 transmits {C,S}_4 to C.
  44
  45 (5) C creates a V4 credentials strucuture from the plaintext
  46 information in the V5 credential and {C,S}_4.
  47
  48 Steps (2) through (4) are encapsulated in a single function call in
  49 the krb524 library.
  50
  51 An alternate conversion is provided for AFS servers that support the
  52 encrypted part of a krb5 ticket as an AFS token.  If the krb524d is
  53 converting a principal whose first component is afs and if the
  54 encrypted part of the ticket fits in 344 bytes, then it will default
  55 to simply returning the encrypted part of the ticket as a token.  If
  56 it turns out that the AFS server does not support the ticket, then
  57 users will get an unknown key version error and the krb524d must be
  58 configured to use v4 tickets for this AFS service.
  59
  60
  61 Obviously, not all V5 credentials can be completely converted to V4
  62 credentials, since the former is a superset of the latter.  The
  63 precise semantics of the conversion function are still undecided.
  64 UTSL.
  65
  66 Programs contained in this release
  67 ======================================================================
  68
  69 krb524d [-m[aster]] [-k[eytab]]
  70
  71 The krb524 server.  It accepts UDP requests on the krb524 service
  72 port, specified in /etc/services, or on port 4444 by default.  (A
  73 request for an official port assignment is underway.)  The -m argument
  74 causes krb524d to access the KDC master database directly; the -k
  75 argument causes krb524d to use the default keytab (and therefore only
  76 be able to convert tickets for services in the keytab).  Only one of
  77 -m or -k can be specified.
  78
  79 test -remote server client service
  80
  81 A test program that obtains a V5 credential for {client,service},
  82 converts it to a V4 credential, and prints out the entire contents of
  83 both versions.  It prompts for service's secret key, which it needs to
  84 decrypt both tickets in order to print them out.  Enter it as an eight
  85 digit ASCII hex number.
  86
  87 k524init [-n] [-p principal]
  88
  89 Convert a V5 credential into a V4 credential and store it in a V4
  90 ticket file.  The client is 'principal', or krbtgt at the V5 ccache's
  91 default principal's realm if not specified.  The -n argument causes
  92 the new ticket to be added to the existing ticket file; otherwise, the
  93 ticket file is initialized.
  94
  95 Configuring krb524d AFS Conversion
  96 ======================================================================
  97
  98 The krb524d looks in the appdefaults  section of krb5.conf for an
  99 application called afs_krb5 to determine whether  afs principals
 100 support encrypted ticket parts as tokens.  The following configuration
 101 fragment says that afs/sipb.mit.edu@ATHENA.MIT.EDU supports the new
 102 token format but afs@ATHENA.MIT.EDU and
 103 afs/athena.mit.edu@ATHENA.MIT.EDU do not.  Note that the default is to
 104 assume afs servers support the new format.
 105
 106 [appdefaults]
 107 afs_krb5 = {
 108         ATHENA.MIT.EDU = {
 109                 # This stanza describes principals in the
 110                 #ATHENA.MIT.EDU realm
 111                 afs = false
 112                 afs/athena.mit.edu = false
 113                 afs/sipb.mit.edu = true
 114         }
 115 }
 116
 117
 118 Using libkrb524.a
 119 ======================================================================
 120
 121 To use libkrb524.a, #include "krb524.h", link against libkrb524.a,
 122 call krb524_init_ets() at the beginning of your program, and call one
 123 of the following two functions:
 124
 125 int krb524_convert_creds_addr(krb5_creds *v5creds, CREDENTIALS *v4creds,
 126                          struct sockaddr *saddr)
 127
 128 int krb524_convert_creds_kdc(krb5_creds *v5creds, CREDENTIALS *v4creds)
 129
 130 Both convert the V5 credential in v5creds into a V4 credential in
 131 v4creds.  One assumes krb524d is running on the KDC, the other uses an
 132 explicit host.  You only need to specify the address for saddr; the
 133 port is filled in automatically.
 134
 135 Unresolved issues / Bugs
 136 ======================================================================
 137
 138 o krb524d requires access to the secret key of any service to be
 139 converted.  Should krb524d run on the KDC or on individual server
 140 machines?  The latter is more paranoid, since it prevents bugs in
 141 krb524d from provided unauthorized access to the master database.
 142 However, it also requires the client to provide the address of the
 143 server to be used.  The client will usually have this information
 144 (since presumably it will be sending the converted V4 credentials to
 145 the same server) but it may not be in a convenient form.  It seems
 146 "cleaner" to have krb524d run on the KDC.
 147
 148 o Even if krb524d uses keytabs on server machines, it needs to be more
 149 flexible.  You only want to run one krb524d per host, so it has to be
 150 able to scan multiple keytabs.  This might get logistically messy.
 151
 152 o This code is of alpha quality.  Bugs, omissions, memory leaks, and
 153 perhaps security holes still remain.  Do not use it (yet) in a
 154 production environment.