crypto/heimdal/doc/apps.texi

   1 @c $Id: apps.texi 22071 2007-11-14 20:04:50Z lha $
   2
   3 @node Applications, Things in search for a better place, Setting up a realm, Top
   4
   5 @chapter Applications
   6
   7 @menu
   8 * Authentication modules::
   9 * AFS::
  10 @end menu
  11
  12 @node  Authentication modules, AFS, Applications, Applications
  13 @section Authentication modules
  14
  15 The problem of having different authentication mechanisms has been
  16 recognised by several vendors, and several solutions have appeared. In
  17 most cases these solutions involve some kind of shared modules that are
  18 loaded at run-time.  Modules for some of these systems can be found in
  19 @file{lib/auth}.  Presently there are modules for Digital's SIA,
  20 and IRIX' @code{login} and @code{xdm} (in
  21 @file{lib/auth/afskauthlib}).
  22
  23 @menu
  24 * Digital SIA::
  25 * IRIX::
  26 @end menu
  27
  28 @node Digital SIA, IRIX, Authentication modules, Authentication modules
  29 @subsection Digital SIA
  30
  31 How to install the SIA module depends on which OS version you're
  32 running. Tru64 5.0 has a new command, @file{siacfg}, which makes this
  33 process quite simple. If you have this program, you should just be able
  34 to run:
  35 @example
  36 siacfg -a KRB5 /usr/athena/lib/libsia_krb5.so
  37 @end example
  38
  39 On older versions, or if you want to do it by hand, you have to do the
  40 following (not tested by us on Tru64 5.0):
  41
  42 @itemize @bullet
  43
  44 @item
  45 Make sure @file{libsia_krb5.so} is available in
  46 @file{/usr/athena/lib}. If @file{/usr/athena} is not on local disk, you
  47 might want to put it in @file{/usr/shlib} or someplace else. If you do,
  48 you'll have to edit @file{krb5_matrix.conf} to reflect the new location
  49 (you will also have to do this if you installed in some other directory
  50 than @file{/usr/athena}). If you built with shared libraries, you will
  51 have to copy the shared @file{libkrb.so}, @file{libdes.so},
  52 @file{libkadm.so}, and @file{libkafs.so} to a place where the loader can
  53 find them (such as @file{/usr/shlib}).
  54 @item
  55 Copy (your possibly edited) @file{krb5_matrix.conf} to @file{/etc/sia}.
  56 @item
  57 Apply @file{security.patch} to @file{/sbin/init.d/security}.
  58 @item
  59 Turn on KRB5 security by issuing @kbd{rcmgr set SECURITY KRB5} and
  60 @kbd{rcmgr set KRB5_MATRIX_CONF krb5_matrix.conf}.
  61 @item
  62 Digital thinks you should reboot your machine, but that really shouldn't
  63 be necessary.  It's usually sufficient just to run
  64 @kbd{/sbin/init.d/security start} (and restart any applications that use
  65 SIA, like @code{xdm}.)
  66 @end itemize
  67
  68 Users with local passwords (like @samp{root}) should be able to login
  69 safely.
  70
  71 When using Digital's xdm the @samp{KRB5CCNAME} environment variable isn't
  72 passed along as it should (since xdm zaps the environment). Instead you
  73 have to set @samp{KRB5CCNAME} to the correct value in
  74 @file{/usr/lib/X11/xdm/Xsession}. Add a line similar to
  75 @example
  76 KRB5CCNAME=FILE:/tmp/krb5cc`id -u`_`ps -o ppid= -p $$`; export KRB5CCNAME
  77 @end example
  78 If you use CDE, @code{dtlogin} allows you to specify which additional
  79 environment variables it should export. To add @samp{KRB5CCNAME} to this
  80 list, edit @file{/usr/dt/config/Xconfig}, and look for the definition of
  81 @samp{exportList}. You want to add something like:
  82 @example
  83 Dtlogin.exportList:     KRB5CCNAME
  84 @end example
  85
  86 @subsubheading Notes to users with Enhanced security
  87
  88 Digital's @samp{ENHANCED} (C2) security, and Kerberos solve two
  89 different problems. C2 deals with local security, adds better control of
  90 who can do what, auditing, and similar things. Kerberos deals with
  91 network security.
  92
  93 To make C2 security work with Kerberos you will have to do the
  94 following.
  95
  96 @itemize @bullet
  97 @item
  98 Replace all occurrences of @file{krb5_matrix.conf} with
  99 @file{krb5+c2_matrix.conf} in the directions above.
 100 @item
 101 You must enable ``vouching'' in the @samp{default} database.  This will
 102 make the OSFC2 module trust other SIA modules, so you can login without
 103 giving your C2 password. To do this use @samp{edauth} to edit the
 104 default entry @kbd{/usr/tcb/bin/edauth -dd default}, and add a
 105 @samp{d_accept_alternate_vouching} capability, if not already present.
 106 @item
 107 For each user who does @emph{not} have a local C2 password, you should
 108 set the password expiration field to zero. You can do this for each
 109 user, or in the @samp{default} table. To do this use @samp{edauth} to
 110 set (or change) the @samp{u_exp} capability to @samp{u_exp#0}.
 111 @item
 112 You also need to be aware that the shipped @file{login}, @file{rcp}, and
 113 @file{rshd}, don't do any particular C2 magic (such as checking for
 114 various forms of disabled accounts), so if you rely on those features,
 115 you shouldn't use those programs. If you configure with
 116 @samp{--enable-osfc2}, these programs will, however, set the login
 117 UID. Still: use at your own risk.
 118 @end itemize
 119
 120 At present @samp{su} does not accept the vouching flag, so it will not
 121 work as expected.
 122
 123 Also, kerberised ftp will not work with C2 passwords. You can solve this
 124 by using both Digital's ftpd and our on different ports.
 125
 126 @strong{Remember}, if you do these changes you will get a system that
 127 most certainly does @emph{not} fulfil the requirements of a C2
 128 system. If C2 is what you want, for instance if someone else is forcing
 129 you to use it, you're out of luck.  If you use enhanced security because
 130 you want a system that is more secure than it would otherwise be, you
 131 probably got an even more secure system. Passwords will not be sent in
 132 the clear, for instance.
 133
 134 @node IRIX, , Digital SIA, Authentication modules
 135 @subsection IRIX
 136
 137 The IRIX support is a module that is compatible with Transarc's
 138 @file{afskauthlib.so}.  It should work with all programs that use this
 139 library. This should include @command{login} and @command{xdm}.
 140
 141 The interface is not very documented but it seems that you have to copy
 142 @file{libkafs.so}, @file{libkrb.so}, and @file{libdes.so} to
 143 @file{/usr/lib}, or build your @file{afskauthlib.so} statically.
 144
 145 The @file{afskauthlib.so} itself is able to reside in
 146 @file{/usr/vice/etc}, @file{/usr/afsws/lib}, or the current directory
 147 (wherever that is).
 148
 149 IRIX 6.4 and newer seem to have all programs (including @command{xdm} and
 150 @command{login}) in the N32 object format, whereas in older versions they
 151 were O32. For it to work, the @file{afskauthlib.so} library has to be in
 152 the same object format as the program that tries to load it. This might
 153 require that you have to configure and build for O32 in addition to the
 154 default N32.
 155
 156 Apart from this it should ``just work''; there are no configuration
 157 files.
 158
 159 Note that recent Irix 6.5 versions (at least 6.5.22) have PAM,
 160 including a @file{pam_krb5.so} module.  Not all relevant programs use
 161 PAM, though, e.g.@: @command{ssh}. In particular, for console
 162 graphical login you need to turn off @samp{visuallogin} and turn on
 163 @samp{xdm} with @command{chkconfig}.
 164
 165 @node AFS, , Authentication modules, Applications
 166 @section AFS
 167
 168 @cindex AFS
 169 AFS is a distributed filesystem that uses Kerberos for authentication.
 170
 171 @cindex OpenAFS
 172 @cindex Arla
 173 For more information about AFS see OpenAFS
 174 @url{http://www.openafs.org/} and Arla
 175 @url{http://www.stacken.kth.se/projekt/arla/}.
 176
 177 @subsection How to get a KeyFile
 178
 179 @file{ktutil -k AFSKEYFILE:KeyFile get afs@@MY.REALM}
 180
 181 or you can extract it with kadmin
 182
 183 @example
 184 kadmin> ext -k AFSKEYFILE:/usr/afs/etc/KeyFile afs@@My.CELL.NAME
 185 @end example
 186
 187 You have to make sure you have a @code{des-cbc-md5} encryption type since that
 188 is the enctype that will be converted.
 189
 190 @subsection How to convert a srvtab to a KeyFile
 191
 192 You need a @file{/usr/vice/etc/ThisCell} containing the cellname of your
 193 AFS-cell.
 194
 195 @file{ktutil copy krb4:/root/afs-srvtab AFSKEYFILE:/usr/afs/etc/KeyFile}.
 196
 197 If keyfile already exists, this will add the new key in afs-srvtab to
 198 KeyFile.
 199
 200 @section Using 2b tokens with AFS
 201
 202 @subsection What is 2b ?
 203
 204 2b is the name of the proposal that was implemented to give basic
 205 Kerberos 5 support to AFS in rxkad. It's not real Kerberos 5 support
 206 since it still uses fcrypt for data encryption and not Kerberos
 207 encryption types.
 208
 209 Its only possible (in all cases) to do this for DES encryption types
 210 because only then the token (the AFS equivalent of a ticket) will be
 211 smaller than the maximum size that can fit in the token cache in the
 212 OpenAFS/Transarc client. It is a so tight fit that some extra wrapping
 213 on the ASN1/DER encoding is removed from the Kerberos ticket.
 214
 215 2b uses a Kerberos 5 EncTicketPart instead of a Kerberos 4 ditto for
 216 the part of the ticket that is encrypted with the service's key. The
 217 client doesn't know what's inside the encrypted data so to the client
 218 it doesn't matter.
 219
 220 To  differentiate between Kerberos 4 tickets and Kerberos 5 tickets, 2b
 221 uses a special kvno, 213 for 2b tokens and 255 for Kerberos 5 tokens.
 222
 223 Its a requirement that all AFS servers that support 2b also support
 224 native Kerberos 5 in rxkad.
 225
 226 @subsection Configuring a Heimdal kdc to use 2b tokens
 227
 228 Support for 2b tokens in the kdc are turned on for specific principals
 229 by adding them to the string list option @code{[kdc]use_2b} in the
 230 kdc's @file{krb5.conf} file.
 231
 232 @example
 233 [kdc]
 234         use_2b = @{
 235                 afs@@SU.SE = yes
 236                 afs/it.su.se@@SU.SE = yes
 237         @}
 238 @end example
 239
 240 @subsection Configuring AFS clients for 2b support
 241
 242 There is no need to configure AFS clients for 2b support. The only
 243 software that needs to be installed/upgrade is a Kerberos 5 enabled
 244 @file{afslog}.