crypto/heimdal/doc/apps.texi

   1 @c $Id$
   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 kafs and afslog
 178 @cindex afslog
 179
 180 @manpage{afslog,1} will obtains AFS tokens for a number of cells. What cells to get
 181 tokens for can either be specified as an explicit list, as file paths to
 182 get tokens for, or be left unspecified, in which case will use whatever
 183 magic @manpage{kafs,3} decides upon.
 184
 185 If not told what cell to get credentials for, @manpage{kafs,3} will
 186 search for the files ThisCell and TheseCells in the locations
 187 specified in @manpage{kafs,3} and try to get tokens for these cells
 188 and the cells specified in $HOME/.TheseCells.
 189
 190 More usefully it will look at and ~/.TheseCells in your home directory
 191 and for each line which is a cell get afs token for these cells.
 192
 193 The TheseCells file defines the the cells to which applications on the
 194 local client machine should try to aquire tokens for. It must reside in
 195 the directories searched by @manpage{kafs,3} on every AFS client machine.
 196
 197 The file is in ASCII format and contains one character string, the cell
 198 name, per line. Cell names are case sensitive, but most cell names
 199 are lower case.
 200
 201 See manpage for @manpage{kafs,3} for search locations of ThisCell and TheseCells.
 202
 203 @subsection How to get a KeyFile
 204
 205 @file{ktutil -k AFSKEYFILE:KeyFile get afs@@MY.REALM}
 206
 207 or you can extract it with kadmin
 208
 209 @example
 210 kadmin> ext -k AFSKEYFILE:/usr/afs/etc/KeyFile afs@@My.CELL.NAME
 211 @end example
 212
 213 You have to make sure you have a @code{des-cbc-md5} encryption type since that
 214 is the enctype that will be converted.
 215
 216 @subsection How to convert a srvtab to a KeyFile
 217
 218 You need a @file{/usr/vice/etc/ThisCell} containing the cellname of your
 219 AFS-cell.
 220
 221 @file{ktutil copy krb4:/root/afs-srvtab AFSKEYFILE:/usr/afs/etc/KeyFile}.
 222
 223 If keyfile already exists, this will add the new key in afs-srvtab to
 224 KeyFile.
 225
 226 @section Using 2b tokens with AFS
 227
 228 @subsection What is 2b ?
 229
 230 2b is the name of the proposal that was implemented to give basic
 231 Kerberos 5 support to AFS in rxkad. It's not real Kerberos 5 support
 232 since it still uses fcrypt for data encryption and not Kerberos
 233 encryption types.
 234
 235 Its only possible (in all cases) to do this for DES encryption types
 236 because only then the token (the AFS equivalent of a ticket) will be
 237 smaller than the maximum size that can fit in the token cache in the
 238 OpenAFS/Transarc client. It is a so tight fit that some extra wrapping
 239 on the ASN1/DER encoding is removed from the Kerberos ticket.
 240
 241 2b uses a Kerberos 5 EncTicketPart instead of a Kerberos 4 ditto for
 242 the part of the ticket that is encrypted with the service's key. The
 243 client doesn't know what's inside the encrypted data so to the client
 244 it doesn't matter.
 245
 246 To  differentiate between Kerberos 4 tickets and Kerberos 5 tickets, 2b
 247 uses a special kvno, 213 for 2b tokens and 255 for Kerberos 5 tokens.
 248
 249 Its a requirement that all AFS servers that support 2b also support
 250 native Kerberos 5 in rxkad.
 251
 252 @subsection Configuring a Heimdal kdc to use 2b tokens
 253
 254 Support for 2b tokens in the kdc are turned on for specific principals
 255 by adding them to the string list option @code{[kdc]use_2b} in the
 256 kdc's @file{krb5.conf} file.
 257
 258 @example
 259 [kdc]
 260         use_2b = @{
 261                 afs@@SU.SE = yes
 262                 afs/it.su.se@@SU.SE = yes
 263         @}
 264 @end example
 265
 266 @subsection Configuring AFS clients for 2b support
 267
 268 There is no need to configure AFS clients for 2b support. The only
 269 software that needs to be installed/upgrade is a Kerberos 5 enabled
 270 @file{afslog}.