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