~ubuntu-branches/ubuntu/breezy/pam/breezy

« back to all changes in this revision

Viewing changes to Linux-PAM/doc/specs/draft-morgan-pam.raw

  • Committer: Bazaar Package Importer
  • Author(s): Sam Hartman
  • Date: 2004-06-28 14:28:08 UTC
  • mfrom: (2.1.1 warty)
  • Revision ID: james.westby@ubuntu.com-20040628142808-adikk7vtfg3pzcjw
Tags: 0.76-22
* Add uploaders
* Document location of repository
* Fix options containing arguments in pam_unix, Closes: #254904

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
Open-PAM working group            ##              A.G. Morgan
 
2
Internet Draft:                   ##              Dec 8, 2001
 
3
Document: draft-morgan-pam-08.txt ##
 
4
Expires: June 8, 2002             ##
 
5
Obsoletes: draft-morgan-pam-07.txt##
 
6
 
 
7
## Pluggable Authentication Modules (PAM) ##
 
8
 
 
9
#$  Status of this memo
 
10
 
 
11
This document is a draft specification. Its contents are subject to
 
12
change with revision. The latest version of this draft may be obtained
 
13
from here:
 
14
 
 
15
  http://www.kernel.org/pub/linux/libs/pam/pre/doc/
 
16
 
 
17
As
 
18
 
 
19
  Linux-PAM-'version'-docs.tar.gz
 
20
 
 
21
It is also contained in the Linux-PAM tar ball.
 
22
 
 
23
#$  Abstract
 
24
 
 
25
This document is concerned with the definition of a general
 
26
infrastructure for module based authentication.  The infrastructure is
 
27
named Pluggable Authentication Modules (PAM for short).
 
28
 
 
29
#$  Introduction
 
30
 
 
31
Computers are tools.  They provide services to people and other
 
32
computers (collectively we shall call these _users_ entities).  In
 
33
order to provide convenient, reliable and individual service to
 
34
different entities, it is common for entities to be labelled.  Having
 
35
defined a label as referring to a some specific entity, the label is
 
36
used for the purpose of protecting and allocating data resources.
 
37
 
 
38
All modern operating systems have a notion of labelled entities and
 
39
all modern operating systems face a common problem: how to
 
40
authenticate the association of a predefined label with applicant
 
41
entities.
 
42
 
 
43
There are as many authentication methods as one might care to count.
 
44
None of them are perfect and none of them are invulnerable.  In
 
45
general, any given authentication method becomes weaker over time.  It
 
46
is common then for new authentication methods to be developed in
 
47
response to newly discovered weaknesses in the old authentication
 
48
methods.
 
49
 
 
50
The problem with inventing new authentication methods is the fact that
 
51
old applications do not support them.  This contributes to an inertia
 
52
that discourages the overhaul of weakly protected systems.  Another
 
53
problem is that individuals (people) are frequently powerless to layer
 
54
the protective authentication around their systems.  They are forced
 
55
to rely on single (lowest common denominator) authentication schemes
 
56
even in situations where this is far from appropriate.
 
57
 
 
58
PAM, as discussed in this document, is a generalization of the
 
