current-draft.txt

This program is a RADIUS RFC-compliant daemon, which is derived from original Livingston Enterprise

PAM working group                                              A.G. Morgan
Internet Draft:                                            October 6, 1999
Document: draft-morgan-pam-07.txt                                         
Expires: June 13, 2000                                                    
Obsoletes: draft-morgan-pam-06.txt                                        

                     Pluggable Authentication Modules                     

  1  Status of this memo

  This document is an draft specification. The latest version of this
  draft may be obtained from here:

    http://linux.kernel.org/pub/linux/libs/pam/pre/doc/

  As

    Linux-PAM-'version'-docs.tar.gz

  It is also contained in the Linux-PAM tar ball.

  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
  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 inventing new 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:

    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 encapsulated for
  	exchanges between the server and the client, only that full
  	octet sequences can be freely exchanged without corruption.

    client
  	application providing the direct/primary interface to
  	applicant.  This application is completely responsible
  	for the client end of the transport layer connecting the
  	server to the client.  PAM makes no assumptions about how data
  	is encapsulated for exchanges between the server and the
  	client, only that full octet sequences can be freely
  	exchanged without corruption.

    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.

  Here is a diagram to help orient the reader:

                           +-------+              +--------+              
                  . . . . .| agent |             .| module |              
                  .        +-------+             .+--------+              
                  V            |                 .    |                   
                  .            |                 V    |                   
             +---------+   +-------+             . +------+               
             |         |   |libpamc|             . |libpam|               
             |         |   +-------+             . +------+               
             |applicant|       |                 .    |                   
             |         |   +--------+           +----------+              
             |         |---| client |-----------|  server  |              
             +---------+   +--------+           +----------+              

  Solid lines connecting the boxes represent two-way interaction.  The
  dotted-directed lines indicate an optional connection beteween the
  plugin module (agent) and the server (applicant). In the case of the
  module, this represents the module invoking the 'conversation'
  callback function provided to libpam by the server application when it
  inititializes the libpam library. In the case of the agent, this may
  be some out-of-PAM API interaction (for example directly displaying a
  dialog box under X).

  4.2  Defined Data Types

  In this draft, we define two composite data types, the text string and
  the binary prompt. They are the data types used to communicate
  authentication requests and responses.

  4.2.1  text string

  The text string is a simple sequence of non-NUL (NUL = 0x00)
  octets. Terminated with a single NUL (0x00) octet. The character set
  employed in the octet sequence may be negotiated out of band, but
  defaults to utf-8.

                       ---------------------------                        
                       [  character data  |  NUL ]                        
                       [  octet sequence  | 0x00 ]                        
                       ---------------------------                        

  Within the rest of this text, PAM text strings are delimited with a
  pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}.

  4.2.2  binary prompt

  A binary prompt consists of a stream of octets arranged as follows:

                 ----------------------------------------                 
                 [  u32   |   u8    | (length-5 octets) ]                 
                 [ length | control |       data        ]                 
                 ----------------------------------------                 

  That is, a 32-bit unsigned integer in network byte order, a single
  unsigned byte of control information and a sequence of octets of
  length (length-5). The composition of the _data_ is context dependent
  but is generally not a concern for either the server or the client. It
  is very much the concern of modules and agents.

  For purposes of interoperability, we define the following control
  characters as legal.

            value    symbol             description                       
            -------------------------------------------------             
            0x01     PAM_BPC_OK       - continuation packet               
            0x02     PAM_BPC_SELECT   - initialization packet             
            0x03     PAM_BPC_DONE     - termination packet                
            0x04     PAM_BPC_FAIL     - unable to execute                 

  The following control characters are only legal for exchanges between
  an agent and a client (it is the responsibility of the client to
  enforce this rule in the face of a rogue server):

            0x41     PAM_BPC_GETENV   - obtain client env.var             
            0x42     PAM_BPC_PUTENV   - set client env.var                
            0x43     PAM_BPC_TEXT     - display message                   
            0x44     PAM_BPC_ERROR    - display error message             
            0x45     PAM_BPC_PROMPT   - echo'd text prompt                
            0x46     PAM_BPC_PASS     - non-echo'd text prompt            

  Note, length is always equal to the total length of the binary
  prompt and represented by a network ordered unsigned 32 bit integer.

  4.2.2.1 PAM_BPC_SELECT binary prompts

  Binary prompts of control type PAM_BPC_SELECT have a defined
  data part. It is composed of three elements:

  	{agent_id;'/';data}

  The agent_id is a sequence of characters satisfying the following
  regexp:

  	/^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/

  and has a specific form for each independent agent.

  o Agent_ids that do not contain an at-sign (@) are reserved to be
    assigned by IANA (Internet Assigned Numbers Authority). Names of
    this format MUST NOT be used without first registering with IANA.
    Registered names MUST NOT contain an at-sign (@).

  o Anyone can define additional agents by using names in the format
    name@domainname, e.g. "[e-mail]". The part following
    the at-sign MUST be a valid fully qualified internet domain name
    [RFC-1034] controlled by the person or organization defining the
    name. (Said another way, if you control the email address that
    your agent has as an identifier, they you are entitled to use
    this identifier.) It is up to each domain how it manages its local
    namespace.
   
  The '/' character is a mandatory delimiter, indicating the end of the
  agent_id. The trailing data is of a format specific to the agent with
  the given agent_id.


  4.3  Special cases

  In a previous section (4.1) we identified the most general
  selection of authentication participants.  In the case of network
  authentication, it is straightforward to ascribe identities to the
  defined participants.  However, there are also special (less general)
  cases that we recognize 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.

  Some client-server implementations (telnet for example) provide
  effective full tty connections. In these cases, the four simple text
  string prompting cases (see below) can be handled as in the primary
  login step. In other words, the server absorbs most of the overhead of
  propagating authentication messages. In these cases, there is special
  client/server support for handling binary prompts.

  5  Defined interfaces for information flow

  Here, we discuss the information exchange interfaces between the
  players in the authentication process. It should be understood that
  the server side is responsible for driving the authentication of the
  applicant. Notably, every request received by the client from the
  server must be matched with a single response from the client to the
  server.

  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 string
     echo error text string
     prompt with text string for echo'd text string input
     prompt with text string for concealed text string 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
  	binary prompt agent expecting binary prompt reply to client

     agent -> client
  	binary prompt reply from agent to clients binary prompt

  Following the acceptance of a binary prompt by the agent, the agent
  may attempt to exchange information with the client before returning
  its binary prompt reply. Permitted exchanges are binary prompts of the
  following types:

     agent -> client
  	set environment variable (A)
  	get environment variable (B)
  	echo text string (C)
  	echo error text string (D)
  	prompt for echo'd text string input (E)
  	prompt for concealed text string input (F)

  In response to these prompts, the client must legitimately respond
  with a corresponding binary prompt reply. We list a complete set of
  example exchanges, including each type of legitimate response (passes
  and a single fail):

     Type | Agent request                  | Client response              
     ---------------------------------------------------------------      
     (A)  | {13;PAM_BPC_PUTENV;"FOO=BAR"}  | {5;PAM_BPC_OK;}              
          | {10;PAM_BPC_PUTENV;"FOO="}     | {5;PAM_BPC_OK;}              
          | {9;PAM_BPC_PUTENV;"FOO"}  (*)  | {5;PAM_BPC_OK;}              
          | {9;PAM_BPC_PUTENV;"BAR"}  (*)  | {5;PAM_BPC_FAIL;}            
     ---------------------------------------------------------------      
     (B)  | {10;PAM_BPC_GETENV;"TERM"}     | {11;PAM_BPC_OK;"vt100"}      
          | {9;PAM_BPC_GETENV;"FOO"}       | {5;PAM_BPC_FAIL;}            
     ---------------------------------------------------------------      
     (C)  | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_OK;}              
          | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_FAIL;}            
     ---------------------------------------------------------------      
     (D)  | {11;PAM_BPC_TEXT;"ouch!"}      | {5;PAM_BPC_OK;}              
          | {11;PAM_BPC_TEXT;"ouch!"}      | {5;PAM_BPC_FAIL;}            
     ---------------------------------------------------------------      
     (E)  | {13;PAM_BPC_PROMPT;"login: "}  | {9;PAM_BPC_OK;"joe"}         
          | {13;PAM_BPC_PROMPT;"login: "}  | {6;PAM_BPC_OK;""}            
          | {13;PAM_BPC_PROMPT;"login: "}  | {5;PAM_BPC_FAIL;}            
     ---------------------------------------------------------------      
     (F)  | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"}         
          | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""}            
          | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;}            

  (*) Used to attempt the removal of a pre-existing environment
  variable.

  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 forwarded by the client to the applicant)
  	echo text string
  	echo error text string
  	prompt for echo'd text string response
  	prompt for concealed text string response

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

  Client side agents are required to process binary prompts.  The