
pam_tacplus v1.2.9
Feb 02 2000

This PAM module support the following functions:

	* authentication
	* authorization (account management)
	* accounting (session management)

All are performed using TACACS+ protocol [1], designed by Cisco Systems.
This is remote AAA protocol, supported by most Cisco hardware. 
A free TACACS+ server is available [2], which I'm using without any
major problems for about a year. Advantages of TACACS+ is that all
(unlike RADIUS) packets exchanged with the authentication server are
encrypted. This module is an attempt to provide most useful part of
TACACS+ functionality to applications using the PAM interface on Linux.

	NOTE that it's in a very early beta stage and different things
	may happen, since it's the first PAM module I've ever written and
	some topics are still not quite clear to me ;)	I'll appreciate
	any comments, suggetions and improvements.

Recognized options:
~~~~~~~~~~~~~~~~~~~

Option		Management group        Description
--------------- ----------------------- ----------------------------------
debug           ALL                     output debugging information via
                                        syslog(3); note, that the debugging
                                        is heavy, including passwords!
					
encrypt         ALL                     encrypt TACACS+ packets; you should
                                        use this always in normal operations

secret=STRING   ALL                     secret key used to encrypt/decrypt
                                        packets sent/received from the server

server=HOSTNAME auth, session           can be specified more than once;
server=IP_ADDR                          adds a TACACS+ server to the servers
                                        list

first_hit       auth                    if multiple servers are supplied,
                                        pam_tacplus will try to authenticate
                                        the user on all servers until it
                                        succeds or all servers are queried

acct_all        session                 if multiple servers are supplied,
                                        pam_tacplus will send accounting
                                        start/stop packets to all servers
                                        on the list

service         account, session        TACACS+ service for authorization
                                        and accounting

protocol        account, session        TACACS+ protocol for authorization
                                        and accounting

The last two items are widely described in TACACS+ draft [1]. They are
required by the server, but it will work if they don't match the real
service authorized :)

Example configuration:
~~~~~~~~~~~~~~~~~~~~~~

#%PAM-1.0
auth       required     /lib/security/pam_tacplus.so debug server=123.123.123.123 secret=SECRET-123 encrypt
account	   required	/lib/security/pam_tacplus.so debug secret=SECRET-123 encrypt service=ppp protocol=lcp
password   required	/lib/security/pam_cracklib.so
password   required	/lib/security/pam_pwdb.so shadow use_authtok
session    required	/lib/security/pam_tacplus.so debug server=123.123.123.123 server=124.124.124.124 secret=SECRET-124 encrypt service=ppp protocol=lcp

(note that above are five long lines)

More on server lists:
~~~~~~~~~~~~~~~~~~~~~

1. Having more that one TACACS+ server defined for given management group
has following effects on authentication:

 	* always, if the first server on the list is unreachable or failing
	  pam_tacplus will try to authenticate user on the another one

	  in case, where there are no modifiers like `first_hit', you
	  could think the of the first server on list as primary one,
	  and the others as backup/secondary servers

	* if the `first_hit' option is specified, if the first server
	  on the list will return negative authentication reply, pam_tacplus
	  will try to ask another server; this will continue until it
	  will get positive reply from one of the servers, or all servers
	  are probed with negative replies; then pam_tacplus will return
	  with authentication failure

	  this is useful if you have e.g. dialup server authenticating
	  users who have accounts on multiple servers in your network;
	  in this case, from host B won't be authenticated by TACACS+ server
	  on host A (which is first on the list), but it will be authenticated
	  when pam_tacplus will query the server on host B next

	  in this case all the servers can be considered as having equal
	  authority in authenticating users

	* when the authentication function gets a positive reply from
	  a server, it saves its address for future use by account
	  management function (see below)

2. The account management (authorization) function asks *only one*
TACACS+ server and it ignores the whole server list passed from command
line. It uses server saved by authentication function after successful
authenticating user on that server. We assume that the server is
authoriative for queries about that user.

3. The session management (accounting) functions obtain their server lists
independently from the other functions. This allows you to account user
sessions on different servers than those used for authentication and
authorization.

	* normally, without the `acct_all' modifier, the extra servers
	  on the list will be considered as backup servers, mostly like
	  in point 1. i.e. they will be used only if the first server
	  on the list will fail to accept our accounting packets

	* with `acct_all' pam_tacplus will try to deliver the accounting
	  packets to all servers on the list; failure of one of the servers
	  will make it try another one

	  this is useful when your have several accounting, billing or
	  logging hosts and want to have the accounting information appear
	  on all of them at the same time


Short introduction to PAM via TACACS+:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This diagram should show general idea of how the whole process looks:

                                              +-----+
          Authen -user/pass valid?----------> | T S |
        /                                     | A e |
     PAM- Author -service allowed?----------> | C r |
      ^ \                                     | A v |
      |   Acct ,-----start session----------> | C e |
      |         `----stop session-----------> | S r |
  Application                                 +-----+

  *Client Host*          *Network*           *Server Host*

Consider `login' application:

1. Login accepts username and password from the user.
2. Login calls PAM function pam_authenticate() to verify if the
   supplied username/password pair is valid.
3. PAM loads pam_tacplus module (as defined in /etc/pam.d/login)
   and calls pam_sm_authenticate() function supplied by this module.
4. This function sends an encrypted packet to the TACACS+ server.
   The packet contains username and password to verify. TACACS+ server
   replied with either positive or negative response. If the reponse
   is negative, the whole thing is over ;)
5. PAM calls another function from pam_tacplus - pam_sm_acct_mgmt().
   This function is expected to verify whether the user is allowed
   to get the service he's requesting (in this case: unix shell).
   The function again verifies the permission on TACACS+ server. Assume
   the server granted the user with requested service.
6. Before user gets the shell, PAM calls one another function from
   pam_tacplus - pam_sm_open_session(). This results in sending an
   accounting START packet to the server. Among other things it contains
   the terminal user loggen in on and the time session started.
7. When user logs out, pam_sm_close_session() sends STOP packet to the
   server. The whole session is closed.

Limitations:
~~~~~~~~~~~~

Many of them for now :)

	* it's still in beta
	* only subset of TACACS+ protocol is supported; it's enough for
	  most need, though
	* only one, common `secret' can be specified
	* utilize PAM_SERVICE item obtained from PAM for TACACS+ services
	* clean options and configuration code
		
References:
~~~~~~~~~~~

TACACS+
1. ftp://ftpeng.cisco.com/pub/tacplus/tac_plus.rfc.1.76.txt
2. ftp://ftpeng.cisco.com/pub/tacplus/tac_plus.3.0.12.alpha.tar.Z

PAM
3. http://parc.power.net/morgan/Linux-PAM/index.html

Author:
~~~~~~~

Pawel Krawczyk <kravietz@ceti.com.pl>
http://ceti.pl/~kravietz/prog.html
