PAM working group A.G. Morgan Internet Draft: August 11, 1998 Document: draft-morgan-pam-00.txt Expires: February 11, 1999 Obsoletes: 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 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 [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 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 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 exchanged between the server and the client, only that 8-bit data can be freely exchanged without corruption. 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 (arbitrary) authentication method. agent 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 client. 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 file. #include <security/pam_client.h> The following opaque data type is defined: pamc_handle_t 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. pamc_packet_t 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 clients: 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 used: 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 completed. 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 forms: 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 server 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: server->client: echo text echo error prompt for echo'd text input prompt for concealed text input binary packet client->server: 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 security. 8 Contact The email list for discussing issues related to this document is <pam-list@redhat.com>. 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 $