path: root/contrib/libpam/doc/specs/draft-morgan-pam-00.raw

PAM working group                 ##              A.G. Morgan
Internet Draft:                   ##           March 24, 1998
Document: draft-morgan-pam-00.txt ##
Expires: September 24, 1998       ##
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 refering 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 deam 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).

#$  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 PAM_RUSER with this requesting user].

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

  user
	the entity (user) who's identity is being authenticated
	[PAM associates PAM_USER 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 transport
	layer.  PAM makes no assumptions about how data is
	exchanged between the server and the client.

  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 authentication method.

  agent
	authentication binary that provides client-side support for
	some 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.

#$  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 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

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 the 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 reponsible for driving the authentication process.

General servers can request the following from the client:

   (directed to the applicant)
	echo text
	echo error
	prompt for echo'd text response
	prompt for concealed text response

   (directed 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.

#$$  Client <-> agent

This interface is concerned with the exchange of "binary prompts".  A
binary prompt has the following form: { 4 8-bit bytes in network order
encoding an unsigened 32 bit integer (length), 4 8-bit bytes in
network order encoding an unsigened 32 bit integer (control),
"length-4" 8-bit bytes bytes comprising upto 2^32-4 bytes of binary
data }.

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

The composition of the "data" is not specified.  Valid control values
are:

##control value          | used by      | description               ##
##------------------------------------------------------------------##
##                       |              |                           ##
##PAMC_CONTROL_OK        | agent        | agent is happy            ##
##PAMC_CONTROL_FAIL      | agent        | agent failed              ##
##PAMC_CONTROL_BUSY      | agent        | agent is busy             ##
##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+agent | data exchange packet      ##
##PAMC_CONTROL_DONE      | agent        | agent has completed       ##
##PAMC_CONTROL_EMPTY     | agent        | agent has no reply        ##

#$  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