59
approach first introduced in [#$R#{OSF_RFC_PAM}].  In short, it is a
 
60
general framework of interfaces that abstract the process of
 
61
authentication.  With PAM, a service provider can custom protect
 
62
individual services to the level that they deem is appropriate.
 
63
 
 
64
PAM has nothing explicit to say about transport layer encryption.
 
65
Within the context of this document encryption and/or compression of
 
66
data exchanges are application specific (strictly between client and
 
67
server) and orthogonal to the process of authentication.
 
68
 
 
69
#$  Definitions
 
70
 
 
71
Here we pose the authentication problem as one of configuring defined
 
72
interfaces between two entities.
 
73
 
 
74
#$$#{players}  Players in the authentication process
 
75
 
 
76
PAM reserves the following words to specify unique entities in the
 
77
authentication process:
 
78
 
 
79
  applicant
 
80
        the entity (user) initiating an application for service
 
81
        [PAM associates the PAM_RUSER _item_ with this requesting user].
 
82
 
 
83
  arbitrator
 
84
        the entity (user) under whose identity the service application
 
85
        is negotiated and with whose authority service is granted.
 
86
 
 
87
  user
 
88
        the entity (user) whose identity is being authenticated
 
89
        [PAM associates the PAM_USER _item_ with this identity].
 
90
 
 
91
  server
 
92
        the application that provides service, or acts as an
 
93
        authenticated gateway to the requested service.  This
 
94
        application is completely responsible for the server end of
 
95
        the transport layer connecting the server to the client.
 
96
        PAM makes no assumptions about how data is encapsulated for
 
97
        exchanges between the server and the client, only that full
 
98
        octet sequences can be freely exchanged without corruption.
 
99
 
 
100
  client
 
101
        application providing the direct/primary interface to
 
102
        applicant.  This application is completely responsible
 
103
        for the client end of the transport layer connecting the
 
104
        server to the client.  PAM makes no assumptions about how data
 
105
        is encapsulated for exchanges between the server and the
 
106
        client, only that full octet sequences can be freely
 
107
        exchanged without corruption.
 
108
 
 
109
  module
 
110
        authentication binary that provides server-side support for
 
111
        some (arbitrary) authentication method.
 
112
 
 
113
  agent
 
114
        authentication binary that provides client-side support for
 
115
        some (arbitrary) authentication method.
 
116
 
 
117
Here is a diagram to help orient the reader:
 
118
 
 
119
##               +-------+              +--------+ ##
 
120
##      . . . . .| agent |             .| module | ##
 
121
##      .        +-------+             .+--------+ ##
 
122
##      V            |                 .    |      ##
 
123
##      .            |                 V    |      ##
 
124
## +---------+   +-------+             . +------+  ##
 
125
## |         |   |libpamc|             . |libpam|  ##
 
126
## |         |   +-------+             . +------+  ##
 
127
## |applicant|       |                 .    |      ##
 
128
## |         |   +--------+           +----------+ ##
 
129
## |         |---| client |-----------|  server  | ##
 
130
## +---------+   +--------+           +----------+ ##
 
131
 
 
132
Solid lines connecting the boxes represent two-way interaction.  The
 
133
dotted-directed lines indicate an optional connection beteween the
 
134
plugin module (agent) and the server (applicant). In the case of the
 
135
module, this represents the module invoking the 'conversation'
 
136
callback function provided to libpam by the server application when it
 
137
inititializes the libpam library. In the case of the agent, this may
 
138
be some out-of-PAM API interaction (for example directly displaying a
 
139
dialog box under X).
 
140
 
 
141
#$$  Defined Data Types
 
142
 
 
143
In this draft, we define two composite data types, the text string and
 
144
the binary prompt. They are the data types used to communicate
 
145
authentication requests and responses.
 
146
 
 
147
#$$$#{text_string}  text string
 
148
 
 
149
The text string is a simple sequence of non-NUL (NUL = 0x00)
 
150
octets. Terminated with a single NUL (0x00) octet. The character set
 
151
employed in the octet sequence may be negotiated out of band, but
 
152
defaults to utf-8.
 
153
 
 
154
## --------------------------- ##
 
155
## [  character data  |  NUL ] ##
 
156
## [  octet sequence  | 0x00 ] ##
 
157
## --------------------------- ##
 
158
 
 
159
Within the rest of this text, PAM text strings are delimited with a
 
160
pair of double quotes. Example, "this" = {'t';'h';'i';'s';0x00}.
 
161
 
 
162
#$$$#{binary_prompt}  binary prompt
 
163
 
 
164
A binary prompt consists of a stream of octets arranged as follows:
 
165
 
 
166
## ---------------------------------------- ##
 
167
## [  u32   |   u8    | (length-5 octets) ] ##
 
168
## [ length | control |       data        ] ##
 
169
## ---------------------------------------- ##
 
170
 
 
171
That is, a 32-bit unsigned integer in network byte order, a single
 
172
unsigned byte of control information and a sequence of octets of
 
173
length (length-5). The composition of the _data_ is context dependent
 
174
but is generally not a concern for either the server or the client. It
 
175
is very much the concern of modules and agents.
 
176
 
 
177
For purposes of interoperability, we define the following control
 
178
characters as legal.
 
179
 
 
180
## value    symbol             description           ##
 
181
## ------------------------------------------------- ##
 
182
## 0x01     PAM_BPC_OK       - continuation packet   ##
 
183
## 0x02     PAM_BPC_SELECT   - initialization packet ##
 
184
## 0x03     PAM_BPC_DONE     - termination packet    ##
 
185
## 0x04     PAM_BPC_FAIL     - unable to execute     ##
 
186
 
 
187
The following control characters are only legal for exchanges between
 
188
an agent and a client (it is the responsibility of the client to
 
189
enforce this rule in the face of a rogue server):
 
190
 
 
191
## 0x41     PAM_BPC_GETENV   - obtain client env.var  ##
 
192
## 0x42     PAM_BPC_PUTENV   - set client env.var     ##
 
193
## 0x43     PAM_BPC_TEXT     - display message        ##
 
194
## 0x44     PAM_BPC_ERROR    - display error message  ##
 
195
## 0x45     PAM_BPC_PROMPT   - echo'd text prompt     ##
 
196
## 0x46     PAM_BPC_PASS     - non-echo'd text prompt ##
 
197
## 0x46     PAM_BPC_STATUS   - ping all active clients##
 
198
## 0x47     PAM_BPC_ABORT    - please abort session   ##
 
199
 
 
200
Note, length is always equal to the total length of the binary
 
201
prompt and represented by a network ordered unsigned 32 bit integer.
 
202
 
 
203
#$$$$#{agent_ids} PAM_BPC_SELECT binary prompts
 
204
 
 
205
Binary prompts of control type PAM_BPC_SELECT have a defined
 
206
data part. It is composed of three elements:
 
207
 
 
208
        {agent_id;'/';data}
 
209
 
 
210
The agent_id is a sequence of characters satisfying the following
 
211
regexp:
 
212
 
 
213
        /^[a-z0-9\_]+(@[a-z0-9\_.]+)?$/
 
214
 
 
215
and has a specific form for each independent agent.
 
216
 
 
217
o Agent_ids that do not contain an at-sign (@) are to be considered as
 
218
  representing some authentication mode that is a "public
 
219
  standard" see reference [#$R#{PAM_STD_AGENTIDS}]. Registered names
 
220
  MUST NOT contain an at-sign (@).
 
221
 
 
222
o Anyone can define additional agents by using names in the format
 
223
  name@domainname, e.g. "ouragent@example.com". The part following
 
224
  the at-sign MUST be a valid fully qualified internet domain name
 
225
  [RFC-1034] controlled by the person or organization defining the
 
226
  name. (Said another way, if you control the email address that
 
227
  your agent has as an identifier, they you are entitled to use
 
228
  this identifier.) It is up to each domain how it manages its local
 
229
  namespace.
 
230
 
 
231
The '/' character is a mandatory delimiter, indicating the end of the
 
232
agent_id. The trailing data is of a format specific to the agent with
 
233
the given agent_id.
 
234
 
 
235
 
 
236
#$$  Special cases
 
237
 
 
238
In a previous section (#{players}) we identified the most general
 
239
selection of authentication participants.  In the case of network
 
240
authentication, it is straightforward to ascribe identities to the
 
241
defined participants.  However, there are also special (less general)
 
242
cases that we recognize here.
 
243
 
 
244
The primary authentication step, when a user is directly introduced
 
245
into a computer system (log's on to a workstation) is a special case.
 
246
In this situation, the client and the server are generally one
 
247
application.  Before authenticating such a user, the applicant is
 
248
formally unknown: PAM_RUSER is NULL.
 
249
 
 
250
Some client-server implementations (telnet for example) provide
 
251
effective full tty connections. In these cases, the four simple text
 
252
string prompting cases (see below) can be handled as in the primary
 
253
login step. In other words, the server absorbs most of the overhead of
 
254
propagating authentication messages. In these cases, there needs to be
 
255
special client/server support for handling binary prompts.
 
256
 
 
257
In some circumstances, a legacy network transfer protocol can carry
 
258
authentication information. In such cases, a desire to support legacy
 
259
clients (with no client-side support for PAM) will neccessitate the
 
260
'hardcoding' of an agent protocol into the server application. Whilst
 
261
against the spirit of PAM, this special casing can be managed by the
 
262
server's 'conversation function' (see below). The guiding principle
 
263
when implementing such support is for the application developer to
 
264
relegate the authentication process to the PAM module -- simply
 
265
performing a transcription of data from binary-prompt to legacy
 
266
network 'packet' and visa-versa for propagating replies back to the
 
267
driving PAM module. A common case of this is with network protocols
 
268
that define an initialization packet of "user+password". In such cases
 
269
one should attempt to support the "userpass" agent-id and its defined
 
270
protocol.
 
271
 
 
272
#$  Defined interfaces for information flow
 
273
 
 
274
Here, we discuss the information exchange interfaces between the
 
275
players in the authentication process. It should be understood that
 
276
the server side is responsible for driving the authentication of the
 
277
applicant. Notably, every request received by the client from the
 
278
server must be matched with a single response from the client to the
 
279
server.
 
280
 
 
281
#$$#{applicant_client}  Applicant <-> client
 
282
 
 
283
Once the client is invoked, requests to the applicant entity are
 
284
initiated by the client application.  General clients are able to make
 
285
the following requests directly to an applicant:
 
286
 
 
287
   echo text string
 
288
   echo error text string
 
289
   prompt with text string for echo'd text string input
 
290
   prompt with text string for concealed text string input
 
291
 
 
292
the nature of the interface provided by the client for the benefit of
 
293
the applicant entity is client specific and not defined by PAM.
 
294
 
 
295
#$$#{client_agent}  Client <-> agent
 
296
 
 
297
In general, authentication schemes require more modes of exchange than
 
298
the four defined in the previous section (#{applicant_client}).  This
 
299
provides a role for client-loadable agents.  The client and agent
 
300
exchange binary-messages that can have one of the following forms:
 
301
 
 
302
   client -> agent
 
303
        binary prompt agent expecting binary prompt reply to client
 
304
 
 
305
   agent -> client
 
306
        binary prompt reply from agent to clients binary prompt
 
307
 
 
308
Following the acceptance of a binary prompt by the agent, the agent
 
309
may attempt to exchange information with the client before returning
 
310
its binary prompt reply. Permitted exchanges are binary prompts of the
 
311
following types:
 
312
 
 
313
   agent -> client
 
314
        set environment variable (A)
 
315
        get environment variable (B)
 
316
        echo text string (C)
 
317
        echo error text string (D)
 
318
        prompt for echo'd text string input (E)
 
319
        prompt for concealed text string input (F)
 
320
 
 
321
In response to these prompts, the client must legitimately respond
 
322
with a corresponding binary prompt reply. We list a complete set of
 
323
example exchanges, including each type of legitimate response (passes
 
324
and a single fail):
 
325
 
 
326
## Type | Agent request                  | Client response         ##
 
327
## --------------------------------------------------------------- ##
 
328
## (A)  | {13;PAM_BPC_PUTENV;"FOO=BAR"}  | {5;PAM_BPC_OK;}         ##
 
329
##      | {10;PAM_BPC_PUTENV;"FOO="}     | {5;PAM_BPC_OK;}         ##
 
330
##      | {9;PAM_BPC_PUTENV;"FOO"}  (*)  | {5;PAM_BPC_OK;}         ##
 
331
##      | {9;PAM_BPC_PUTENV;"BAR"}  (*)  | {5;PAM_BPC_FAIL;}       ##
 
332
## --------------------------------------------------------------- ##
 
333
## (B)  | {10;PAM_BPC_GETENV;"TERM"}     | {11;PAM_BPC_OK;"vt100"} ##
 
334
##      | {9;PAM_BPC_GETENV;"FOO"}       | {5;PAM_BPC_FAIL;}       ##
 
335
## --------------------------------------------------------------- ##
 
336
## (C)  | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_OK;}         ##
 
337
##      | {12;PAM_BPC_TEXT;"hello!"}     | {5;PAM_BPC_FAIL;}       ##
 
338
## --------------------------------------------------------------- ##
 
339
## (D)  | {11;PAM_BPC_ERROR;"ouch!"}     | {5;PAM_BPC_OK;}         ##
 
340
##      | {11;PAM_BPC_ERROR;"ouch!"}     | {5;PAM_BPC_FAIL;}       ##
 
341
## --------------------------------------------------------------- ##
 
342
## (E)  | {13;PAM_BPC_PROMPT;"login: "}  | {9;PAM_BPC_OK;"joe"}    ##
 
343
##      | {13;PAM_BPC_PROMPT;"login: "}  | {6;PAM_BPC_OK;""}       ##
 
344
##      | {13;PAM_BPC_PROMPT;"login: "}  | {5;PAM_BPC_FAIL;}       ##
 
345
## --------------------------------------------------------------- ##
 
346
## (F)  | {16;PAM_BPC_PASS;"password: "} | {9;PAM_BPC_OK;"XYZ"}    ##
 
347
##      | {16;PAM_BPC_PASS;"password: "} | {6;PAM_BPC_OK;""}       ##
 
348
##      | {16;PAM_BPC_PASS;"password: "} | {5;PAM_BPC_FAIL;}       ##
 
349
 
 
350
(*) Used to attempt the removal of a pre-existing environment
 
351
variable.
 
352
 
 
353
#$$  Client <-> server
 
354
 
 
355
Once the client has established a connection with the server (the
 
356
nature of the transport protocol is not specified by PAM), the server
 
357
is responsible for driving the authentication process.
 
358
 
 
359
General servers can request the following from the client:
 
360
 
 
361
   (to be forwarded by the client to the applicant)
 
362
        echo text string
 
363
        echo error text string
 
364
        prompt for echo'd text string response
 
365
        prompt for concealed text string response
 
366
 
 
367
   (to be forwarded by the client to the appropriate agent)
 
368
        binary prompt for a binary prompt response
 
369
 
 
370
Client side agents are required to process binary prompts.  The
 
371
agents' binary prompt responses are returned to the server.
 
372
 
 
373
#$$  Server <-> module
 
374
 
 
375
Modules drive the authentication process.  The server provides a
 
376
conversation function with which it encapsulates module-generated
 
377
requests and exchanges them with the client. Every message sent by a
 
378
module should be acknowledged.
 
379
 
 
380
General conversation functions can support the following five 
 
381
conversation requests:
 
382
 
 
383
   echo text string
 
384
   echo error string
 
385
   prompt for echo'd text string response
 
386
   prompt for concealed text string response
 
387
   binary prompt for binary prompt response
 
388
 
 
389
The server is responsible for redirecting these requests to the
 
390
client.
 
391
 
 
392
#$  C API for application interfaces (client and server)
 
393
 
 
394
#$$  Applicant <-> client
 
395
 
 
396
No API is defined for this interface.  The interface is considered to
 
397
be specific to the client application.  Example applications include
 
398
terminal login, (X)windows login, machine file transfer applications.
 
399
 
 
400
All that is important is that the client application is able to
 
401
present the applicant with textual output and to receive textual
 
402
input from the applicant.  The forms of textual exchange are listed
 
403
in an earlier section (#{applicant_client}).  Other methods of
 
404
data input/output are better suited to being handled via an
 
405
authentication agent.
 
406
 
 
407
#$$  Client <-> agent
 
408
 
 
409
The client makes use of a general API for communicating with
 
410
agents. The client is not required to communicate directly with
 
411
available agents, instead a layer of abstraction (in the form of a
 
412
library: libpamc) takes care of loading and maintaining communication
 
413
with all requested agents. This layer of abstraction will choose which
 
414
agents to interact with based on the content of binary prompts it
 
415
receives that have the control type PAM_BPC_SELECT.
 
416
 
 
417
#$$$  Client <-> libpamc
 
418
 
 
419
#$$$$  Compilation information
 
420
 
 
421
The C-header file provided for client-agent abstraction is included
 
422
with the following source line:
 
423
 
 
424
        \#include <security/pam_client.h>
 
425
 
 
426
The library providing the corresponding client-agent abstraction
 
427
functions is, libpamc.
 
428
 
 
429
        cc .... -lpamc
 
430
 
 
431
#$$$$  Initializing libpamc
 
432
 
 
433
The libpamc library is initialized with a call to the following
 
434
function:
 
435
 
 
436
        pamc_handle_t pamc_start(void);
 
437
 
 
438
This function is responsible for configuring the library and
 
439
registering the location of available agents. The location of the
 
440
available agents on the system is implementation specific.
 
441
 
 
442
pamc_start() function returns NULL on failure. Otherwise, the return
 
443
value is a pointer to an opaque data type which provides a handle to
 
444
the libpamc library. On systems where threading is available, the
 
445
libpamc libraray is thread safe provided a single (pamc_handler_t *)
 
446
is used by each thread.
 
447
 
 
448
#$$$$  Client (Applicant) selection of agents
 
449
 
 
450
For the purpose of applicant and client review of available agents,
 
451
the following function is provided.
 
452
 
 
453
        char **pamc_list_agents(pamc_handle_t pch);
 
454
 
 
455
This returns a list of pointers to the agent_id's of the agents which
 
456
are available on the system. The list is terminated by a NULL pointer.
 
457
It is the clients responsibility to free this memory area by calling
 
458
free() on each agent id and the block of agent_id pointers in the
 
459
result.
 
460
 
 
461
PAM represents a server-driven authentication model, so by default
 
462
any available agent may be invoked in the authentication process.
 
463
 
 
464
#$$$$$  Client demands agent
 
465
 
 
466
If the client requires that a specific authentication agent is
 
467
satisfied during the authentication process, then the client should
 
468
call the following function, immediately after obtaining a
 
469
pamc_handle_t from pamc_start().
 
470
 
 
471
        int pamc_load(pamc_handle_t pch, const char *agent_id);
 
472
 
 
473
agent_id is a PAM text string (see section #{agent_ids}) and is not
 
474
suffixed with a '/' delimiter. The return value for this function is:
 
475
 
 
476
        PAM_BPC_TRUE    - agent located and loaded.
 
477
        PAM_BPC_FALSE   - agent is not available.
 
478
 
 
479
Note, although the agent is loaded, no data is fed to it. The agent's
 
480
opportunity to inform the client that it does not trust the server is
 
481
when the agent is shutdown.
 
482
 
 
483
#$$$$$  Client marks agent as unusable
 
484
 
 
485
The applicant might prefer that a named agent is marked as not
 
486
available.  To do this, the client would invoke the following function
 
487
immediately after obtaining a pamc_handle_t from pam_start().
 
488
 
 
489
        int pamc_disable(pamc_handle_t pch, const char *agent_id);
 
490
 
 
491
here agent_id is a PAM text string containing an agent_id (section
 
492
#{agent_ids}).
 
493
 
 
494
The return value for this function is:
 
495
 
 
496
        PAM_BPC_TRUE    - agent is disabled. This is the response
 
497
                          independent of whether the agent is locally
 
498
                          available.
 
499
 
 
500
        PAM_BPC_FALSE   - agent cannot be disabled (this may be because
 
501
                          it has already been invoked).
 
502
 
 
503
#$$$$  Allocating and manipulating binary prompts
 
504
 
 
505
All conversation between an client and an agent takes place with
 
506
respect to binary prompts. A binary prompt (see section #{binary_prompt}), is
 
507
obtained, resized and deleted via the following C-macro:
 
508
 
 
509
 CREATION of a binary prompt with control X1 and data length Y1:
 
510
 
 
511
        pamc_bp_t prompt = NULL;
 
512
        PAM_BP_RENEW(&prompt, X1, Y1);
 
513
 
 
514
 REPLACEMENT of a binary prompt with a control X2 and data length Y2:
 
515
 
 
516
        PAM_BP_RENEW(&prompt, X2, Y2);
 
517
 
 
518
 DELETION of a binary prompt (the referenced prompt is scrubbed):
 
519
 
 
520
        PAM_BP_RENEW(&prompt, 0, 0);
 
521
 
 
522
Note, the PAM_BP_RENEW macro always overwrites any prompt that you
 
523
call it with, deleting and liberating the old contents in a secure
 
524
fashion. Also note that PAM_BP_RENEW, when returning a prompt of data
 
525
size Y1>0, will always append a '\0' byte to the end of the prompt (at
 
526
data offset Y1). It is thus, by definition, acceptable to treat the
 
527
data contents of a binary packet as a text string (see #{text_string}).
 
528
 
 
529
 FILLING a binary prompt from a memory pointer U1 from offset O1 of
 
530
   length L1:
 
531
 
 
532
        PAM_BP_FILL(prompt, O1, L1, U1);
 
533
 
 
534
 the CONTROL type for the packet can be obtained as follows:
 
535
 
 
536
        control = PAM_PB_CONTROL(prompt);
 
537
 
 
538
 the LENGTH of a data within the prompt (_excluding_ its header
 
539
 information) can be obtained as follows:
 
540
 
 
541
        length = PAM_BP_LENGTH(prompt);
 
542
 
 
543
 the total SIZE of the prompt (_including_ its header information)
 
544
 can be obtained as follows:
 
545
 
 
546
        size = PAM_BP_SIZE(prompt);
 
547
 
 
548
 EXTRACTING data from a binary prompt from offset O2 of length L2 to
 
549
   a memory pointer U2:
 
550
 
 
551
        PAM_BP_EXTRACT(prompt, O2, L2, U2);
 
552
 
 
553
 If you require direct access to the raw prompt DATA, you should use
 
554
 the following macro:
 
555
 
 
556
        __u8 *raw_data = PAM_BP_DATA(prompt);
 
557
 
 
558
#$$$$  Client<->agent conversations
 
559
 
 
560
All exchanges of binary prompts with agents are handled with the
 
561
single function:
 
562
 
 
563
        int pamc_converse(pamc_handle_t *pch, pamc_bp_t *prompt_p);
 
564
 
 
565
The return value for pamc_converse(...) is PAM_BPC_TRUE when there is
 
566
a response packet and PAM_BPC_FALSE when the client is unable to
 
567
handle the request represented by the original prompt. In this latter
 
568
case, *prompt_p is set to NULL.
 
569
 
 
570
This function takes a binary prompt and returns a replacement binary
 
571
prompt that is either a request from an agent to be acted upon by the
 
572
client or the 'result' which should be forwarded to the server. In the
 
573
former case, the following macro will return 1 (PAM_BPC_TRUE) and in
 
574
all other cases, 0 (PAM_BPC_FALSE):
 
575
 
 
576
        PAM_BPC_FOR_CLIENT(/* pamc_bp_t */ prompt)
 
577
 
 
578
Note, all non-NULL binary prompts returned by pamc_converse(...), are
 
579
terminated with a '\0', even when the full length of the prompt (as
 
580
returned by the agent) does not contain this delimiter. This is a
 
581
defined property of the PAM_BP_RENEW macro, and can be relied upon.
 
582
 
 
583
Important security note: in certain implementations, agents are
 
584
implemented by executable binaries, which are transparently loaded and
 
585
managed by the PAM client library. To ensure there is never a leakage
 
586
of elevated privilege to an unprivileged agent, the client application
 
587
should go to some effort to lower its level of privilege. It remains
 
588
the responsibility of the applicant and the client to ensure that it
 
589
is not compromised by a rogue agent.
 
590
 
 
591
#$$$$  Status of agents
 
592
 
 
593
        int pamc_status(pamc_handle_t *pch, pamc_bp_t *prompt_p);
 
594
 
 
595
At any time, the client may ping all active agents for their status
 
596
(with a PAM_BPC_STATUS binary prompt). If any agent replies with
 
597
PAM_BPC_ABORT, the client is responsible for terminating the
 
598
connection to the server and then terminating all agents with a call
 
599
to pamc_end(). In such cases, the return value of pamc_status() is
 
600
PAM_BPC_FALSE.
 
601
 
 
602
If the return status of pamc_status() is PAM_BPC_TRUE and *prompt_p is
 
603
non-NULL, then an agent is requesting access to a server module.
 
604
 
 
605
XXX - how this information gets propagated to the server, and
 
606
      ultimately to the server's module is yet to be determined.
 
607
 
 
608
#$$$$  Termination of agents
 
609
 
 
610
When closing the authentication session and severing the connection
 
611
between a client and a selection of agents, the following function is
 
612
used:
 
613
 
 
614
        int pamc_end(pamc_handle_t *pch);
 
615
 
 
616
Following a call to pamc_end, the pamc_handle_t will be invalid.
 
617
 
 
618
The return value for this function is one of the following:
 
619
 
 
620
        PAM_BPC_TRUE    - all invoked agents are content with
 
621
                          authentication (the server is _not_ judged
 
622
                          _un_trustworthy by any agent)
 
623
 
 
624
        PAM_BPC_FALSE   - one or more agents were unsatisfied at
 
625
                          being terminated.  In general, the client
 
626
                          should terminate its connection to the
 
627
                          server and indicate to the applicant that
 
628
                          the server is untrusted.
 
629
 
 
630
#$$$ libpamc <-> agents
 
631
 
 
632
The agents are manipulated from within libpamc. Each agent is an
 
633
executable in its own right. This permits the agent to have access to
 
634
sensitive data not accessible directly from the client. The mode of
 
635
communication between libpamc and an agent is through a pair of
 
636
pipes. The agent reads binary prompts (section #{binary_prompt})
 
637
through its standard input file descriptor and writes response (to the
 
638
server) binary prompts and instruction binary prompts (instructions
 
639
for the client) through its standard output file descriptor.
 
640
 
 
641
#$$ Client <-> server
 
642
 
 
643
This interface is concerned with the exchange of text and binary
 
644
prompts between the client application and the server application.  No
 
645
API is provided for this as it is considered specific to the transport
 
646
protocol shared by the client and the server.
 
647
 
 
648
#$$ Server <-> modules
 
649
 
 
650
The server makes use of a general API for communicating with
 
651
modules. The client is not required to communicate directly with
 
652
available modules. By abstracting the authentication interface, it
 
653
becomes possible for the local administrator to make a run time
 
654
decision about the authentication method adopted by the server.
 
655
 
 
656
#$$$ Functions and definitions available to servers and modules
 
657
 
 
658
[This section will document the following functions
 
659
 
 
660
        pam_set_item()
 
661
        pam_get_item()
 
662
        pam_fail_delay(pam_handle_t *pamh, unsigned int micro_sec)
 
663
        pam_get_env(pam_handle_t *pamh, const char *varname)
 
664
        pam_strerror(pam_handle_t *pamh, int pam_errno)
 
665
 
 
666
Event driven support (XXX work in progress)
 
667
 
 
668
        pam_register_event() - app or module associates an event poller/handler
 
669
        pam_select_event()   - query for any outstanding event and act on any
 
670
]
 
671
 
 
672
#$$$ Server <-> libpam
 
673
 
 
674
[This section will document the following pam_ calls:
 
675
 
 
676
        pam_start
 
677
        pam_end
 
678
        pam_authenticate (*)
 
679
        pam_setcred
 
680
        pam_acct_mgmt
 
681
        pam_open_session
 
682
        pam_close_session
 
683
        pam_chauthtok (*)
 
684
 
 
685
The asterisked functions may return PAM_INCOMPLETE. In such cases, the
 
686
application should be aware that the conversation function was called
 
687
and that it returned PAM_CONV_AGAIN to a module. The correct action
 
688
for the application to take in response to receiving PAM_INCOMPLETE,
 
689
is to acquire the replies so that the next time the conversation
 
690
function is called it will be able to provide the desired
 
691
responses. And then recall pam_authenticate (pam_chauthtok) with the
 
692
same arguments. Libpam will arrange that the module stack is resumed
 
693
from the module that returned before. This functionality is required
 
694
for programs whose user interface is maintained by an event loop. ]
 
695
 
 
696
#$$$ libpam <-> modules
 
697
 
 
698
[This section will document the following pam_ and pam_sm_ calls:
 
699
 
 
700
functions provided by libpam
 
701
 
 
702
        pam_set_data
 
703
        pam_get_data
 
704
 
 
705
functions provided to libpam by each module
 
706
 
 
707
  groups:
 
708
        AUTHENTICATION
 
709
                pam_sm_authenticate
 
710
                pam_sm_setcred
 
711
        ACCOUNT
 
712
                pam_sm_acct_mgmt
 
713
        SESSION
 
714
                pam_sm_open_session
 
715
                pam_sm_close_session
 
716
        AUTHENTICATION TOKEN MANAGEMENT
 
717
                pam_sm_chauthtok
 
718
]
 
719
 
 
720
#$$$ The conversation function
 
721
 
 
722
The server application, as part of its initialization of libpam,
 
723
provides a conversation function for use by modules and libpam. The
 
724
purpose of the conversation function is to enable direct communication
 
725
to the applicant ultimately via the client and selected agents.
 
726
 
 
727
[ this section will contain a definition for the conversation
 
728
  function, the conversation structure (appdata etc), and legitimate
 
729
  return codes for the application supplied function.
 
730
 
 
731
        PAM_SUCCESS           - ok conversation completed
 
732
        PAM_CONV_ERR          - conversation failed
 
733
        PAM_CONV_AGAIN        - application needs control to complete conv
 
734
        PAM_CONV_RECONSIDER   - application believes module should check if
 
735
                                it still needs to converse for this info
 
736
 ]
 
737
 
 
738
#$  Security considerations
 
739
 
 
740
This document is devoted to standardizing authentication
 
741
infrastructure: everything in this document has implications for
 
742
security.
 
743
 
 
744
#$  Contact
 
745
 
 
746
The email list for discussing issues related to this document is
 
747
<pam-list@redhat.com>.
 
748
 
 
749
#$  References
 
750
 
 
751
[#{OSF_RFC_PAM}]  OSF RFC 86.0, "Unified Login with Pluggable Authentication
 
752
     Modules (PAM)", October 1995
 
753
 
 
754
[#{PAM_STD_AGENTIDS}] Definitions for standard agents, "REGISTERED
 
755
     AGENTS AND THEIR AGENT-ID'S", to be found here:
 
756
 
 
757
## http://www.kernel.org/pub/linux/libs/pam/pre/doc/std-agent-ids.txt ##
 
758
 
 
759
#$  Author's Address
 
760
 
 
761
Andrew G. Morgan
 
762
Email: morgan@kernel.org
 
763
 
 
764
## $Id: draft-morgan-pam.raw,v 1.1.1.2 2002/09/15 20:08:34 hartmans Exp $ ##