source: trunk/third/lprng/doc/LPRng-HOWTO-16.html @ 14517

Revision 14517, 35.1 KB checked in by mwhitson, 25 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r14516, which included commits to RCS files with non-trunk default branches.
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2<HTML>
3<HEAD>
4 <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
5 <TITLE> LPRng-HOWTO: Authentication and Encryption</TITLE>
6 <LINK HREF="LPRng-HOWTO-17.html" REL=next>
7 <LINK HREF="LPRng-HOWTO-15.html" REL=previous>
8 <LINK HREF="LPRng-HOWTO.html#toc16" REL=contents>
9</HEAD>
10<BODY>
11<A HREF="LPRng-HOWTO-17.html">Next</A>
12<A HREF="LPRng-HOWTO-15.html">Previous</A>
13<A HREF="LPRng-HOWTO.html#toc16">Contents</A>
14<HR>
15<H2><A NAME="authref"></A> <A NAME="s16">16. Authentication and Encryption</A></H2>
16
17<P>One of the major problems in a print spooler system is providing
18privacy and authentication services for users.  One method is to
19construct a specific set of protocols which will be used for
20providing the privacy or authentication;  another is to provide a
21simple interface to a set of tools that will do the authentication
22and/or encryption.
23<P>LPRng provides native support for the MIT Kerberos 4 extensions and
24Kerberos 5 authentication.
25<P>LPRng has native support for the PGP (Pretty Good Privacy) program
26and can sign and optionally encrypt command and responses between servers
27and clients.
28Due to legal restrictions,
29an external PGP program must be used for this purpose.
30<P>A simple MD5 hash based authentication scheme is also provided as an
31example to illustrate how new or different authentication methods
32can be adddd.
33<P>Finally,
34LPRng provide a general purpose interface allowing users to insert their
35own authentication methods,
36either at the program level or at the code level.
37<H2><A NAME="ss16.1">16.1 Authentication</A>
38</H2>
39
40<P>A careful study of the authentication problem shows that it should be done
41during reception of commands and/or jobs from a remote user and/or
42spooler.  At this time the following must be done:
43<OL>
44<LI>The received command must be checked for consistency,  and the
45remote user and host must be determined.</LI>
46<LI>The remote user and host must be authenticated.</LI>
47<LI>The command and/or spooling operation must be carried out.</LI>
48<LI>The results must be returned to the remote system.</LI>
49</OL>
50<P>
51<H2><A NAME="ss16.2">16.2 Identifiers</A>
52</H2>
53
54<P>When a user logs into a system,  they are assigned a user name
55and a corresponding UserID.  This user name is used by the LPRng
56software when transferring jobs to identify the user.
57<P>When we look into the problem of authentication,  we will possibly
58have a more global user identification to deal with, the
59authentication identifier (AuthID).  One way to deal with this problem is to
60give LPRng intimate knowledge of the UserID and AuthID relationship.
61While this is possible it is difficult to deal with in a
62simple and extensible manner.  An alternate solution is to provide
63a mapping service,  where the authentication procedure provides
64a map between the UserID and AuthID.
65<H2><A NAME="ss16.3">16.3 RFC1179 Protocol Extensions</A>
66</H2>
67
68<P>The RFC1179 protocol specifies that a LPD server command sent on
69a connection has the form:
70<BLOCKQUOTE><CODE>
71<PRE>
72\nnn[additional fields]\n
73</PRE>
74</CODE></BLOCKQUOTE>
75<P><CODE>\nnn</CODE> is a one octet (byte) value with the following meaning:
76<P>
77<BLOCKQUOTE><CODE>
78<PRE>
79REQ_START   1    start printer
80REQ_RECV    2    transfer a printer job
81REQ_DSHORT  3    print short form of queue status
82REQ_DLONG   4    print long form of queue status
83REQ_REMOVE  5    remove jobs
84</PRE>
85</CODE></BLOCKQUOTE>
86<P>The LPRng system extends the protocol with the following additional
87types:
88<BLOCKQUOTE><CODE>
89<PRE>
90REQ_CONTROL 6    do control operation
91REQ_BLOCK   7    transfer a block format print job
92REQ_SECURE  8    do operation with authentication
93</PRE>
94</CODE></BLOCKQUOTE>
95<P>The REQ_CONTROL allows a remote user to send LPC commands to the
96server.  The REQ_BLOCK provides an alternate method to transfer a
97job.  Rather than transferring the control and data files individually,
98this format transfers one file.  The REQ_AUTH provides a mechanism
99for providing an authentication mechanism and is described in this
100document.
101<H2><A NAME="authforward"></A> <A NAME="auth"></A> <A NAME="ss16.4">16.4 Authentication Operations</A>
102</H2>
103
104<P>Options used:
105<UL>
106<LI> <CODE>auth=</CODE><EM>client to server authentication type</EM></LI>
107<LI> <CODE>auth_forward=</CODE><EM>server to server authentication type</EM></LI>
108<LI> <CODE>XX_id=</CODE><EM>server identification</EM></LI>
109<LI> <CODE>XX_forward_id=</CODE><EM>Server identification</EM></LI>
110</UL>
111<P>A client (<CODE>lpr, lpc, etc</CODE> to <CODE>lpd</CODE> server authenticated transfer
112proceeds as follows.
113If an authenticated transfer is specified by the
114<CODE>auth=protocol</CODE> entry in the printcap or configuration information,
115the client sends a request for an authenticated transfer
116to the server.
117<P>Part of the authentication request is the authentication type.
118If authentication type <CODE>XX</CODE> is requested
119the server will examine the information in the printcap and configuration
120entries for an <CODE>XX_id</CODE> value.
121If this value is present then the server supports authentication of this type.
122Further permission checks are carried out and finally the
123server will accept or reject the authentication request.
124If the request is accepted the server returns a postive
125acknowlegement (single 0 byte) to the requester,
126otherwise it returns a nonzero value and an error message.
127<P>If the request is accepted
128then an authentication specific protocol exchange is carried out between
129client and server.
130The commands and/or data files
131are encrypted and/or signed and transferred to the server.
132The protocol specific software on the server will then decrypt and/or check
133signatures,
134perform the requested actions,
135and in turn generate a status information.
136The status information is encrypted and/or signed by the server
137and sent to the client,
138where the client decrypts and/or checked for correct signature.
139<P>A <CODE>lpd</CODE> server to <CODE>lpd</CODE> server authenticated transfer
140proceeds as follows.
141If an authenticated transfer is specified by the
142<CODE>auth_forward=protocol</CODE> entry in the printcap or configuration information,
143the originating server sends a request for an authenticated transfer
144to the destination server.
145The originating server plays the part of the client
146and performs the same set of actions.
147<P>The following printcap or user level information needs to be provided
148for an authenticated exchange.
149<OL>
150<LI>The <CODE>auth</CODE> option specifies the authentication type to be used
151for client to server transfers.
152For example,
153<CODE>auth=kerberos5</CODE> would specify Kerberos 5 authentication,
154<CODE>auth=kerberos4</CODE> would specify Kerberos 4 authentication,
155<CODE>auth=pgp</CODE> would specify PGP authentication,
156<CODE>auth=md5</CODE> would specify MD5 authentication,
157etc.
158The special form <CODE>auth@</CODE> specifies no authentication.</LI>
159<LI>The <CODE>auth_forward</CODE> option specifies the authentication type to be used
160for server to server transfers.
161For example,
162<CODE>auth_forward=kerberos5</CODE> would specify Kerberos 5 authentication,
163etc.
164The special form <CODE>auth@</CODE> specifies no authentication.</LI>
165<LI>The authenticated transfer request sent to a server has one of the
166following forms, depending on the orginator:
167<BLOCKQUOTE><CODE>
168<PRE>
169\008printer C user_id authtype \n     - for commands (lpq, lpc, etc.)
170\008printer C user_id authtype size\n - for print jobs (lpr)
171\008printer F server_id authtype \n     - forwarded commands (lpq, lpc, etc.)
172\008printer F server_id authtype size\n - forwarded print jobs (lpr)
173</PRE>
174</CODE></BLOCKQUOTE>
175
176<P> 
177The single character with the <CODE>\008</CODE> value signals that this
178is an authentication request
179the <CODE>printer</CODE> is the name of a print queue,
180and the <CODE>C</CODE> (client) or <CODE>F</CODE> indicates that the request is from
181a client program or is a forwarded request from a server.
182The <CODE>user_id</CODE> or <CODE>server_id</CODE> field is an identifier supplied by
183the originator and is dicussed below.
184If the <CODE>size</CODE> value is present then the request
185is for a job transfer and this value represents the job size.
186It is used to determine if there is sufficient space in the spool queue
187for the job.
188</LI>
189<LI>The <CODE>user_id</CODE> or <CODE>server_id</CODE> fields in the authentication
190request are obtained as follows.
191If the request originates from a client,
192then the <CODE>user_id</CODE> is the user name of the originator obtained from
193password information.
194If the request originates from a server,
195then the  <CODE>server_id</CODE> is the printcap or configuration
196<CODE>xx_id=server_id</CODE> value,
197where <CODE>xx</CODE> is the value of the <CODE>auth_forward=xx</CODE> entry.</LI>
198<LI>When the authenticated transfer request is received,
199the destination will either return a single zero byte,
200or a non-zero byte value followed by additional refusal information.
201A refusal terminates the protocol exchange.</LI>
202<LI>Further exchanges are then determined by the authentication
203protocol specific requirements.</LI>
204<LI>Once the initial exchanges have been completed
205a user file and/or command will be transferred to the destination server.</LI>
206<LI>An authentication protcol specific <CODE>AUTHFROM</CODE> and <CODE>AUTHUSER</CODE>
207strings will be supplied
208to the lpd server for purposes of permission checking.</LI>
209<LI>The lpd server then carries out the requested operation,
210and will write error and status information into a file.</LI>
211<LI>After the requested activity has finished,
212protocol specific module transfer the status information in the
213file to the requesting system
214and terminate the protocol exchange.</LI>
215</OL>
216<H2><A NAME="ss16.5">16.5 Permission Checking</A>
217</H2>
218
219<P>When an authenticated transfer has been performed,
220the following permission information will be provided.
221<UL>
222<LI>AUTH<BR>
223This value is <CODE>true</CODE> or <CODE>match</CODE> if an authenticated request
224was received.</LI>
225<LI>AUTHTYPE=authtype<BR>
226This has the value of the <CODE>authtype</CODE> field in the authentication
227request.</LI>
228<LI>AUTHUSER=userinfo<BR>
229This is the <CODE>AUTHUSER</CODE> information provided by the authentication
230protocol,
231and is usually the originating user's identification.</LI>
232<LI>AUTHFROM=frominfo<BR>
233This is the <CODE>AUTHUSER</CODE> information provided by the authentication
234protocol,
235and is usually the originating system (user or lpd server) identification.</LI>
236<LI>AUTHSAMEUSER<BR>
237This item has effect only when checking jobs in a spool queue.
238The <CODE>AUTHUSER</CODE> information from the request is compared to the
239<CODE>AUTHUSER</CODE> information from the request that created a job.
240If they are identical,  the match succeeds.</LI>
241<LI>AUTHJOB
242This item has effect only when checking jobs in a spool queue.
243If the job was transfered using an authentication protocol the match succeeds.<BR></LI>
244</UL>
245<P>For example,  to reject non-authenticated operations, the following
246line could be put in the permissions file.
247<BLOCKQUOTE><CODE>
248<PRE>
249REJECT NOT AUTH
250</PRE>
251</CODE></BLOCKQUOTE>
252<P>If a remote server has id information FFEDBEEFDEAF,  then the
253following will accept only forwarded jobs from this server.
254<BLOCKQUOTE><CODE>
255<PRE>
256ACCEPT AUTH AUTHFROM=FFEDBEEFDEAF
257REJECT AUTH
258REJECT NOT AUTH
259</PRE>
260</CODE></BLOCKQUOTE>
261<P>To allow only authenticated users to remove jobs you can use:
262<BLOCKQUOTE><CODE>
263<PRE>
264ACCEPT AUTH SERVICE=R,M,L,P AUTHSAMEUSER
265REJECT AUTH
266REJECT NOT AUTH
267</PRE>
268</CODE></BLOCKQUOTE>
269<H2><A NAME="ss16.6">16.6 PGP Authentication Support</A>
270</H2>
271
272<P>PGP is a well known encryption and authentication program.
273For more details see the web site
274<A HREF="http://www.pgp.net">http://www.pgp.net</A>
275or the ftp site
276<A HREF="ftp://ftp.pgp.net">ftp://ftp.pgp.net</A>.
277<P>LPRng has greatly simplified the use of PGP for authentication
278by building in support as follows.
279<UL>
280<LI>The <CODE>user</CODE> and <CODE>group</CODE> configuration entry (defaults
281<CODE>daemon</CODE> and <CODE>daemon</CODE> respectively) specify the user and group id
282used by the <CODE>lpd</CODE> server for file and program execution.
283PGP uses the current user id of the PGP process to determine the locations
284of various configuration files and information.
285In this discussion we will assume that <CODE>lpd</CODE> runs as uid <CODE>daemon</CODE>.</LI>
286<LI>By default,
287the PGP program expects the public and secret key rings to be in the
288<CODE>$HOME/.pgp/</CODE> directory
289to be readable only by the user.
290In order to set up PGP authentication,
291make sure that the <CODE>daemon</CODE> account has a home directory.
292Then use the <CODE>su daemon</CODE> command to change effective UID to daemon
293and run the
294<CODE>pgp -kg</CODE>
295(generate key)
296command as daemon.
297The <CODE>daemon</CODE> user should not have a password.</LI>
298<LI>Each PGP key has an associated identifier.
299It is recommended that the <CODE>lpd</CODE> key be <CODE>lpr@hostname</CODE>,
300where hostname is the fully qualified domain name of the server.
301A public and a private key file will be created.</LI>
302<LI>Next,
303place the passphrase for the <CODE>daemon</CODE>
304user in
305<CODE>~daemon/.pgp/serverkey</CODE>,
306and make sure it has owner <CODE>daemon</CODE>
307and <CODE>600</CODE> permissions (read/write only by <CODE>daemon</CODE>).
308This is extremely important.
309If other users can read this file then security will be severely compromised.</LI>
310<LI>Next, distribute the <CODE>lpr@hostname</CODE> public key to all users of the
311LPRng server.
312This is usually done by placing the public key in a well known file location
313or making it available to users by some form of Public Key Distribution system
314(PKD).
315The key can be extracted and put into a text file using the following commands:
316<BLOCKQUOTE><CODE>
317<PRE>
318pgp -kxa userid destfile keyfile
319
320Example:
321> pgp -kxa lpr@astart /tmp/lprkey ~daemon/.pgp/pubring.pgp
322Key for user ID: lpr@astart
323512-bit key, key ID BB261B89, created 1999/01/01
324
325Transport armor file: /tmp/lprkey.asc
326Key extracted to file '/tmp/lprkey.asc'.
327</PRE>
328</CODE></BLOCKQUOTE>
329</LI>
330<LI>To allow a user to send files to the server,
331their public key must be put into the <CODE>daemon</CODE> public key ring.
332This can be done using:
333<BLOCKQUOTE><CODE>
334<PRE>
335pgp -ka /tmp/lprkey.asc
336</PRE>
337</CODE></BLOCKQUOTE>
338</LI>
339<LI>Finally,  the administrator will need to add users public keys to the
340<CODE>daemon</CODE> users public key ring.  This can most easily be done by
341copying all the keys (in ASCII text form) to a single file
342(<CODE>/tmp/keyfile</CODE>)and using:
343<BLOCKQUOTE><CODE>
344<PRE>
345su daemon
346pgp -ka /tmp/keyfile ~daemon/.pgp/pubring.pgp
347</PRE>
348</CODE></BLOCKQUOTE>
349</LI>
350<LI>If the <CODE>lpd</CODE> server is using PGP to forward jobs or requests,
351the destination server's public key must be put in the originating
352servers public keyring.  For example:
353<BLOCKQUOTE><CODE>
354<PRE>
355su daemon
356pgp -ka /tmp/lpd.keyfile ~daemon/.pgp/pubring.pgp
357</PRE>
358</CODE></BLOCKQUOTE>
359</LI>
360</UL>
361<H3><A NAME="pgpserverkey"></A> <A NAME="pgppassphrase"></A> <A NAME="pgppath"></A> Printcap Configuration</H3>
362
363<P>Options used:
364<UL>
365<LI><CODE>pgp_path=</CODE><EM>path to PGP program</EM></LI>
366<LI><CODE>pgp_id=</CODE><EM>destination server key used by clients</EM></LI>
367<LI><CODE>pgp_forward_id=</CODE><EM>destination server used by server</EM></LI>
368<LI><CODE>pgp_server_key=</CODE><EM>path to server passphrase file</EM></LI>
369</UL>
370<P>Example printcap entry:
371<BLOCKQUOTE><CODE>
372<PRE>
373pr:
374    :lp=pr@wayoff
375    :auth=pgp
376    :pgp_id=lpr@wayoff.com
377    :pgp_path=/usr/local/bin/pgp
378pr:server
379    :lp=pr@faroff
380    :auth_forward=pgp
381    :pgp_id=lpr@wayoff.com
382    :pgp_path=/usr/bin/pgp
383    :pgp_forward_id=lpr@faroff.com
384</PRE>
385</CODE></BLOCKQUOTE>
386<P>The <CODE>pgp_path</CODE> value is the path to the PGP program.
387The progam must be executable by all users.
388<P>The <CODE>pgp_id</CODE> value is the id used by PGP to look extract keys from
389key rings.
390When doing a client to server transfer this will be supplied as the id
391to be used for the destination,
392and the user's public keyring will be checked for a key corresponding to
393this id.
394When a request arrives at the server,
395the server will use this value as the id of a key in its private key ring.
396Finally,
397when a server is forwarding a request to a remote server,
398it will use this value
399as the id of the key in its private key ring to be used to sign
400or encode the destination information.
401<P>The <CODE>pgp_forward_id</CODE> value is used by the <CODE>lpd</CODE> server as the id
402to use to find a key for the destination.
403<P>The <CODE>pgp_server_key</CODE> is the path to the file containing the server passphrase.
404This file will be read by <CODE>lpd</CODE> to get the passphrase to unlock the server's
405keyring.
406<H3>User Files and Environment Variables</H3>
407
408<P>Options used:
409<UL>
410<LI><CODE>PGPPASSFILE=</CODE><EM>File to read PGP passphrase from</EM></LI>
411<LI><CODE>PGPPASSFD=</CODE><EM>File descriptor to read PGP passphrase from</EM></LI>
412<LI><CODE>PGPPASS=</CODE><EM>PGP passphrase</EM></LI>
413</UL>
414<P>One problem with using PGP is the need to have users input their
415passphrases.
416The following methods can be used.
417<UL>
418<LI>Put the passphrase in a file,
419say <CODE>$(HOME)/.pgp/.hidden</CODE>,
420and set the <CODE>PGPPASSFILE</CODE> environment variable to the file name.
421This file will be opened and read by PGP to get the passphrase.
422This file should be owned by the user and have <CODE>0600</CODE> or read/write
423only by user permissions.</LI>
424<LI>A more subtle solution is to use the <CODE>PGPPASSFD</CODE> environment variable
425facility.
426This causes PGP to read the passphrase from a file descriptor.
427If the user puts his passphrase in a file,  say
428<CODE>$(HOME)/.pgp/.hidden</CODE>,
429then the following shell script can be used:
430<BLOCKQUOTE><CODE>
431<PRE>
432#!/bin/sh
433#  /usr/local/bin/pgplpr script - passphrase in $(HOME)/.pgp/.hidden
434#
435PGPASSFD=3 3&lt;$(HOME)/.pgp/.hidden lpr "$@"
436</PRE>
437</CODE></BLOCKQUOTE>
438</LI>
439<LI>The least desirable method is to put the passphrase in the
440<CODE>PGPPASS</CODE> environment variable.
441Since the <CODE>ps</CODE> command can be used to list the environment variables
442of processes,
443this is highly undesireable and should not be used under any circumstances.</LI>
444</UL>
445<H2><A NAME="ss16.7">16.7 Using Kerberos 5 for Authentication</A>
446</H2>
447
448<P>LPRng Kerberos 5 authentication is
449based on the
450Kerberos5-1.0.5 release as of March 28, 1999.  This was obtained
451from MIT:
452<OL>
453<LI> ftp to ATHENA-DIST.MIT.EDU (18.159.0.42), login anonymous, password
454your_email_address</LI>
455<LI> Change into the directory '/pub/kerberos/</LI>
456<LI> Get the README files and look at the details of using FTP to get
457the distribution.  Note that there are also patches available
458which you might want to use.</LI>
459</OL>
460<P>Note that the distribution has only the most superficial documentation.
461There are no man pages for any of the support libraries, etc. etc.
462<P>The following sections describe how to set up and test the Kerberos
463software,
464and then how to configure LPRng to use Kerberos.
465<H3><A NAME="kerberosforwardprincipal"></A> <A NAME="kerberosserverprincipal"></A> <A NAME="kerberosservice"></A> <A NAME="kerberosrenew"></A> <A NAME="kerberoslife"></A> <A NAME="kerberoskeytab"></A> Kerberos Installation Procedure</H3>
466
467<P>
468<OL>
469<LI> Get the Kerberos 5 distribution.</LI>
470<LI> Compile and install the distribution.</LI>
471<LI> Create the /etc/krb5.conf, /usr/local/var/krb5kdc/kdc.conf
472files using templates from the src/conf-files subdirectory.
473See the Installation notes and the System Administrators Guide.</LI>
474<LI> Don't forget to create the /usr/local/var/krb5kdc/kdc.acl file;
475I did and it took me HOURS to figure out what was wrong...</LI>
476<LI> Start up the KDC and KADMIN servers - you might want to put
477the following in your rc.local or equivalent file:
478<BLOCKQUOTE><CODE>
479<PRE>
480if [ -f /etc/krb5.conf -a -f /usr/local/var/krb5kdc/kdc.conf  ]; then
481    echo -n ' krb5kdc ';    /usr/local/sbin/krb5kdc;
482    echo -n ' kadmind ';    /usr/local/sbin/kadmind;
483fi
484</PRE>
485</CODE></BLOCKQUOTE>
486</LI>
487<LI> use kadmin (or kadmin.local) to create principals for your users.</LI>
488<LI> Now you need to create principals for the lprng servers.  I have been
489using
490<CODE>lpr/hostname.REALM</CODE>
491as a template-
492i.e.
493<CODE>lpr/astart1.astart.com@ASTART.COM</CODE>
494for an example.</LI>
495<LI>Do this for all the servers.  You should use fully qualified domain names
496for the principals.</LI>
497<LI> Now you need to extract the keytab for each of the servers:
498<BLOCKQUOTE><CODE>
499<PRE>
500kadmin ...
501ktadd -k file_for_host  lpr/hostname.REALM
502</PRE>
503</CODE></BLOCKQUOTE>
504</LI>
505<LI>The 'file_for_host' contains the keytab information, which is the
506equivalent information for the server.</LI>
507<LI> Copy the 'file_for_host' to the server (you might want to encrypt
508or use a secure transfer for this).  You need to put this in
509<CODE>/etc/lpd.keytab</CODE>.
510Make sure that this file is readable only by user <CODE>daemon</CODE>,
511as it will try to read the file to get its server key.
512<BLOCKQUOTE><CODE>
513<PRE>
514#> ls -l /etc/lpd.keytab
515-rw-------  1 daemon  wheel  128 Jan 16 11:06 /etc/lpd.keytab
516</PRE>
517</CODE></BLOCKQUOTE>
518</LI>
519</OL>
520<H3>Printcap Entries</H3>
521
522<P>Options used:
523<UL>
524<LI><CODE>auth=kerberos5=</CODE><EM>use Kerberos5 authentication</EM></LI>
525<LI><CODE>kerberos_id=</CODE><EM>destination server key used by clients</EM></LI>
526<LI><CODE>kerberos_server_principal=</CODE><EM>alias for kerberos_id</EM></LI>
527<LI><CODE>kerberos_forward_id=</CODE><EM>destination server used by server</EM></LI>
528<LI><CODE>kerberos_forward_principal=</CODE><EM>alias for kerberos_forward_id</EM></LI>
529<LI><CODE>kerberos_keytab=</CODE><EM>location of the lpd server keytab file</EM></LI>
530<LI><CODE>kerberos_service=</CODE><EM>service to be used</EM></LI>
531<LI><CODE>kerberos_life=</CODE><EM>lpd server ticket lifetime</EM></LI>
532<LI><CODE>kerberos_renew=</CODE><EM>lpd server ticket renew</EM></LI>
533</UL>
534<P>Example printcap entry:
535<BLOCKQUOTE><CODE>
536<PRE>
537pr:
538    :lp=pr@wayoff
539    :auth=kerberos5
540    :kerberos_id=lpr@wayoff.ASTART.COM
541pr:server
542    :lp=pr@faroff
543    :auth_forward=kerberos5
544    :kerberos_id=lpr@wayoff.ASTART.COM
545    :kerberos_forward_id=lpr@faroff.ASTART.COM
546    :kerberos_keytab=/etc/krb5.keytab
547</PRE>
548</CODE></BLOCKQUOTE>
549<P>The printcap configuration for Kerberos authentication is very simple.
550<P>The <CODE>kerberos_id</CODE> is the principal name of the lpd server
551that clients will connect to.
552For backwards compatibility,
553<CODE>kerberos_server_principal</CODE> can also be used.
554This values is used to obtain a ticket for the <CODE>lpd</CODE> server,
555and is the only entry required for client to server authentication.
556<P>The other entries are used by the <CODE>lpd</CODE> server.
557<CODE>kerberos_keytab</CODE>
558entry is the location of the keytab file to be used by the server.
559This contains the passphrase used by the server to authenticate itself
560and get a ticket from the ticket server.
561<P>The <CODE>kerberos_id</CODE> value is also used by the server during the
562authentication process to make sure that the correct principal name
563was used by the request originator.
564This check has saved many hours of pain in trying to determine why
565authentication is failing.
566<P>The
567<CODE>kerberos_life</CODE> and <CODE>kerberos_renew</CODE>
568set the lifetime and renewability
569of the lpd server Kerberos tickets.
570These values should not be modified unless you are familiar with the
571Kerberos system.
572There are extensive notes in the LPRng source code concerning these values.
573The <CODE>kerberos_service</CODE> value supplies the name of the service
574to be used when generating a ticket.
575It is stronly recommended that the <CODE>kerberos_id</CODE> entry
576be used instead.
577<H3>User Environment Variables and Files</H3>
578
579<P>In order to use kerberos authentication,
580the user will need to obtain a ticket from the Kerberos ticket server.
581This is done using <CODE>kinit</CODE>.
582<P>No other actions are required by the user.
583<H2><A NAME="ss16.8">16.8 Using Kerberos 4 for Authentication</A>
584</H2>
585
586<P>LPRng has built-in support for the Project Athena extensions to the
587RFC1179 protocol.
588These provide an extremely simple authentication protocol
589using an initial credential exchange.
590After the initial exchange the usual RFC1179 protocol is used.
591<P>To enable Kerberos 4 support,
592you must modify the <CODE>LPRng/src/Makefile</CODE> and recompile
593the LPRng code.
594You should be aware that this is not a supported extension,
595and is provided as a courtesy to MIT and Project Athena.
596<BLOCKQUOTE><CODE>
597<PRE>
598cd LPRng
599./configure
600make MIT_KERBEROS4=1
601</PRE>
602</CODE></BLOCKQUOTE>
603<H3>Printcap Entries</H3>
604
605<P>Options used:
606<UL>
607<LI><CODE>auth=kerberos4</CODE><EM>use Kerberos4 authentication</EM></LI>
608<LI><CODE>kerberos_id=</CODE><EM>destination server key used by clients</EM></LI>
609<LI><CODE>kerberos_server_principal=</CODE><EM>alias for kerberos_id</EM></LI>
610</UL>
611<P>Example printcap entry:
612<BLOCKQUOTE><CODE>
613<PRE>
614pr:
615    :lp=pr@wayoff
616    :auth=kerberos4
617    :kerberos_id=lpr@wayoff.ASTART.COM
618</PRE>
619</CODE></BLOCKQUOTE>
620<P>The configuration information for Kerberos4 and Kerberos5 is identical
621and differ only in the authentication type.
622Note that only client to server authentication is supported.
623<H2><A NAME="ss16.9">16.9 Using MD5 for Authentication</A>
624</H2>
625
626<P>LPRng has built-in support for using MD5 digests as an
627authentication method.
628The implementation is provided as an example of how to
629add user level authentication into the LPRng system.
630<P>The method used to do authentication is very simple.
631Each user has a file containing a set of keys that are used to salt an
632md5 hash.
633The information being transferred has its md5 checksum calculated using
634this salt,
635and is then transferred to the destination,
636along with the md5 hash result.
637At the destination the server will get the user id,
638obtain the salt value from a key file,
639and then calculate the md5 hash value.
640If the two are in agreement,
641authentication is successful.
642<P>The keyfile used for md5 authentication contains an id followed by
643a text string whose binary value is used as a hash key:
644<BLOCKQUOTE><CODE>
645<PRE>
646id1=key
647id2=key
648
649Example:
650
651lpr@h2=tadf79asd%^1asdf
652lpr@h1=fdfa%$^&amp;^%$
653</PRE>
654</CODE></BLOCKQUOTE>
655<P>
656<H3>Printcap Entries</H3>
657
658<P>Options used:
659<UL>
660<LI><CODE>auth=md5</CODE><EM>use MD5 authentication</EM></LI>
661<LI><CODE>auth_forward=md5</CODE><EM>forward using MD5 authentication</EM></LI>
662<LI><CODE>md5_id=</CODE><EM>id for server</EM></LI>
663<LI><CODE>md5_forward_id=</CODE><EM>id for server</EM></LI>
664<LI><CODE>md5_server_keyfile=</CODE><EM>server keyfile</EM></LI>
665</UL>
666<P>Example printcap entry:
667<BLOCKQUOTE><CODE>
668<PRE>
669pr:
670    :lp=pr@wayoff
671    :auth=md5
672    :md5_id=lpr@wayoff.com
673pr:server
674        :auth_forward=md5
675        :md5_id=lpr@wayoff.com
676        :md5_server_keyfile
677        :md5_forward_id=lpr@faroff.com
678</PRE>
679</CODE></BLOCKQUOTE>
680<P>The <CODE>md5_id</CODE> value is used by the client to obtain
681a hash key that is used to salt the md5 calculation for client to server
682transfers.
683The <CODE>md5_forward_id</CODE> value is used by the server to obtain
684a hash key that is used to salt the md5 calculation for server to server transfers.
685<P>The <CODE>md5_server_keyfile</CODE> contains the keys of users;
686the id sent as the connection information is used to obtain the key from the file.
687<P>To set up md5 authentication,
688all that is needed is the following.
689<UL>
690<LI>For each user generate a key and place it in the server keyfile.
691This file should have the form:
692<BLOCKQUOTE><CODE>
693<PRE>
694user1@host1=asdfasdfadf
695user2@host2=a8789087asddasdf
696</PRE>
697</CODE></BLOCKQUOTE>
698</LI>
699<LI>Assign a key to the server, and set its printcap entry to this key.
700<BLOCKQUOTE><CODE>
701<PRE>
702pr:
703    :lp=pr@wayoff
704    :auth=md5
705    :md5_id=lpr@wayoff.com
706</PRE>
707</CODE></BLOCKQUOTE>
708</LI>
709<LI>For each user, create a user key file with the following format:
710<BLOCKQUOTE><CODE>
711<PRE>
712lpr@wayoff=user1@host1 asdfasdfadf
713</PRE>
714</CODE></BLOCKQUOTE>
715
716The first entry corresponds to the <CODE>md5_id</CODE> value in the printcap.
717The second field is the <CODE>AUTHUSER</CODE> value supplied to the server
718and which will be used to look up the key in the servers key file.
719Finally,
720the last field is the salt value for the md5 calculation.</LI>
721</UL>
722<H3>User Environment Variables and Files</H3>
723
724<P>Options used:
725<UL>
726<LI><CODE>MD5KEYFILE=5</CODE><EM>location of user keyfile</EM></LI>
727</UL>
728<P>The <CODE>MD5KEYFILE</CODE> environment variable contains the path to the
729user keytab file.
730<H2><A NAME="ss16.10">16.10 Adding Authentication Support</A>
731</H2>
732
733<P>Additional types of authentication support can be added very easily to
734LPRng by using the following conventions and guidelines.
735<P>First,
736the authentication method can be connection based or transfer based.
737Connection based authentication involves the LPRng client or server
738opening a connection to the remote server,
739having the authentication protocol provide authentication information,
740and then having no further interaction with the system.
741This is the easiest to implement and understand method.
742Code needs to be provided to do a simple authentication exchange
743between the two ends of the connection,
744after which no other action needs to be taken.
745<P>Transfer based authentication is more complex,
746but allows encrypted transfers of information between the two systems.
747A connection is established between client and server (or server and server),
748and an initial protocol exchange is performed.
749Then the authentication module transfers the command or job information
750to the destination,
751where is it unpacked and/or decrypted.
752The internal LPD server facilities are then invoked by the authentication
753module,
754which also provides a destination for any error message or information
755destined for the client.
756The authentication module will encrpt or encode this information and then
757send it to the client program.
758This type of authentication is more complex,
759but provides a higher degree of security and reliability than the
760simple connection based system.
761<H3>Printcap Support</H3>
762
763<P>By convention,
764printcap entries
765<CODE>auth=XXX</CODE>
766and
767<CODE>auth_forward=XXX</CODE>
768specifies that authentication protocol <CODE>XXX</CODE>
769is to be used for client to server
770and for server to server transfers respectively.
771<P>Similarly,
772the server receiving an authentication request must have a
773<CODE>XXX_id=name</CODE> entry in the printcap or configuration information.
774This allows several different authentication protocols to be accepted
775by a server.
776<P>By convention,
777printcap and configuration entries of the form
778<CODE>XXX_key</CODE>
779contain configuration information for the <CODE>XXX</CODE> authentication protocol.
780As part of the authentication support process the <CODE>XXX_key</CODE> values
781are extracted from the printcap and configuration files
782and placed in a simple database for the authentication support module.
783<P>If you are using a routing filter,
784then you can also place
785<CODE>XXX_key</CODE>
786information in the routing entry for each file,
787and this will be used for sending the job to the specified destination.
788<H3>Code Support</H3>
789
790<P>The <CODE>LPRng/src/common/sendauth.c</CODE>
791file has the following entries at the end.
792<BLOCKQUOTE><CODE>
793<PRE>
794#define SENDING
795#include "user_auth.stub"
796
797struct security SendSecuritySupported[] = {
798  /* name,       config_tag, connect,    send,   receive */
799  { "kerberos4", "kerberos", Send_krb4_auth, 0, 0 },
800  { "kerberos*", "kerberos", 0,           Krb5_send },
801  { "pgp",       "pgp",      0,           Pgp_send },
802#if defined(USER_SEND)
803 USER_SEND
804#endif
805  {0}
806};
807</PRE>
808</CODE></BLOCKQUOTE>
809
810This is an example of how to add user level authentication support.
811The <CODE>user_auth.stub</CODE>
812file contains the source code for the various modules authentication
813modules.
814You can replace this file with your own version
815if desired.
816The following fields are used.
817<DL>
818<DT><B> name </B><DD><P>The authentication name.
819The <CODE>auth=XXX</CODE> printcap or configuration value will cause the
820<CODE>name</CODE> fields to be searched using a
821glob match.
822<DT><B> config_tag</B><DD><P>When a match is found,
823the <CODE>config_tag</CODE> value is used to search
824the printcap and configuration entries for information.
825If the <CODE>config_tag</CODE> field has value <CODE>XXX</CODE>,
826then entries with keys <CODE>XXX_key</CODE> will be extracted for use
827by the authentication code.
828<DT><B>connect</B><DD><P>Routine to call to support <CODE>connection</CODE>
829level authentication.
830This routine is responsible for connection establishment and
831protocol handshake.
832If the value is 0,
833then the <CODE>send</CODE> field value will be used.
834<DT><B>send</B><DD><P>Routine to call to support <CODE>transfer</CODE>
835level authentication.
836The <CODE>send</CODE>
837routine is provided a file and a connection to the remote server,
838and is responsible for the transferring files.
839</DL>
840<P>The
841<CODE>LPRng/src/common/lpd_secure.c</CODE>
842file has the following information at the end:
843<BLOCKQUOTE><CODE>
844<PRE>
845#define RECEIVE 1
846#include "user_auth.stub"
847
848 struct security ReceiveSecuritySupported[] = {
849    /* name, config_tag, connect, send, receive */
850#if defined(HAVE_KRB_H) &amp;&amp; defined(MIT_KERBEROS4)
851    { "kerberos4", "kerberos",  0, 0, 0 },
852#endif
853#if defined(HAVE_KRB5_H)
854    { "kerberos*", "kerberos",   0, 0, Krb5_receive },
855#endif
856    { "pgp",       "pgp",   0, 0, Pgp_receive, },
857#if defined(USER_RECEIVE)
858/* this should have the form of the entries above */
859 USER_RECEIVE
860#endif
861    {0}
862};
863</PRE>
864</CODE></BLOCKQUOTE>
865<P>This information matches the same information in the <CODE>sendauth.c</CODE>
866file.
867When the authentication request arrives at the server,
868the <CODE>name</CODE> field values are searched for a match,
869and then the <CODE>config_tag</CODE> value is used to get extract configuration
870information from the database for the protocol.
871<P>The <CODE>receive</CODE>
872routine is then called and is expected to handle the remaining
873steps of the authentication protocol.
874If the routine exits with a 0 value then the lpd server expects
875<CODE>connection</CODE> level authentication has been done and proceeds to
876simply transfer information using the standard RFC1179 protocol steps.
877A non-zero return value indicates an error and an error is reported
878to the other end of the connection.
879<P>If the <CODE>receive</CODE> module is to perform <CODE>transfer</CODE> level authentication,
880then the module carries out the necessary steps to transfer the command and/or
881job information.
882It then calls the necessary internal LPRng routine to implement the desired
883services.
884After finishing the requested work,
885these routines return to the calling authentication module,
886which then will transfer data, close the connection to the
887remote system,
888and return to the calling system.
889The combination of 0 return value and closed connection
890indicates successful transfer level authentication to the server.
891<P>The <CODE>user_auth.stub</CODE> file contains the following code that sets the
892<CODE>USER_SEND</CODE> variable:
893<BLOCKQUOTE><CODE>
894<PRE>
895#if defined(SENDING)
896extern int md5_send();
897#  define USER_SEND \
898  { "md5", "md5", md5_send, 0, md5_receive },
899#endif
900</PRE>
901</CODE></BLOCKQUOTE>
902<P>If the <CODE>SENDING</CODE> value has been defined,
903this causes the prototype for <CODE>md5_send()</CODE> to be place in the file
904and the <CODE>USER_SEND</CODE> value to be defined.
905This will cause the <CODE>md5</CODE> authentication information to be placed in the
906correct table.
907<H3>Connection and Transfer Authentication</H3>
908
909<P>Rather than go into a detailed description of the code,
910the <CODE>user_auth.stub</CODE> file contains extremely detailed examples
911as well as several working versions of authentication information.
912It is recommended that the user start with one of these and then
913modify it to suit themselves.
914<HR>
915<A HREF="LPRng-HOWTO-17.html">Next</A>
916<A HREF="LPRng-HOWTO-15.html">Previous</A>
917<A HREF="LPRng-HOWTO.html#toc16">Contents</A>
918</BODY>
919</HTML>
Note: See TracBrowser for help on using the repository browser.