crypto/external/bsd/heimdal/dist/doc/apps.texi

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