[Search] [txt|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00                                                            
PAM working group                                              A.G. Morgan
Internet Draft:                                            August 11, 1998
Document: draft-morgan-pam-00.txt
Expires: February 11, 1999

                     Pluggable Authentication Modules

  1  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).

  2  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).

  3  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

  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

  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 [1].  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.

  4  Definitions

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

  4.1  Players in the authentication process

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

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

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

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

        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.

        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.

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

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

  4.2  Special cases

  In the previous section (4.1) 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.

  5  Defined interfaces

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

  5.1  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.

  5.2  Client <-> agent

  In general, authentication schemes require more modes of exchange than
  the four defined in the previous section (5.1).  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.

  5.3  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.

  5.4  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

  6  C API for defined interfaces

  6.1  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 (5.1).  Other methods of
  data input/output are better suited to being handled via an
  authentication agent (see next section).

  6.2  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.

  6.2.1 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

    #include <security/pam_client.h>

  The following opaque data type is defined:


  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.


  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

  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

    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

    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).

  6.2.2 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 (5.2),
  these tokens serve to indicate the state of the data exchange between
  client and agent.

  6.2.3 Example "binary prompt" exchanges

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

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

  6.3 Client <-> server

  [This section will elaborate on be the simple requirement that the
  client and server are able to exchange the following types of data
  without ambiguity/confusion:

                echo text
                echo error
                prompt for echo'd text input
                prompt for concealed text input
                binary packet
                return text visibly entered by applicant
                return text "invisibly" entered by applicant
                return binary packet from agent

  6.4 Server <-> modules

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

  7  Security considerations

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

  8  Contact

  The email list for discussing issues related to this document is

  9  References

  [1]  OSF RFC 86.0, "Unified Login with Pluggable Authentication
       Modules (PAM)", October 1995

  10  Author's Address

  Andrew Morgan
  Email: morgan@ftp.kernel.org

     $Id: draft-morgan-pam.raw,v 1.1 1998/08/11 15:08:55 morgan Exp $