PAM working group                 ##              A.G. Morgan
Internet Draft:                   ##           Whenever, 1998
Document: draft-morgan-pam-02.txt ##
Expires: whenever+6 months        ##
Obsoletes:                        ##

## Pluggable Authentication Modules ##

#$  Status of this memo

This document is an Internet-Draft.  Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups.  Note that other groups may also distribute
working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time.  It is inappropriate to use Internet- Drafts as reference
material or to cite them other than as "work in progress."

To view the entire list of current Internet-Drafts, please check the
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe),
ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim),
ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast).

#$  Abstract

This document is concerned with the definition of a general
infrastructure for module based authentication.  The infrastructure is
named Pluggable Authentication Modules (PAM for short).

#$  Introduction

Computers are tools.  They provide services to people and other
computers (collectively we shall call these "users" entities).  In
order to provide convenient, reliable and individual service to
different entities, it is common for entities to be labelled.  Having
defined a label as referring to a some specific entity, the label is
used for the purpose of protecting and allocating data resources.

All modern operating systems have a notion of labelled entities and
all modern operating systems face a common problem: how to
authenticate the association of a predefined label with applicant
entities.

There are as many authentication methods as one might care to count.
None of them are perfect and none of them are invulnerable.  In
general, any given authentication method becomes weaker over time.  It
is common then for new authentication methods to be developed in
response to newly discovered weaknesses in the old authentication
methods.

The problem with reinventing authentication methods is the fact that
old applications do not support them.  This contributes to an inertia
that discourages the overhaul of weakly protected systems.  Another
problem is that individuals (people) are frequently powerless to layer
the protective authentication around their systems.  They are forced
to rely on single (lowest common denominator) authentication schemes
even in situations where this is far from appropriate.

