summaryrefslogtreecommitdiff
path: root/doc/specs/draft-morgan-pam.raw
diff options
context:
space:
mode:
authorSteve Langasek <steve.langasek@ubuntu.com>2019-01-03 12:44:11 -0800
committerSteve Langasek <steve.langasek@ubuntu.com>2019-01-03 12:44:11 -0800
commitefd31890b5ed496a5a00c08a262da240e66a4ddc (patch)
tree22a7aab22b3a491bb58df250d7d6409e0c160bcc /doc/specs/draft-morgan-pam.raw
parent067affee9267fa0d1c21835182ba639ba33e820f (diff)
New upstream version 0.76
Diffstat (limited to 'doc/specs/draft-morgan-pam.raw')
-rw-r--r--doc/specs/draft-morgan-pam.raw764
1 files changed, 0 insertions, 764 deletions
diff --git a/doc/specs/draft-morgan-pam.raw b/doc/specs/draft-morgan-pam.raw
deleted file mode 100644
index 45109f45..00000000
--- a/doc/specs/draft-morgan-pam.raw
+++ /dev/null
@@ -1,764 +0,0 @@
-Open-PAM working group ## A.G. Morgan
-Internet Draft: ## Dec 8, 2001
-Document: draft-morgan-pam-08.txt ##
-Expires: June 8, 2002 ##
-Obsoletes: draft-morgan-pam-07.txt##
-
-## Pluggable Authentication Modules (PAM) ##
-
-#$ Status of this memo
-
-This document is a draft specification. Its contents are subject to
-change with revision. The latest version of this draft may be obtained
-from here:
-
- http://www.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.
-
-#$ 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).
-
-#$ 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 [#$R#{OSF_RFC_PAM}]. 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.
-
-#$ Definitions
-
-Here we pose the authentication problem as one of configuring defined
-interfaces between two entities.
-
-#$$#{players} 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).
-
-#$$ 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.
-
-#$$$#{text_string} 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}.
-
-#$$$#{binary_prompt} 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 ##
-## 0x46 PAM_BPC_STATUS - ping all active clients##
-## 0x47 PAM_BPC_ABORT - please abort session ##
-
-Note, length is always equal to the total length of the binary
-prompt and represented by a network ordered unsigned 32 bit integer.
-
-#$$$$#{agent_ids} 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 to be considered as
- representing some authentication mode that is a "public
- standard" see reference [#$R#{PAM_STD_AGENTIDS}]. Registered names
- MUST NOT contain an at-sign (@).
-
-o Anyone can define additional agents by using names in the format
- name@domainname, e.g. "ouragent@example.com". 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.
-
-
-#$$ Special cases
-
-In a previous section (#{players}) 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 needs to be
-special client/server support for handling binary prompts.
-
-In some circumstances, a legacy network transfer protocol can carry
-authentication information. In such cases, a desire to support legacy
-clients (with no client-side support for PAM) will neccessitate the
-'hardcoding' of an agent protocol into the server application. Whilst
-against the spirit of PAM, this special casing can be managed by the
-server's 'conversation function' (see below). The guiding principle
-when implementing such support is for the application developer to
-relegate the authentication process to the PAM module -- simply
-performing a transcription of data from binary-prompt to legacy
-network 'packet' and visa-versa for propagating replies back to the
-driving PAM module. A common case of this is with network protocols
-that define an initialization packet of "user+password". In such cases
-one should attempt to support the "userpass" agent-id and its defined
-protocol.
-
-#$ 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.
-
-#$$#{applicant_client} 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.
-
-#$$#{client_agent} Client <-> agent
-
-In general, authentication schemes require more modes of exchange than
-the four defined in the previous section (#{applicant_client}). 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_ERROR;"ouch!"} | {5;PAM_BPC_OK;} ##
-## | {11;PAM_BPC_ERROR;"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.
-
-#$$ 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
-agents' binary prompt responses are returned to the server.
-
-#$$ 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. Every message sent by a
-module should be acknowledged.
-
-General conversation functions can support the following five
-conversation requests:
-
- echo text string
- echo error string
- prompt for echo'd text string response
- prompt for concealed text string response
- binary prompt for binary prompt response
-
-The server is responsible for redirecting these requests to the
-client.
-
-#$ C API for application interfaces (client and server)
-
-#$$ 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 (#{applicant_client}). Other methods of
-data input/output are better suited to being handled via an
-authentication agent.
-
-#$$ Client <-> agent
-
-The client makes use of a general API for communicating with
-agents. The client is not required to communicate directly with
-available agents, instead a layer of abstraction (in the form of a
-library: libpamc) takes care of loading and maintaining communication
-with all requested agents. This layer of abstraction will choose which
-agents to interact with based on the content of binary prompts it
-receives that have the control type PAM_BPC_SELECT.
-
-#$$$ Client <-> libpamc
-
-#$$$$ Compilation information
-
-The C-header file provided for client-agent abstraction is included
-with the following source line:
-
- \#include <security/pam_client.h>
-
-The library providing the corresponding client-agent abstraction
-functions is, libpamc.
-
- cc .... -lpamc
-
-#$$$$ Initializing libpamc
-
-The libpamc library is initialized with a call to the following
-function:
-
- pamc_handle_t pamc_start(void);
-
-This function is responsible for configuring the library and
-registering the location of available agents. The location of the
-available agents on the system is implementation specific.
-
-pamc_start() function returns NULL on failure. Otherwise, the return
-value is a pointer to an opaque data type which provides a handle to
-the libpamc library. On systems where threading is available, the
-libpamc libraray is thread safe provided a single (pamc_handler_t *)
-is used by each thread.
-
-#$$$$ Client (Applicant) selection of agents
-
-For the purpose of applicant and client review of available agents,
-the following function is provided.
-
- char **pamc_list_agents(pamc_handle_t pch);
-
-This returns a list of pointers to the agent_id's of the agents which
-are available on the system. The list is terminated by a NULL pointer.
-It is the clients responsibility to free this memory area by calling
-free() on each agent id and the block of agent_id pointers in the
-result.
-
-PAM represents a server-driven authentication model, so by default
-any available agent may be invoked in the authentication process.
-
-#$$$$$ Client demands agent
-
-If the client requires that a specific authentication agent is
-satisfied during the authentication process, then the client should
-call the following function, immediately after obtaining a
-pamc_handle_t from pamc_start().
-
- int pamc_load(pamc_handle_t pch, const char *agent_id);
-
-agent_id is a PAM text string (see section #{agent_ids}) and is not
-suffixed with a '/' delimiter. The return value for this function is:
-
- PAM_BPC_TRUE - agent located and loaded.
- PAM_BPC_FALSE - agent is not available.
-
-Note, although the agent is loaded, no data is fed to it. The agent's
-opportunity to inform the client that it does not trust the server is
-when the agent is shutdown.
-
-#$$$$$ Client marks agent as unusable
-
-The applicant might prefer that a named agent is marked as not
-available. To do this, the client would invoke the following function
-immediately after obtaining a pamc_handle_t from pam_start().
-
- int pamc_disable(pamc_handle_t pch, const char *agent_id);
-
-here agent_id is a PAM text string containing an agent_id (section
-#{agent_ids}).
-
-The return value for this function is:
-
- PAM_BPC_TRUE - agent is disabled. This is the response
- independent of whether the agent is locally
- available.
-
- PAM_BPC_FALSE - agent cannot be disabled (this may be because
- it has already been invoked).
-
-#$$$$ Allocating and manipulating binary prompts
-
-All conversation between an client and an agent takes place with
-respect to binary prompts. A binary prompt (see section #{binary_prompt}), is
-obtained, resized and deleted via the following C-macro:
-
- CREATION of a binary prompt with control X1 and data length Y1:
-
- pamc_bp_t prompt = NULL;
- PAM_BP_RENEW(&prompt, X1, Y1);
-
- REPLACEMENT of a binary prompt with a control X2 and data length Y2:
-
- PAM_BP_RENEW(&prompt, X2, Y2);
-
- DELETION of a binary prompt (the referenced prompt is scrubbed):
-
- PAM_BP_RENEW(&prompt, 0, 0);
-
-Note, the PAM_BP_RENEW macro always overwrites any prompt that you
-call it with, deleting and liberating the old contents in a secure
-fashion. Also note that PAM_BP_RENEW, when returning a prompt of data
-size Y1>0, will always append a '\0' byte to the end of the prompt (at
-data offset Y1). It is thus, by definition, acceptable to treat the
-data contents of a binary packet as a text string (see #{text_string}).
-
- FILLING a binary prompt from a memory pointer U1 from offset O1 of
- length L1:
-
- PAM_BP_FILL(prompt, O1, L1, U1);
-
- the CONTROL type for the packet can be obtained as follows:
-
- control = PAM_PB_CONTROL(prompt);
-
- the LENGTH of a data within the prompt (_excluding_ its header
- information) can be obtained as follows:
-
- length = PAM_BP_LENGTH(prompt);
-
- the total SIZE of the prompt (_including_ its header information)
- can be obtained as follows:
-
- size = PAM_BP_SIZE(prompt);
-
- EXTRACTING data from a binary prompt from offset O2 of length L2 to
- a memory pointer U2:
-
- PAM_BP_EXTRACT(prompt, O2, L2, U2);
-
- If you require direct access to the raw prompt DATA, you should use
- the following macro:
-
- __u8 *raw_data = PAM_BP_DATA(prompt);
-
-#$$$$ Client<->agent conversations
-
-All exchanges of binary prompts with agents are handled with the
-single function:
-
- int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p);
-
-The return value for pamc_converse(...) is PAM_BPC_TRUE when there is
-a response packet and PAM_BPC_FALSE when the client is unable to
-handle the request represented by the original prompt. In this latter
-case, *prompt_p is set to NULL.
-
-This function takes a binary prompt and returns a replacement binary
-prompt that is either a request from an agent to be acted upon by the
-client or the 'result' which should be forwarded to the server. In the
-former case, the following macro will return 1 (PAM_BPC_TRUE) and in
-all other cases, 0 (PAM_BPC_FALSE):
-
- PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt)
-
-Note, all non-NULL binary prompts returned by pamc_converse(...), are
-terminated with a '\0', even when the full length of the prompt (as
-returned by the agent) does not contain this delimiter. This is a
-defined property of the PAM_BP_RENEW macro, and can be relied upon.
-
-Important security note: in certain implementations, agents are
-implemented by executable binaries, which are transparently loaded and
-managed by the PAM client library. To ensure there is never a leakage
-of elevated privilege to an unprivileged agent, the client application
-should go to some effort to lower its level of privilege. It remains
-the responsibility of the applicant and the client to ensure that it
-is not compromised by a rogue agent.
-
-#$$$$ Status of agents
-
- int pamc_status(pamc_handle_t *pch, pamc_bp_t *prompt_p);
-
-At any time, the client may ping all active agents for their status
-(with a PAM_BPC_STATUS binary prompt). If any agent replies with
-PAM_BPC_ABORT, the client is responsible for terminating the
-connection to the server and then terminating all agents with a call
-to pamc_end(). In such cases, the return value of pamc_status() is
-PAM_BPC_FALSE.
-
-If the return status of pamc_status() is PAM_BPC_TRUE and *prompt_p is
-non-NULL, then an agent is requesting access to a server module.
-
-XXX - how this information gets propagated to the server, and
- ultimately to the server's module is yet to be determined.
-
-#$$$$ Termination of agents
-
-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);
-
-Following a call to pamc_end, the pamc_handle_t will be invalid.
-
-The return value for this function is one of the following:
-
- PAM_BPC_TRUE - all invoked agents are content with
- authentication (the server is _not_ judged
- _un_trustworthy by any agent)
-
- PAM_BPC_FALSE - 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.
-
-#$$$ libpamc <-> agents
-
-The agents are manipulated from within libpamc. Each agent is an
-executable in its own right. This permits the agent to have access to
-sensitive data not accessible directly from the client. The mode of
-communication between libpamc and an agent is through a pair of
-pipes. The agent reads binary prompts (section #{binary_prompt})
-through its standard input file descriptor and writes response (to the
-server) binary prompts and instruction binary prompts (instructions
-for the client) through its standard output file descriptor.
-
-#$$ Client <-> server
-
-This interface is concerned with the exchange of text and binary
-prompts between the client application and the server application. No
-API is provided for this as it is considered specific to the transport
-protocol shared by the client and the server.
-
-#$$ Server <-> modules
-
-The server makes use of a general API for communicating with
-modules. The client is not required to communicate directly with
-available modules. By abstracting the authentication interface, it
-becomes possible for the local administrator to make a run time
-decision about the authentication method adopted by the server.
-
-#$$$ Functions and definitions available to servers and modules
-
-[This section will document the following functions
-
- pam_set_item()
- pam_get_item()
- pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec)
- pam_get_env(pam_handle_t *pamh, const char *varname)
- pam_strerror(pam_handle_t *pamh, int pam_errno)
-
-Event driven support (XXX work in progress)
-
- pam_register_event() - app or module associates an event poller/handler
- pam_select_event() - query for any outstanding event and act on any
-]
-
-#$$$ Server <-> libpam
-
-[This section will document the following pam_ calls:
-
- pam_start
- pam_end
- pam_authenticate (*)
- pam_setcred
- pam_acct_mgmt
- pam_open_session
- pam_close_session
- pam_chauthtok (*)
-
-The asterisked functions may return PAM_INCOMPLETE. In such cases, the
-application should be aware that the conversation function was called
-and that it returned PAM_CONV_AGAIN to a module. The correct action
-for the application to take in response to receiving PAM_INCOMPLETE,
-is to acquire the replies so that the next time the conversation
-function is called it will be able to provide the desired
-responses. And then recall pam_authenticate (pam_chauthtok) with the
-same arguments. Libpam will arrange that the module stack is resumed
-from the module that returned before. This functionality is required
-for programs whose user interface is maintained by an event loop. ]
-
-#$$$ libpam <-> modules
-
-[This section will document the following pam_ and pam_sm_ calls:
-
-functions provided by libpam
-
- pam_set_data
- pam_get_data
-
-functions provided to libpam by each module
-
- groups:
- AUTHENTICATION
- pam_sm_authenticate
- pam_sm_setcred
- ACCOUNT
- pam_sm_acct_mgmt
- SESSION
- pam_sm_open_session
- pam_sm_close_session
- AUTHENTICATION TOKEN MANAGEMENT
- pam_sm_chauthtok
-]
-
-#$$$ The conversation function
-
-The server application, as part of its initialization of libpam,
-provides a conversation function for use by modules and libpam. The
-purpose of the conversation function is to enable direct communication
-to the applicant ultimately via the client and selected agents.
-
-[ this section will contain a definition for the conversation
- function, the conversation structure (appdata etc), and legitimate
- return codes for the application supplied function.
-
- PAM_SUCCESS - ok conversation completed
- PAM_CONV_ERR - conversation failed
- PAM_CONV_AGAIN - application needs control to complete conv
- PAM_CONV_RECONSIDER - application believes module should check if
- it still needs to converse for this info
- ]
-
-#$ Security considerations
-
-This document is devoted to standardizing authentication
-infrastructure: everything in this document has implications for
-security.
-
-#$ Contact
-
-The email list for discussing issues related to this document is
-<pam-list@redhat.com>.
-
-#$ References
-
-[#{OSF_RFC_PAM}] OSF RFC 86.0, "Unified Login with Pluggable Authentication
- Modules (PAM)", October 1995
-
-[#{PAM_STD_AGENTIDS}] Definitions for standard agents, "REGISTERED
- AGENTS AND THEIR AGENT-ID'S", to be found here:
-
-## http://www.kernel.org/pub/linux/libs/pam/pre/doc/std-agent-ids.txt ##
-
-#$ Author's Address
-
-Andrew G. Morgan
-Email: morgan@kernel.org
-
-## $Id$ ##