1233294Sstas@c $Id$
2178825Sdfr
3178825Sdfr@node Applications, Things in search for a better place, Setting up a realm, Top
4178825Sdfr
5178825Sdfr@chapter Applications
6178825Sdfr
7178825Sdfr@menu
8178825Sdfr* Authentication modules::
9178825Sdfr* AFS::
10178825Sdfr@end menu
11178825Sdfr
12178825Sdfr@node  Authentication modules, AFS, Applications, Applications
13178825Sdfr@section Authentication modules
14178825Sdfr
15178825SdfrThe problem of having different authentication mechanisms has been
16178825Sdfrrecognised by several vendors, and several solutions have appeared. In
17178825Sdfrmost cases these solutions involve some kind of shared modules that are
18178825Sdfrloaded at run-time.  Modules for some of these systems can be found in
19178825Sdfr@file{lib/auth}.  Presently there are modules for Digital's SIA,
20178825Sdfrand IRIX' @code{login} and @code{xdm} (in
21178825Sdfr@file{lib/auth/afskauthlib}).
22178825Sdfr
23178825Sdfr@menu
24178825Sdfr* Digital SIA::                 
25178825Sdfr* IRIX::                        
26178825Sdfr@end menu
27178825Sdfr
28178825Sdfr@node Digital SIA, IRIX, Authentication modules, Authentication modules
29178825Sdfr@subsection Digital SIA
30178825Sdfr
31178825SdfrHow to install the SIA module depends on which OS version you're
32178825Sdfrrunning. Tru64 5.0 has a new command, @file{siacfg}, which makes this
33178825Sdfrprocess quite simple. If you have this program, you should just be able
34178825Sdfrto run:
35178825Sdfr@example
36178825Sdfrsiacfg -a KRB5 /usr/athena/lib/libsia_krb5.so
37178825Sdfr@end example
38178825Sdfr
39178825SdfrOn older versions, or if you want to do it by hand, you have to do the
40178825Sdfrfollowing (not tested by us on Tru64 5.0):
41178825Sdfr
42178825Sdfr@itemize @bullet
43178825Sdfr
44178825Sdfr@item
45178825SdfrMake sure @file{libsia_krb5.so} is available in
46178825Sdfr@file{/usr/athena/lib}. If @file{/usr/athena} is not on local disk, you
47178825Sdfrmight want to put it in @file{/usr/shlib} or someplace else. If you do,
48178825Sdfryou'll have to edit @file{krb5_matrix.conf} to reflect the new location
49178825Sdfr(you will also have to do this if you installed in some other directory
50178825Sdfrthan @file{/usr/athena}). If you built with shared libraries, you will
51178825Sdfrhave to copy the shared @file{libkrb.so}, @file{libdes.so},
52178825Sdfr@file{libkadm.so}, and @file{libkafs.so} to a place where the loader can
53178825Sdfrfind them (such as @file{/usr/shlib}).
54178825Sdfr@item
55178825SdfrCopy (your possibly edited) @file{krb5_matrix.conf} to @file{/etc/sia}.
56178825Sdfr@item
57178825SdfrApply @file{security.patch} to @file{/sbin/init.d/security}.
58178825Sdfr@item
59178825SdfrTurn on KRB5 security by issuing @kbd{rcmgr set SECURITY KRB5} and
60178825Sdfr@kbd{rcmgr set KRB5_MATRIX_CONF krb5_matrix.conf}.
61178825Sdfr@item
62178825SdfrDigital thinks you should reboot your machine, but that really shouldn't
63178825Sdfrbe necessary.  It's usually sufficient just to run
64178825Sdfr@kbd{/sbin/init.d/security start} (and restart any applications that use
65178825SdfrSIA, like @code{xdm}.)
66178825Sdfr@end itemize
67178825Sdfr
68178825SdfrUsers with local passwords (like @samp{root}) should be able to login
69178825Sdfrsafely.
70178825Sdfr
71178825SdfrWhen using Digital's xdm the @samp{KRB5CCNAME} environment variable isn't
72178825Sdfrpassed along as it should (since xdm zaps the environment). Instead you
73178825Sdfrhave to set @samp{KRB5CCNAME} to the correct value in
74178825Sdfr@file{/usr/lib/X11/xdm/Xsession}. Add a line similar to
75178825Sdfr@example
76178825SdfrKRB5CCNAME=FILE:/tmp/krb5cc`id -u`_`ps -o ppid= -p $$`; export KRB5CCNAME
77178825Sdfr@end example
78178825SdfrIf you use CDE, @code{dtlogin} allows you to specify which additional
79178825Sdfrenvironment variables it should export. To add @samp{KRB5CCNAME} to this
80178825Sdfrlist, edit @file{/usr/dt/config/Xconfig}, and look for the definition of
81178825Sdfr@samp{exportList}. You want to add something like:
82178825Sdfr@example
83178825SdfrDtlogin.exportList:     KRB5CCNAME
84178825Sdfr@end example
85178825Sdfr
86178825Sdfr@subsubheading Notes to users with Enhanced security
87178825Sdfr
88178825SdfrDigital's @samp{ENHANCED} (C2) security, and Kerberos solve two
89178825Sdfrdifferent problems. C2 deals with local security, adds better control of
90178825Sdfrwho can do what, auditing, and similar things. Kerberos deals with
91178825Sdfrnetwork security.
92178825Sdfr
93178825SdfrTo make C2 security work with Kerberos you will have to do the
94178825Sdfrfollowing.
95178825Sdfr
96178825Sdfr@itemize @bullet
97178825Sdfr@item
98178825SdfrReplace all occurrences of @file{krb5_matrix.conf} with
99178825Sdfr@file{krb5+c2_matrix.conf} in the directions above.
100178825Sdfr@item
101178825SdfrYou must enable ``vouching'' in the @samp{default} database.  This will
102178825Sdfrmake the OSFC2 module trust other SIA modules, so you can login without
103178825Sdfrgiving your C2 password. To do this use @samp{edauth} to edit the
104178825Sdfrdefault entry @kbd{/usr/tcb/bin/edauth -dd default}, and add a
105178825Sdfr@samp{d_accept_alternate_vouching} capability, if not already present.
106178825Sdfr@item
107178825SdfrFor each user who does @emph{not} have a local C2 password, you should
108178825Sdfrset the password expiration field to zero. You can do this for each
109178825Sdfruser, or in the @samp{default} table. To do this use @samp{edauth} to
110178825Sdfrset (or change) the @samp{u_exp} capability to @samp{u_exp#0}.
111178825Sdfr@item
112178825SdfrYou also need to be aware that the shipped @file{login}, @file{rcp}, and
113178825Sdfr@file{rshd}, don't do any particular C2 magic (such as checking for
114178825Sdfrvarious forms of disabled accounts), so if you rely on those features,
115178825Sdfryou shouldn't use those programs. If you configure with
116178825Sdfr@samp{--enable-osfc2}, these programs will, however, set the login
117178825SdfrUID. Still: use at your own risk.
118178825Sdfr@end itemize
119178825Sdfr
120178825SdfrAt present @samp{su} does not accept the vouching flag, so it will not
121178825Sdfrwork as expected.
122178825Sdfr
123178825SdfrAlso, kerberised ftp will not work with C2 passwords. You can solve this
124178825Sdfrby using both Digital's ftpd and our on different ports.
125178825Sdfr
126178825Sdfr@strong{Remember}, if you do these changes you will get a system that
127178825Sdfrmost certainly does @emph{not} fulfil the requirements of a C2
128178825Sdfrsystem. If C2 is what you want, for instance if someone else is forcing
129178825Sdfryou to use it, you're out of luck.  If you use enhanced security because
130178825Sdfryou want a system that is more secure than it would otherwise be, you
131178825Sdfrprobably got an even more secure system. Passwords will not be sent in
132178825Sdfrthe clear, for instance.
133178825Sdfr
134178825Sdfr@node IRIX, , Digital SIA, Authentication modules
135178825Sdfr@subsection IRIX
136178825Sdfr
137178825SdfrThe IRIX support is a module that is compatible with Transarc's
138178825Sdfr@file{afskauthlib.so}.  It should work with all programs that use this
139178825Sdfrlibrary. This should include @command{login} and @command{xdm}.
140178825Sdfr
141178825SdfrThe interface is not very documented but it seems that you have to copy
142178825Sdfr@file{libkafs.so}, @file{libkrb.so}, and @file{libdes.so} to
143178825Sdfr@file{/usr/lib}, or build your @file{afskauthlib.so} statically.
144178825Sdfr
145178825SdfrThe @file{afskauthlib.so} itself is able to reside in
146178825Sdfr@file{/usr/vice/etc}, @file{/usr/afsws/lib}, or the current directory
147178825Sdfr(wherever that is).
148178825Sdfr
149178825SdfrIRIX 6.4 and newer seem to have all programs (including @command{xdm} and
150178825Sdfr@command{login}) in the N32 object format, whereas in older versions they
151178825Sdfrwere O32. For it to work, the @file{afskauthlib.so} library has to be in
152178825Sdfrthe same object format as the program that tries to load it. This might
153178825Sdfrrequire that you have to configure and build for O32 in addition to the
154178825Sdfrdefault N32.
155178825Sdfr
156178825SdfrApart from this it should ``just work''; there are no configuration
157178825Sdfrfiles.
158178825Sdfr
159178825SdfrNote that recent Irix 6.5 versions (at least 6.5.22) have PAM,
160178825Sdfrincluding a @file{pam_krb5.so} module.  Not all relevant programs use
161178825SdfrPAM, though, e.g.@: @command{ssh}. In particular, for console
162178825Sdfrgraphical login you need to turn off @samp{visuallogin} and turn on
163178825Sdfr@samp{xdm} with @command{chkconfig}.
164178825Sdfr
165178825Sdfr@node AFS, , Authentication modules, Applications
166178825Sdfr@section AFS
167178825Sdfr
168178825Sdfr@cindex AFS
169178825SdfrAFS is a distributed filesystem that uses Kerberos for authentication.
170178825Sdfr
171178825Sdfr@cindex OpenAFS
172178825Sdfr@cindex Arla
173178825SdfrFor more information about AFS see OpenAFS
174178825Sdfr@url{http://www.openafs.org/} and Arla
175178825Sdfr@url{http://www.stacken.kth.se/projekt/arla/}.
176178825Sdfr
177233294Sstas@subsection kafs and afslog
178233294Sstas@cindex afslog
179233294Sstas
180233294Sstas@manpage{afslog,1} will obtains AFS tokens for a number of cells. What cells to get
181233294Sstastokens for can either be specified as an explicit list, as file paths to
182233294Sstasget tokens for, or be left unspecified, in which case will use whatever
183233294Sstasmagic @manpage{kafs,3} decides upon.
184233294Sstas
185233294SstasIf not told what cell to get credentials for, @manpage{kafs,3} will
186233294Sstassearch for the files ThisCell and TheseCells in the locations
187233294Sstasspecified in @manpage{kafs,3} and try to get tokens for these cells
188233294Sstasand the cells specified in $HOME/.TheseCells.
189233294Sstas
190233294SstasMore usefully it will look at and ~/.TheseCells in your home directory
191233294Sstasand for each line which is a cell get afs token for these cells.
192233294Sstas
193233294SstasThe TheseCells file defines the the cells to which applications on the
194233294Sstaslocal client machine should try to aquire tokens for. It must reside in
195233294Sstasthe directories searched by @manpage{kafs,3} on every AFS client machine.
196233294Sstas
197233294SstasThe file is in ASCII format and contains one character string, the cell
198233294Sstasname, per line. Cell names are case sensitive, but most cell names
199233294Sstasare lower case.
200233294Sstas
201233294SstasSee manpage for @manpage{kafs,3} for search locations of ThisCell and TheseCells.
202233294Sstas
203178825Sdfr@subsection How to get a KeyFile
204178825Sdfr
205178825Sdfr@file{ktutil -k AFSKEYFILE:KeyFile get afs@@MY.REALM}
206178825Sdfr
207178825Sdfror you can extract it with kadmin
208178825Sdfr
209178825Sdfr@example
210178825Sdfrkadmin> ext -k AFSKEYFILE:/usr/afs/etc/KeyFile afs@@My.CELL.NAME
211178825Sdfr@end example
212178825Sdfr
213178825SdfrYou have to make sure you have a @code{des-cbc-md5} encryption type since that
214178825Sdfris the enctype that will be converted.
215178825Sdfr
216178825Sdfr@subsection How to convert a srvtab to a KeyFile
217178825Sdfr
218178825SdfrYou need a @file{/usr/vice/etc/ThisCell} containing the cellname of your
219178825SdfrAFS-cell.
220178825Sdfr
221178825Sdfr@file{ktutil copy krb4:/root/afs-srvtab AFSKEYFILE:/usr/afs/etc/KeyFile}.
222178825Sdfr
223178825SdfrIf keyfile already exists, this will add the new key in afs-srvtab to
224178825SdfrKeyFile.
225178825Sdfr
226178825Sdfr@section Using 2b tokens with AFS
227178825Sdfr
228178825Sdfr@subsection What is 2b ?
229178825Sdfr
230178825Sdfr2b is the name of the proposal that was implemented to give basic
231178825SdfrKerberos 5 support to AFS in rxkad. It's not real Kerberos 5 support
232178825Sdfrsince it still uses fcrypt for data encryption and not Kerberos
233178825Sdfrencryption types.
234178825Sdfr
235178825SdfrIts only possible (in all cases) to do this for DES encryption types
236178825Sdfrbecause only then the token (the AFS equivalent of a ticket) will be
237178825Sdfrsmaller than the maximum size that can fit in the token cache in the
238178825SdfrOpenAFS/Transarc client. It is a so tight fit that some extra wrapping
239178825Sdfron the ASN1/DER encoding is removed from the Kerberos ticket.
240178825Sdfr
241178825Sdfr2b uses a Kerberos 5 EncTicketPart instead of a Kerberos 4 ditto for
242178825Sdfrthe part of the ticket that is encrypted with the service's key. The
243178825Sdfrclient doesn't know what's inside the encrypted data so to the client
244178825Sdfrit doesn't matter.
245178825Sdfr
246178825SdfrTo  differentiate between Kerberos 4 tickets and Kerberos 5 tickets, 2b
247178825Sdfruses a special kvno, 213 for 2b tokens and 255 for Kerberos 5 tokens.
248178825Sdfr
249178825SdfrIts a requirement that all AFS servers that support 2b also support
250178825Sdfrnative Kerberos 5 in rxkad.
251178825Sdfr
252178825Sdfr@subsection Configuring a Heimdal kdc to use 2b tokens
253178825Sdfr
254178825SdfrSupport for 2b tokens in the kdc are turned on for specific principals
255178825Sdfrby adding them to the string list option @code{[kdc]use_2b} in the
256178825Sdfrkdc's @file{krb5.conf} file.
257178825Sdfr
258178825Sdfr@example
259178825Sdfr[kdc]
260178825Sdfr	use_2b = @{
261178825Sdfr		afs@@SU.SE = yes
262178825Sdfr		afs/it.su.se@@SU.SE = yes
263178825Sdfr	@}
264178825Sdfr@end example
265178825Sdfr
266178825Sdfr@subsection Configuring AFS clients for 2b support
267178825Sdfr
268178825SdfrThere is no need to configure AFS clients for 2b support. The only
269178825Sdfrsoftware that needs to be installed/upgrade is a Kerberos 5 enabled
270178825Sdfr@file{afslog}.
271