PAM, as discussed in this document, is a generalization of the
approach first introduced in [#$R#{OSF_RFC_PAM}].  In short, it is a
general framework of interfaces that abstract the process of
authentication.  With PAM, a service provider can custom protect
individual services to the level that they deem is appropriate.

PAM has nothing explicit to say about transport layer encryption.
Within the context of this document encryption and/or compression of
data exchanges are application specific (strictly between client and
server) and orthogonal to the process of authentication.

#$  Definitions

Here we pose the authentication problem as one of configuring defined
interfaces between two entities.

#$$#{players}  Players in the authentication process

PAM reserves the following words to specify unique entities in the
authentication process:

  applicant
	the entity (user) initiating an application for service
	[PAM associates the PAM_RUSER "item" with this requesting user].

  arbitrator
	the entity (user) under whose identity the service application
	is negotiated and with whose authority service is granted.

  user
	the entity (user) whose identity is being authenticated
	[PAM associates the PAM_USER "item" with this identity].

  server
	the application that provides service, or acts as an
	authenticated gateway to the requested service.  This
	application is completely responsible for the server end of
	the transport layer connecting the server to the client.
	PAM makes no assumptions about how data is exchanged between
	the server and the client, only that 8-bit data can be
	freely exchanged without corruption.

  client
	application providing the direct/primary interface to
	applicant.  This application is completely responsible
	for transporting client-side data to the server.
	PAM makes no assumptions about how data is exchanged between
	the client and the server.

  module
	authentication binary that provides server-side support for
	some (arbitrary) authentication method.

  agent
	authentication binary that provides client-side support for
	some (arbitrary) authentication method.

#$$  Special cases

In the previous section (#{players}) we identified the most general
selection of authentication participants.  In the case of network
authentication, it is easy to ascribe identities to the defined
players.  However, there are special (less general) cases and we
recognize them here.

The primary authentication step, when a user is directly introduced
into a computer system (log's on to a workstation) is a special case.
In this situation, the "client" and the "server" are generally one
application.  Before authenticating such a user, the "applicant" is
formally unknown: PAM_RUSER is NULL.

#$  Defined interfaces

Here, we discuss the formal interfaces between the players in the
authentication process.

#$$#{applicant_client}  Applicant <-> client

Once the client is invoked, requests to the applicant entity are
initiated by the client application.  General clients are able to make
the following requests directly to an applicant:

   echo text
   echo error
   prompt for echo'd text input
   prompt for concealed text input

the nature of the interface provided by the client for the benefit of
the applicant entity is client specific and not defined by PAM.

#$$#{client_agent}  Client <-> agent

In general, authentication schemes require more modes of exchange than
the four defined in the previous section (#{applicant_client}).  This
provides a role for client-loadable agents.  The client and agent
exchange binary-messages that can have one of the following forms:

   client -> agent
	prompt for binary data packet using a binary packet

   agent -> client
	set environment variable
	get environment variable
	echo text
	echo error
	prompt for echo'd text input
	prompt for concealed text input

The single defined procedure for exchange is that the client first
prompts the agent with a binary packet and expects to receive a binary
(response) packet in return.  Before returning this expected binary
response, the agent may request an arbitrary number of exchanges with
the client.

#$$  Client <-> server

Once the client has established a connection with the server (the
nature of the transport protocol is not specified by PAM), the server
is responsible for driving the authentication process.

General servers can request the following from the client:

   (to be redirected by the client to the applicant)
	echo text
	echo error
	prompt for echo'd text response
	prompt for concealed text response

   (to be redirected by the client to the appropriate agent)
	binary prompt for a binary response

Client side agents are required to process binary prompts.  Their
binary responses are passed directly back to the server.

#$$  Server <-> module

Modules drive the authentication process.  The server provides a
conversation function with which it encapsulates module-generated
requests and exchanges them with the client.

General conversation functions can support the following five 
"conversation" requests:

   echo text
   echo error
   prompt for echo'd text response
   prompt for concealed text response
   prompt for binary packet with binary packet

The server is responsible for redirecting these requests to the
client.

#$  C API for defined interfaces

#$$  Applicant <-> client

No API is defined for this interface.  The interface is considered to
be specific to the client application.  Example applications include
terminal login, (X)windows login, machine file transfer applications.

All that is important is that the client application is able to
present the Applicant with textual output and to receive textual
input from the Applicant.  The forms of textual exchange are listed
in an earlier section (#{applicant_client}).  Other methods of
data input/output are better suited to being handled via an
authentication agent (see next section).

#$$  Client <-> agent

This interface is concerned with the exchange of "binary prompts".  A
binary prompt is a packet of arbitrary data packaged in the following
form: { 4 8-bit bytes in network order encoding an unsigned 32 bit
integer (length), "length" 8-bit bytes comprising up to 2^32 bytes of
binary data }.  In other words

## ------------------------------ ##
## [  u32   |  (length-4 bytes) ] ##
## [ length |        data       ] ##
## ------------------------------ ##

The composition of the "data" is not specified.

#$$$ C API for interaction with agents

Here we list the C API with which a client application may interact
with one or more agents.

The definitions pertinent to a client having the ability to make use
of pluggable authentication agents, are contained in the following
file.

  \#include <security/pam_client.h>

The following opaque data type is defined:

  pamc_handle_t

it provides a record of the "current" state of agents known to the
client and should be used when passing binary prompts to a client.
The structure of this type is undefined by this specification, and
will be implementation specific.

The following data type defines a pointer to a full data packet.

  pamc_packet_t

Some functions/macros are supplied for reading and writing 32-bit
unsigned integers to the a packet:

Read a 32 bit unsigned integer from a given piece of (unaligned) memory:

  _u32 pamc_read__u32(_u8 *x)

Write a 32 bit unsigned integer to some (unaligned) memory:

  void pamc_write__u32(_u8 *x, _u32 y)  writes 

Obtain the length of a specified packet:

  _u32 pamc_packet_length(pamc_packet_t packet)

Obtain a pointer to the data contents of a specified packet:

  _u8 *pamc_packet_data(packet)


The main API functions for exchanging packets between agents and
clients:

Initialize pluggable client support and obtain a handle with which to
manage a client agent session:

  pamc_handle_t pamc_set_path(const char *path)

The 'path', indicates a series of (colon `:' separated) directories in
which to locate agents that are permitted to mediate on behalf of the
client.  If path is NULL, a system default is selected.

When closing the authentication session and severing the connection
between a client and a selection of agents, the following function is
used:

  int pamc_end(pamc_handle_t *pch)

The return value for this function is one of the following:

  PAMC_CONTROL_OK	- all invoked agents are content with
			  authentication (the server is _not_ judged
			  _un_trustworthy by any agent)

  PAMC_CONTROL_BUSY	- one or more agents were unsatisfied at
			  being terminated.  In general, the client
			  should terminate its connection to the
			  server and indicate to the applicant that
			  the server is untrusted.


The following function is intended to pre-load a specified agent.
This is the way that a client can demand that a server make use of
a specified agent.  The demand is passive, insofar as the client is
not able to communicate its desire that this agent be used, but by
pre-loading the agent, the agent is in a position to cause pamc_end()
to return PAMC_CONTROL_BUSY when the authentication exchange is
completed. 

  int pamc_set_agent(pamc_handle_t pch, const char *agent_id)

The return value for this function is one of the following:

  PAMC_CONTROL_OK	- agent was loaded, but not initialized

  PAMC_CONTROL_FAIL	- agent was not available


The following functions are used to allocate and release storage
associated with binary packets:

  void pamc_delete_packet(pamc_packet_t *datum_pp);

  void pamc_new_packet(pamc_packet_t *datum_pp, int length);

The following function is used by the client to forward a binary packet
to an agent.

  int pamc_exch_packet(pamc_handle_t pch, unsigned int control,
		       pamc_packet_t *datum_pp);

The values available as a "control" are listed in the next section.
As described above, the agent can reply with a binary packet destined
for the server, or a packet indicating some action on the part of the
client.  In the latter case, the client is required to return another
binary packet to the agent.  This agent<->client exchange continues
until the agent chooses to return a binary packet back to the server
with one of the three control values: PAMC_CONTROL_DONE (agent has
completed and requests no more data from server); PAM_CONTROL_EMPTY
(agent has no data to offer to the server, but wishes to relinquish
control); PAM_CONTROL_EXCHANGE (agent offers data to the server).

#$$$ Control values

Valid control values are:

##control value          | used by      | description               ##
##------------------------------------------------------------------##
##                       |              |                           ##
##PAMC_CONTROL_OK        | client+agent | action completed          ##
##PAMC_CONTROL_FAIL      | client+agent | action failed             ##
##                       |              |                           ##
##PAMC_CONTROL_PUTENV    | agent        | set envvar of client      ##
##PAMC_CONTROL_GETENV    | agent        | want envvar of client     ##
##PAMC_CONTROL_GETECHO   | agent        | echo'd prompt to applicant##
##PAMC_CONTROL_GETNOECHO | agent        | secret prompt to applicant##
##PAMC_CONTROL_PUTTEXT   | agent        | echo text to applicant    ##
##                       |              |                           ##
##PAMC_CONTROL_SELECT    | client       | client selects named agent##
##PAMC_CONTROL_EXCHANGE  | client       | data packet (from server) ##
##PAMC_CONTROL_DONE      | agent        | agent has completed       ##
##PAMC_CONTROL_BUSY      | agent        | agent is busy             ##

Note, these control types are all to support a protocol exchange
between a client and an agent.   As discussed in section (#{client_agent}),
these tokens serve to indicate the state of the data exchange between
client and agent.

#$$$ Example "binary prompt" exchanges

Example exchanges (between an agent and a client) have the following
forms:

 Client succeeds in loading an agent:

    1  client->agent	PAMC_CONTROL_SELECT : { 8, "agent-id" }
    2  agent->client	PAMC_CONTROL_OK : { 0, "" }

 Client fails to load an agent:

    1  client->agent	PAMC_CONTROL_SELECT : { 8, "agent-id" }
    2  agent->client	PAMC_CONTROL_FAIL : { 0, "" }

 Client loads an agent which sets a client environment variable

    1 client->agent	PAMC_CONTROL_SELECT : { 8, "agent-id" }
    2 agent->client	PAMC_CONTROL_PUTENV : { 10, "secret=XYZ" }
    3 client->agent	PAMC_CONTROL_OK : { 0, "" }
    4 agent->client	PAMC_CONTROL_OK : { 12, "localsec=XYZ" }

In all cases, the final agent->client exchange has one of the
following control values:

  PAMC_CONTROL_OK	- agent wants client to pass optional data to
                          server
  PAMC_CONTROL_FAIL	- unhappy agent (do not address agent again)
  PAMC_CONTROL_DONE	- agent has completed: optional data appended
  PAMC_CONTROL_ABORT	- agent distrusts server -- client should drop
			  connection immediately

#$$ Client <-> server

This interface is concerned with the exchange of text and data prompts
between the client application and the server application.  The
requirement here is that there is a defined way, within the transport
protocol, shared by client and server to transfer the following types
of message:

	server->client:
		echo text
		echo error
		prompt for echo'd text input
		prompt for concealed text input
		binary packet

	client->server:
		return text visibly entered by applicant
		return text "invisibly" entered by applicant
		return binary packet from agent

How this is acheived is completely independent of PAM.  The data can
be sent in any form, packaged in any way.  All that is required is
that each of the above "message exchanges" be supported.

#$$$ C API for interaction between server and client

No API is defined for this interface.  The way that this interface is
implemented will be application specific.

#$$ Server <-> modules

[This section will represent the simple requirement that servers and
modules obey the old-PAM API with the extension that they include
support for binary prompts/packets.]

#$  Security considerations

This document is devoted to standardizing authentication
infrastructure: everything in this document has implications for
security.

#$  Contact

The email list for discussing issues related to this document is
<pam-list@redhat.com>.

#$  References

[#{OSF_RFC_PAM}]  OSF RFC 86.0, "Unified Login with Pluggable Authentication
     Modules (PAM)", October 1995

#$  Author's Address

Andrew Morgan
Email: morgan@ftp.kernel.org

## $Id: draft-morgan-pam.raw,v 1.2 1998/09/13 20:25:13 morgan Exp $ ##

