idnits 2.17.1 draft-morgan-pam-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 465 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. (A line matching the expected section header was found, but with an unexpected indentation: ' 2 Abstract' ) ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' 3 Introduction' ) ** The document seems to lack a Security Considerations section. (A line matching the expected section header was found, but with an unexpected indentation: ' 7 Security considerations' ) ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** There are 4 instances of too long lines in the document, the longest one being 2 characters in excess of 72. ** There are 68 instances of lines with control characters in the document. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 11, 1998) is 9383 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 452 looks like a reference Summary: 15 errors (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 PAM working group A.G. Morgan 2 Internet Draft: August 11, 1998 3 Document: draft-morgan-pam-00.txt 4 Expires: February 11, 1999 5 Obsoletes: 7 Pluggable Authentication Modules 9 1 Status of this memo 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. 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." 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). 27 2 Abstract 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). 33 3 Introduction 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 referring to a some specific entity, the label is 40 used for the purpose of protecting and allocating data resources. 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. 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. 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. 62 PAM, as discussed in this document, is a generalization of the 63 approach first introduced in [1]. 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 deem is appropriate. 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) and orthogonal to the process of authentication. 73 4 Definitions 75 Here we pose the authentication problem as one of configuring defined 76 interfaces between two entities. 78 4.1 Players in the authentication process 80 PAM reserves the following words to specify unique entities in the 81 authentication process: 83 applicant 84 the entity (user) initiating an application for service 85 [PAM associates the PAM_RUSER "item" with this requesting user]. 87 arbitrator 88 the entity (user) under who's identity the service application 89 is negotiated and with who's authority service is granted. 91 user 92 the entity (user) who's identity is being authenticated 93 [PAM associates the PAM_USER "item" with this identity]. 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 server end of 99 the transport layer connecting the server to the client. 100 PAM makes no assumptions about how data is exchanged between 101 the server and the client, only that 8-bit data can be 102 freely exchanged without corruption. 104 client 105 application providing the direct/primary interface to 106 applicant. This application is completely responsible 107 for transporting client-side data to the server. 108 PAM makes no assumptions about how data is exchanged between 109 the client and the server. 111 module 112 authentication binary that provides server-side support for 113 some (arbitrary) authentication method. 115 agent 116 authentication binary that provides client-side support for 117 some (arbitrary) authentication method. 119 4.2 Special cases 121 In the previous section (4.1) we identified the most general 122 selection of authentication participants. In the case of network 123 authentication, it is easy to ascribe identities to the defined 124 players. However, there are special (less general) cases and we 125 recognize them here. 127 The primary authentication step, when a user is directly introduced 128 into a computer system (log's on to a workstation) is a special case. 129 In this situation, the "client" and the "server" are generally one 130 application. Before authenticating such a user, the "applicant" is 131 formally unknown: PAM_RUSER is NULL. 133 5 Defined interfaces 135 Here, we discuss the formal interfaces between the players in the 136 authentication process. 138 5.1 Applicant <-> client 140 Once the client is invoked, requests to the applicant entity are 141 initiated by the client application. General clients are able to make 142 the following requests directly to an applicant: 144 echo text 145 echo error 146 prompt for echo'd text input 147 prompt for concealed text input 149 the nature of the interface provided by the client for the benefit of 150 the applicant entity is client specific and not defined by PAM. 152 5.2 Client <-> agent 154 In general, authentication schemes require more modes of exchange than 155 the four defined in the previous section (5.1). This 156 provides a role for client-loadable agents. The client and agent 157 exchange binary-messages that can have one of the following forms: 159 client -> agent 160 prompt for binary data packet using a binary packet 162 agent -> client 163 set environment variable 164 get environment variable 165 echo text 166 echo error 167 prompt for echo'd text input 168 prompt for concealed text input 170 The single defined procedure for exchange is that the client first 171 prompts the agent with a binary packet and expects to receive a binary 172 (response) packet in return. Before returning this expected binary 173 response, the agent may request an arbitrary number of exchanges with 174 the client. 176 5.3 Client <-> server 178 Once the client has established a connection with the server (the 179 nature of the transport protocol is not specified by PAM), the server 180 is responsible for driving the authentication process. 182 General servers can request the following from the client: 184 (to be redirected by the client to the applicant) 185 echo text 186 echo error 187 prompt for echo'd text response 188 prompt for concealed text response 190 (to be redirected by the client to the appropriate agent) 191 binary prompt for a binary response 193 Client side agents are required to process binary prompts. Their 194 binary responses are passed directly back to the server. 196 5.4 Server <-> module 198 Modules drive the authentication process. The server provides a 199 conversation function with which it encapsulates module-generated 200 requests and exchanges them with the client. 202 General conversation functions can support the following five 203 "conversation" requests: 205 echo text 206 echo error 207 prompt for echo'd text response 208 prompt for concealed text response 209 prompt for binary packet with binary packet 211 The server is responsible for redirecting these requests to the 212 client. 214 6 C API for defined interfaces 216 6.1 Applicant <-> client 218 No API is defined for this interface. The interface is considered to 219 be specific to the client application. Example applications include 220 terminal login, (X)windows login, machine file transfer applications. 222 All that is important is that the client application is able to 223 present the Applicant with textual output and to receive textual 224 input from the Applicant. The forms of textual exchange are listed 225 in an earlier section (5.1). Other methods of 226 data input/output are better suited to being handled via an 227 authentication agent (see next section). 229 6.2 Client <-> agent 231 This interface is concerned with the exchange of "binary prompts". A 232 binary prompt is a packet of arbitrary data packaged in the following 233 form: { 4 8-bit bytes in network order encoding an unsigned 32 bit 234 integer (length), "length" 8-bit bytes comprising up to 2^32 bytes of 235 binary data }. In other words 237 ------------------------------ 238 [ u32 | (length-4 bytes) ] 239 [ length | data ] 240 ------------------------------ 242 The composition of the "data" is not specified. 244 6.2.1 C API for interaction with agents 246 Here we list the C API with which a client application may interact 247 with one or more agents. 249 The definitions pertinent to a client having the ability to make use 250 of pluggable authentication agents, are contained in the following 251 file. 253 #include 255 The following opaque data type is defined: 257 pamc_handle_t 259 it provides a record of the "current" state of agents known to the 260 client and should be used when passing binary prompts to a client. 261 The structure of this type is undefined by this specification, and 262 will be implementation specific. 264 The following data type defines a pointer to a full data packet. 266 pamc_packet_t 268 Some functions/macros are supplied for reading and writing 32-bit 269 unsigned integers to the a packet: 271 Read a 32 bit unsigned integer from a given piece of (unaligned) memory: 273 _u32 pamc_read__u32(_u8 *x) 275 Write a 32 bit unsigned integer to some (unaligned) memory: 277 void pamc_write__u32(_u8 *x, _u32 y) writes 279 Obtain the length of a specified packet: 281 _u32 pamc_packet_length(pamc_packet_t packet) 283 Obtain a pointer to the data contents of a specified packet: 285 _u8 *pamc_packet_data(packet) 287 The main API functions for exchanging packets between agents and 288 clients: 290 Initialize pluggable client support and obtain a handle with which to 291 manage a client agent session: 293 pamc_handle_t pamc_set_path(const char *path) 295 The 'path', indicates a series of (colon `:' separated) directories in 296 which to locate agents that are permitted to mediate on behalf of the 297 client. If path is NULL, a system default is selected. 299 When closing the authentication session and severing the connection 300 between a client and a selection of agents, the following function is 301 used: 303 int pamc_end(pamc_handle_t *pch) 305 The return value for this function is one of the following: 307 PAMC_CONTROL_OK - all invoked agents are content with 308 authentication (the server is _not_ judged 309 _un_trustworthy by any agent) 311 PAMC_CONTROL_BUSY - one or more agents were unsatisfied at 312 being terminated. In general, the client 313 should terminate its connection to the 314 server and indicate to the applicant that 315 the server is untrusted. 317 The following function is intended to pre-load a specified agent. 318 This is the way that a client can demand that a server make use of 319 a specified agent. The demand is passive, insofar as the client is 320 not able to communicate its desire that this agent be used, but by 321 pre-loading the agent, the agent is in a position to cause pamc_end() 322 to return PAMC_CONTROL_BUSY when the authentication exchange is 323 completed. 325 int pamc_set_agent(pamc_handle_t pch, const char *agent_id) 327 The return value for this function is one of the following: 329 PAMC_CONTROL_OK - agent was loaded, but not initialized 331 PAMC_CONTROL_FAIL - agent was not available 333 The following functions are used to allocate and release storage 334 associated with binary packets: 336 void pamc_delete_packet(pamc_packet_t *datum_pp); 338 void pamc_new_packet(pamc_packet_t *datum_pp, int length); 340 The following function is used by the client to forward a binary packet 341 to an agent. 343 int pamc_exch_packet(pamc_handle_t pch, unsigned int control, 344 pamc_packet_t *datum_pp); 346 The values available as a "control" are listed in the next section. 347 As described above, the agent can reply with a binary packet destined 348 for the server, or a packet indicating some action on the part of the 349 client. In the latter case, the client is required to return another 350 binary packet to the agent. This agent<->client exchange continues 351 until the agent chooses to return a binary packet back to the server 352 with one of the three control values: PAMC_CONTROL_DONE (agent has 353 completed and requests no more data from server); PAM_CONTROL_EMPTY 354 (agent has no data to offer to the server, but wishes to relinquish 355 control); PAM_CONTROL_EXCHANGE (agent offers data to the server). 357 6.2.2 Control values 359 Valid control values are: 361 control value | used by | description 362 ------------------------------------------------------------------ 363 | | 364 PAMC_CONTROL_OK | client+agent | action completed 365 PAMC_CONTROL_FAIL | client+agent | action failed 366 | | 367 PAMC_CONTROL_PUTENV | agent | set envvar of client 368 PAMC_CONTROL_GETENV | agent | want envvar of client 369 PAMC_CONTROL_GETECHO | agent | echo'd prompt to applicant 370 PAMC_CONTROL_GETNOECHO | agent | secret prompt to applicant 371 PAMC_CONTROL_PUTTEXT | agent | echo text to applicant 372 | | 373 PAMC_CONTROL_SELECT | client | client selects named agent 374 PAMC_CONTROL_EXCHANGE | client | data packet (from server) 375 PAMC_CONTROL_DONE | agent | agent has completed 376 PAMC_CONTROL_BUSY | agent | agent is busy 378 Note, these control types are all to support a protocol exchange 379 between a client and an agent. As discussed in section (5.2), 380 these tokens serve to indicate the state of the data exchange between 381 client and agent. 383 6.2.3 Example "binary prompt" exchanges 385 Example exchanges (between an agent and a client) have the following 386 forms: 388 Client succeeds in loading an agent: 390 1 client->agent PAMC_CONTROL_SELECT : { 8, "agent-id" } 391 2 agent->client PAMC_CONTROL_OK : { 0, "" } 393 Client fails to load an agent: 395 1 client->agent PAMC_CONTROL_SELECT : { 8, "agent-id" } 396 2 agent->client PAMC_CONTROL_FAIL : { 0, "" } 398 Client loads an agent which sets a client environment variable 400 1 client->agent PAMC_CONTROL_SELECT : { 8, "agent-id" } 401 2 agent->client PAMC_CONTROL_PUTENV : { 10, "secret=XYZ" } 402 3 client->agent PAMC_CONTROL_OK : { 0, "" } 403 4 agent->client PAMC_CONTROL_OK : { 12, "localsec=XYZ" } 405 In all cases, the final agent->client exchange has one of the 406 following control values: 408 PAMC_CONTROL_OK - agent wants client to pass optional data to 409 server 410 PAMC_CONTROL_FAIL - unhappy agent (do not address agent again) 411 PAMC_CONTROL_DONE - agent has completed: optional data appended 412 PAMC_CONTROL_ABORT - agent distrusts server -- client should drop 413 connection immediately 415 6.3 Client <-> server 417 [This section will elaborate on be the simple requirement that the 418 client and server are able to exchange the following types of data 419 without ambiguity/confusion: 421 server->client: 422 echo text 423 echo error 424 prompt for echo'd text input 425 prompt for concealed text input 426 binary packet 427 client->server: 428 return text visibly entered by applicant 429 return text "invisibly" entered by applicant 430 return binary packet from agent 431 ] 433 6.4 Server <-> modules 435 [This section will represent the simple requirement that servers and 436 modules obey the old-PAM API with the optional extension that they 437 include support for binary prompts/packets.] 439 7 Security considerations 441 This document is devoted to standardizing authentication 442 infrastructure: everything in this document has implications for 443 security. 445 8 Contact 447 The email list for discussing issues related to this document is 448 . 450 9 References 452 [1] OSF RFC 86.0, "Unified Login with Pluggable Authentication 453 Modules (PAM)", October 1995 455 10 Author's Address 457 Andrew Morgan 458 Email: morgan@ftp.kernel.org 460 $Id: draft-morgan-pam.raw,v 1.1 1998/08/11 15:08:55 morgan Exp $