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

   1 PAM working group                 ##              A.G. Morgan
   2 Internet Draft:                   ##           March 24, 1998
   3 Document: draft-morgan-pam-00.txt ##
   4 Expires: September 24, 1998       ##
   5 Obsoletes:                        ##
   6
   7 ## Pluggable Authentication Modules ##
   8
   9 #$  Status of this memo
  10
  11 This document is an Internet-Draft.  Internet-Drafts are working
  12 documents of the Internet Engineering Task Force (IETF), its areas,
  13 and its working groups.  Note that other groups may also distribute
  14 working documents as Internet-Drafts.
  15
  16 Internet-Drafts are draft documents valid for a maximum of six months
  17 and may be updated, replaced, or obsoleted by other documents at any
  18 time.  It is inappropriate to use Internet- Drafts as reference
  19 material or to cite them other than as "work in progress."
  20
  21 To view the entire list of current Internet-Drafts, please check the
  22 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
  23 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe),
  24 ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim),
  25 ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast).
  26
  27 #$  Abstract
  28
  29 This document is concerned with the definition of a general
  30 infrastructure for module based authentication.  The infrastructure is
  31 named Pluggable Authentication Modules (PAM for short).
  32
  33 #$  Introduction
  34
  35 Computers are tools.  They provide services to people and other
  36 computers (collectively we shall call these "users" entities).  In
  37 order to provide convenient, reliable and individual service to
  38 different entities, it is common for entities to be labelled.  Having
  39 defined a label as refering to a some specific entity, the label is
  40 used for the purpose of protecting and allocating data resources.
  41
  42 All modern operating systems have a notion of labelled entities and
  43 all modern operating systems face a common problem: how to
  44 authenticate the association of a predefined label with applicant
  45 entities.
  46
  47 There are as many authentication methods as one might care to count.
  48 None of them are perfect and none of them are invulnerable.  In
  49 general, any given authentication method becomes weaker over time.  It
  50 is common then for new authentication methods to be developed in
  51 response to newly discovered weaknesses in the old authentication
  52 methods.
  53
  54 The problem with reinventing authentication methods is the fact that
  55 old applications do not support them.  This contributes to an inertia
  56 that discourages the overhaul of weakly protected systems.  Another
  57 problem is that individuals (people) are frequently powerless to layer
  58 the protective authentication around their systems.  They are forced
  59 to rely on single (lowest common denominator) authentication schemes
  60 even in situations where this is far from appropriate.
  61
  62 PAM, as discussed in this document, is a generalization of the
  63 approach first introduced in [#$R#{OSF_RFC_PAM}].  In short, it is a
  64 general framework of interfaces that abstract the process of
  65 authentication.  With PAM, a service provider can custom protect
  66 individual services to the level that they deam is appropriate.
  67
  68 PAM has nothing explicit to say about transport layer encryption.
  69 Within the context of this document encryption and/or compression of
  70 data exchanges are application specific (strictly between client and
  71 server).
  72
  73 #$  Definitions
  74
  75 Here we pose the authentication problem as one of configuring defined
  76 interfaces between two entities.
  77
  78 #$$#{players}  Players in the authentication process
  79
  80 PAM reserves the following words to specify unique entities in the
  81 authentication process:
  82
  83   applicant
  84         the entity (user) initiating an application for service
  85         [PAM associates PAM_RUSER with this requesting user].
  86
  87   arbitrator
  88         the entity (user) under who's identity the service application
  89         is negotiated and with who's authority service is granted.
  90
  91   user
  92         the entity (user) who's identity is being authenticated
  93         [PAM associates PAM_USER with this identity].
  94
  95   server
  96         the application that provides service, or acts as an
  97         authenticated gateway to the requested service.  This
  98         application is completely responsible for the transport
  99         layer.  PAM makes no assumptions about how data is
 100         exchanged between the server and the client.
 101
 102   client
 103         application providing the direct/primary interface to
 104         applicant.  This application is completely responsible
 105         for transporting client-side data to the server.
 106         PAM makes no assumptions about how data is exchanged between
 107         the client and the server.
 108
 109   module
 110         authentication binary that provides server-side support for
 111         some authentication method.
 112
 113   agent
 114         authentication binary that provides client-side support for
 115         some authentication method.
 116
 117 #$$  Special cases
 118
 119 In the previous section (#{players}) we identified the most general
 120 selection of authentication participants.  In the case of network
 121 authentication, it is easy to ascribe identities to the defined
 122 players.  However, there are special (less general) cases and we
 123 recognize them here.
 124
 125 The primary authentication step, when a user is directly introduced
 126 into a computer system (log's on to a workstation) is a special case.
 127 In this situation, the "client" and the "server" are generally one
 128 application.  Before authenticating such a user, the "applicant" is
 129 formally unknown.
 130
 131 #$  Defined interfaces
 132
 133 Here, we discuss the formal interfaces between the players in the
 134 authentication process.
 135
 136 #$$#{applicant_client}  Applicant <-> client
 137
 138 Once the client is invoked, requests to the applicant entity are
 139 initiated by the client application.  General clients are able to make
 140 the following requests to an applicant:
 141
 142    echo text
 143    echo error
 144    prompt for echo'd text input
 145    prompt for concealed text input
 146
 147 the nature of the interface provided by the client for the benefit of
 148 the applicant entity is client specific and not defined by PAM.
 149
 150 #$$  Client <-> agent
 151
 152 In general, authentication schemes require more modes of exchange than
 153 the four defined in the previous section (#{applicant_client}).  This
 154 provides a role for client-loadable agents.  The client and agent
 155 exchange binary-messages that can have one of the following forms:
 156
 157    client -> agent
 158         prompt for binary data packet using a binary packet
 159
 160    agent -> client
 161         set environment variable
 162         get environment variable
 163         echo text
 164         echo error
 165         prompt for echo'd text input
 166         prompt for concealed text input
 167
 168 The single defined procedure for exchange is that the client first
 169 prompts the agent with a binary packet and expects to receive a binary
 170 (response) packet in return.  Before returning the binary response,
 171 the agent may request an arbitrary number of exchanges with the client.
 172
 173 #$$  Client <-> server
 174
 175 Once the client has established a connection with the server (the
 176 nature of the transport protocol is not specified by PAM), the server
 177 is reponsible for driving the authentication process.
 178
 179 General servers can request the following from the client:
 180
 181    (directed to the applicant)
 182         echo text
 183         echo error
 184         prompt for echo'd text response
 185         prompt for concealed text response
 186
 187    (directed to the appropriate agent)
 188         binary prompt for a binary response
 189
 190 Client side agents are required to process binary prompts.  Their
 191 binary responses are passed directly back to the server.
 192
 193 #$$  Server <-> module
 194
 195 Modules drive the authentication process.  The server provides a
 196 conversation function with which it encapsulates module-generated
 197 requests and exchanges them with the client.
 198
 199 General conversation functions can support the following five
 200 "conversation" requests:
 201
 202    echo text
 203    echo error
 204    prompt for echo'd text response
 205    prompt for concealed text response
 206    prompt for binary packet with binary packet
 207
 208 The server is responsible for redirecting these requests to the
 209 client.
 210
 211 #$  C API for defined interfaces
 212
 213 #$$  Applicant <-> client
 214
 215 No API is defined for this interface.  The interface is considered to
 216 be specific to the client application.  Example applications include
 217 terminal login, (X)windows login, machine file transfer applications.
 218
 219 #$$  Client <-> agent
 220
 221 This interface is concerned with the exchange of "binary prompts".  A
 222 binary prompt has the following form: { 4 8-bit bytes in network order
 223 encoding an unsigened 32 bit integer (length), 4 8-bit bytes in
 224 network order encoding an unsigened 32 bit integer (control),
 225 "length-4" 8-bit bytes bytes comprising upto 2^32-4 bytes of binary
 226 data }.
 227
 228 ## [  u32   |   u32   |  (length-4 bytes) ] ##
 229 ##   length   control          data         ##
 230
 231 The composition of the "data" is not specified.  Valid control values
 232 are:
 233
 234 ##control value          | used by      | description               ##
 235 ##------------------------------------------------------------------##
 236 ##                       |              |                           ##
 237 ##PAMC_CONTROL_OK        | agent        | agent is happy            ##
 238 ##PAMC_CONTROL_FAIL      | agent        | agent failed              ##
 239 ##PAMC_CONTROL_BUSY      | agent        | agent is busy             ##
 240 ##PAMC_CONTROL_PUTENV    | agent        | set envvar of client      ##
 241 ##PAMC_CONTROL_GETENV    | agent        | want envvar of client     ##
 242 ##PAMC_CONTROL_GETECHO   | agent        | echo'd prompt to applicant##
 243 ##PAMC_CONTROL_GETNOECHO | agent        | secret prompt to applicant##
 244 ##PAMC_CONTROL_PUTTEXT   | agent        | echo text to applicant    ##
 245 ##PAMC_CONTROL_SELECT    | client       | client selects named agent##
 246 ##PAMC_CONTROL_EXCHANGE  | client+agent | data exchange packet      ##
 247 ##PAMC_CONTROL_DONE      | agent        | agent has completed       ##
 248 ##PAMC_CONTROL_EMPTY     | agent        | agent has no reply        ##
 249
 250 #$  Security considerations
 251
 252 This document is devoted to standardizing authentication
 253 infrastructure: everything in this document has implications for
 254 security.
 255
 256 #$  Contact
 257
 258 The email list for discussing issues related to this document is
 259 <pam-list@redhat.com>.
 260
 261 #$  References
 262
 263 [#{OSF_RFC_PAM}]  OSF RFC 86.0, "Unified Login with Pluggable Authentication
 264      Modules (PAM)", October 1995
 265
 266 #$  Author's Address
 267
 268 Andrew Morgan
 269 Email: morgan@ftp.kernel.org
 270