1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
|
.\" $OpenBSD: auth_subr.3,v 1.19 2009/07/15 07:53:56 schwarze Exp $
.\"
.\" Copyright (c) 1997 Berkeley Software Design, Inc. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by Berkeley Software Design,
.\" Inc.
.\" 4. The name of Berkeley Software Design, Inc. may not be used to endorse
.\" or promote products derived from this software without specific prior
.\" written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN, INC. ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN, INC. BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" BSDI $From: auth_subr.3,v 2.5 2000/03/30 19:11:27 polk Exp $
.Dd $Mdocdate: July 15 2009 $
.Dt BSD_AUTH 3
.Os
.Sh NAME
.Nm auth_open ,
.Nm auth_call ,
.Nm auth_challenge ,
.Nm auth_check_change ,
.Nm auth_check_expire ,
.Nm auth_clean ,
.Nm auth_close ,
.Nm auth_clrenv ,
.Nm auth_clroption ,
.Nm auth_clroptions ,
.Nm auth_getitem ,
.Nm auth_getpwd ,
.Nm auth_getstate ,
.Nm auth_getvalue ,
.Nm auth_set_va_list ,
.Nm auth_setdata ,
.Nm auth_setenv ,
.Nm auth_setitem ,
.Nm auth_setoption ,
.Nm auth_setpwd ,
.Nm auth_setstate
.Nd interface to the BSD Authentication system
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <login_cap.h>
.Fd #include <bsd_auth.h>
.Ft auth_session_t *
.Fn auth_open "void"
.Ft int
.Fn auth_close "auth_session_t *as"
.Ft int
.Fn auth_call "auth_session_t *as" "char *path" "..."
.Ft char *
.Fn auth_challenge "auth_session_t *as"
.Ft quad_t
.Fn auth_check_change "auth_session_t *as"
.Ft quad_t
.Fn auth_check_expire "auth_session_t *as"
.Ft void
.Fn auth_clean "auth_session_t *as"
.Ft void
.Fn auth_clrenv "auth_session_t *as"
.Ft void
.Fn auth_clroption "auth_session_t * as" "char *name"
.Ft void
.Fn auth_clroptions "auth_session_t *as"
.Ft char *
.Fn auth_getitem "auth_session_t *as" "auth_item_t item"
.Ft struct passwd *
.Fn auth_getpwd "auth_session_t *as"
.Ft int
.Fn auth_getstate "auth_session_t *as"
.Ft char *
.Fn auth_getvalue "auth_session_t *as" "char *what"
.Ft void
.Fn auth_set_va_list "auth_session_t *as" "va_list ap"
.Ft int
.Fn auth_setdata "auth_session_t *as" "void *ptr" "size_t len"
.Ft void
.Fn auth_setenv "auth_session_t *as"
.Ft int
.Fn auth_setitem "auth_session_t *as" "auth_item_t item" "char *value"
.Ft int
.Fn auth_setoption "auth_session_t *as" "char *name" "char *value"
.Ft int
.Fn auth_setpwd "auth_session_t *as" "struct passwd *pwd"
.Ft void
.Fn auth_setstate "auth_session_t *as" "int state"
.Sh DESCRIPTION
These functions provide the lower level interface to the BSD
Authentication system.
They all operate on a BSD Authentication session pointer,
.Fa as ,
which is returned by
.Fn auth_open .
The session pointer
must be passed to all other BSD Authentication functions called.
The
.Fn auth_open
function returns
.Dv NULL
if it was unable to allocate memory for the session.
The session is terminated by the
.Fn auth_close
function,
which also sets any environment variables requested by the login script
(assuming the user was not rejected) or removes files created by the
login script if the authentication was not successful.
It returns the final state of the authentication request.
A return value of 0 implies the user was not authenticated.
A non-zero return value is made up of 1 or more of the following values
ORed together:
.Bl -tag -width AUTH_ROOTOKAYXX
.It Dv AUTH_OKAY
The user was authenticated.
.It Dv AUTH_ROOTOKAY
The user was authenticated with a root instance.
.It Dv AUTH_SECURE
The user was authenticated via a mechanism which is not subject to
eavesdropping attacks (such as provided by token cards).
.El
.Pp
The full state of the session is returned by the
.Fn auth_getstate
function.
In addition to the values above, it also may contain the bits:
.Bl -tag -width AUTH_ROOTOKAYXX
.It Dv AUTH_SILENT
Do not report an error, the user was not authenticated for access and
was not expected to be.
This is returned by login scripts that allow changing of the user's password,
for instance.
This value is stripped off for normal returns.
.It Dv AUTH_CHALLENGE
The user was not authenticated for access and a challenge was issued.
The challenge should be displayed to the user, a response retrieved,
and the result verified.
This value is stripped off for normal returns.
.It Dv AUTH_EXPIRED
The user's account has expired.
.It Dv AUTH_PWEXPIRED
The user's password has expired and needs to be changed.
.El
.Pp
A session may be cleaned
by calling
.Fn auth_clean .
This function removes any files created by a login script in this
session and clears all state associated with this session, with the
exception of the option settings.
It is not necessary to call
.Fn auth_clean
if
.Fn auth_close
is called.
.Pp
The remaining functions are described in alphabetical order.
.Pp
The fundamental function for doing BSD Authentication is
.Fn auth_call .
In addition to the pointer to the BSD Authentication session, it takes
the following parameters:
.Bl -tag -width indent
.It Ar path
The full path name of the login script to run.
The call will fail if
.Ar path
does not pass the requirements of the
.Xr secure_path 3
function.
.It Ar ...
The remaining arguments, which should be of type
.Vt char *
and terminated with a
.Dv NULL ,
are passed to the login script at the end of the command line.
.El
.Pp
The
.Fn auth_call
function, after verifying the
.Ar path ,
creates a bi-directional pipe (socketpair) which is located on
file descriptor 3 for the child (the login script).
This is known as the
.Dq back channel .
The actual command line passed to the child is made up of
3 parts.
The parameters passed to
.Fn auth_call
following
.Ar path
have appended to them any arguments specified by the
.Fn auth_set_va_list
function.
These are typically the variable arguments passed to the function
that calls
.Fn auth_call .
Any option values set by the
.Fn auth_setoption
function are inserted between the first argument (the command
name) and the second argument with a preceding
.Fl v
flag.
The name and value are separated by an
.Sq = :
.Pp
.D1 Fl v Ar name=value
.Pp
Once the login script has been spawned, any data specified by the
.Fn auth_setdata
is written to the back channel.
Multiple blocks of data may have been specified and they will be sent
in the same order they were specified.
As the data is sent, the storage for the data is zeroed out and then freed
(the data is zeroed out since it may contain sensitive information,
such as a password).
Once any data is written out,
.Fn auth_call
reads up to 8192 bytes of data from the back channel.
The state of the session is determined from this data (see
.Xr login.conf 5
for details).
If the login script exits with a 0 and does not specify any return state
on the back channel, the state prior to the call to
.Fn auth_call
is retained.
.Pp
Note that while
.Fn auth_call
will zero out the copies it makes of sensitive information, such as plain text
passwords, after it is sent, it is the responsibility of the
caller to zero out the original copies of this sensitive information.
Due to the mechanics of the
.Fn auth_call
function, this data must be zeroed
.Em before
.Fn auth_call
is called.
The safest place to zero out sensitive information is immediately
after it has been passed to
.Fn auth_setdata .
.Pp
The back channel data may also contain a file descriptor passed back
from the login script.
If this is the case, the login script will first send back the string
.Dq fd
to indicate that a file descriptor will be the next data item.
The file descriptor will be passed back to the next invocation of
the login script with a number specified by the
.Fl v Ar fd
option.
This is used to implement stateful challenge/response schemes that require
a persistent connection during the challenge and response.
The copy of the descriptor in the parent process is closed when the
child is running to prevent deadlock when file locking is used.
The descriptor is also closed by a call to
.Fn auth_close
or
.Fn auth_clean .
.Pp
The data read from the back channel is also used by the
.Fn auth_getvalue
and
.Fn auth_close
functions.
Subsequent calls to
.Fn auth_call
will cause this data to be lost and overwritten with the new data read
from the new call.
.Pp
The environment passed to the login script by
.Fn auth_call
only contains two values:
.Ev PATH
and
.Ev SHELL .
The
.Ev PATH
is set to the default path
.Pa ( /bin
and
.Pa /usr/bin )
while the
.Ev SHELL
is set to the default system shell
.Pq Pa /bin/sh .
.Pp
The
.Fn auth_challenge
function queries the login script defined by the current
.Ar style
for a challenge for the user specified by
.Ar name .
(See below for the setting of the
.Ar style
and
.Ar name ) .
It internally uses the
.Fn auth_call
function.
The generated challenge is returned.
.Dv NULL
is returned on error or if no challenge was generated.
The challenge can also be extracted by the
.Fn auth_getchallenge
function, which simply returns the last challenge generated
for this session.
.Pp
The
.Fn auth_check_change
and
.Fn auth_check_expire
functions check the password expiration (change) and account expiration
times.
They return 0 if no change or expiration time is set for the account.
They return a negative value of how many seconds have passed since
the password or account expired.
In this case the state of the session is marked with either
.Li AUTH_PWEXPIRED
or
.Li AUTH_EXPIRED
as well as clearing any bits which would indicate the authentication was
successful.
If the password or account has not expired, they return the number of
seconds left until the account does expire.
The return value of -1 can either indicate the password or account
just expired or that no password entry was set for the current session.
.Pp
The
.Fn auth_clrenv
function clears any requests set by a login script for
environment variables to be set.
.Pp
The
.Fn auth_clroption
function clears the previously set option
.Fa name .
.Pp
The
.Fn auth_clroptions
function clears all previously set options.
.Pp
The
.Fn auth_getitem
function returns the value of
.Fa item .
The
.Fa item
may be one of:
.Bl -tag -width AUTH_INTERACTIVE
.It Dv AUTH_CHALLENGE
The latest challenge, if any, set for the session.
.It Dv AUTH_CLASS
The class of the user, as defined by the
.Pa /etc/login.conf
file.
This value is not directly used by BSD Authentication, rather, it is
passed to the login scripts for their possible use.
.It Dv AUTH_INTERACTIVE
If set to any value, then the session is tagged as interactive.
If not set, the session is not interactive.
When the value is requested it is always either
.Dv NULL
or
.Dq True .
The auth subroutines may choose to provide additional information to
standard output or standard error when the session is interactive.
There is no functional change in the operation of the subroutines.
.It Dv AUTH_NAME
The name of the user being authenticated.
The name should include the instance, if any, that is being requested.
.It Dv AUTH_SERVICE
The service requesting the authentication.
Initially it is set to the default service which provides the traditional
interactive service.
.It Dv AUTH_STYLE
The style of authentication being performed, as defined by the
.Pa /etc/login.conf
file.
The style determines which login script should actually be used.
.El
.Pp
The value returned points to private memory and should not be
freed by the caller.
.Pp
The
.Fn auth_getvalue
function returns the value, if any, associated with the specified internal
variable
.Ar what .
These variables are set by login scripts.
When a new login script is run
(by the
.Fn auth_call
function)
the values from the previous login script are lost.
(See
.Xr login.conf 5
for details on internal variables.)
.Pp
The
.Fn auth_set_va_list
function establishes a variable argument list to be used by the
.Fn auth_call
function.
It is intended to be used by functions which need to call
.Fn auth_call
but take a variable number of arguments themselves.
Since the arguments are not copied, the call to
.Fn auth_call
must be placed within the scope of
.Fa ap .
The
.Fn auth_call
function will call
.Xr va_end 3
on
.Fa ap .
.Pp
The
.Fn auth_setdata
function makes a copy of
.Fa len
bytes of data pointed to by
.Fa ptr
for use by
.Fn auth_call .
The data will be passed on the back channel to the next login script called.
.Pp
The
.Fn auth_setenv
function adds/deletes any environment variables requested by the
login script to the current environment.
.Pp
The
.Fn auth_setitem
function assigns
.Fa value
to the specified
.Fa item .
The items are described above with the
.Fn auth_getitem
function.
In addition, if
.Fa value
is
.Dv NULL ,
the
.Fa item
is cleared.
If
.Fa value
is
.Dv NULL
and
.Fa item
is
.Li AUTH_ALL
then all items are cleared.
.Pp
The
.Fn auth_setoption
function requests that the option
.Fa name
be set with the value of
.Fa value
when a script is executed by
.Fn auth_call .
The actual arguments to the script will be placed at the beginning
of the argument vector.
For each option two arguments will be issued:
.Li -v name=value .
.Pp
The function
.Fn auth_setpwd
establishes the password file entry for the authentication session.
If the name has already been set by
.Fn auth_setitem
then the
.Fa pwd
argument may be
.Dv NULL ,
else it must be the password entry to use.
.Pp
The function
.Fn auth_getpwd
retrieves the saved password file entry for the authentication session.
If no entry has been saved (either explicitly via
.Fn auth_setpwd
or implicitly via
.Fn auth_check_expire
or
.Fn auth_check_change )
it returns
.Dv NULL .
Note that the memory containing the password file entry is freed by
a call to
.Fn auth_close
or
.Fn auth_clean .
.Pp
The function
.Fn auth_setstate
sets the sessions state to
.Fa state .
Typically this is either
.Li AUTH_OKAY
or 0.
.Sh SEE ALSO
.Xr authenticate 3 ,
.Xr login_cap 3 ,
.Xr pw_dup 3 ,
.Xr login.conf 5
.Sh CAVEATS
The
.Fn auth_check_change
and
.Fn auth_check_expire
functions call
.Fn getpwnam
or
.Fn getpwuid ,
overwriting the static storage used by the
.Xr getpwent 3
family of routines.
The calling program must either make a local copy of the passwd struct
pointer via the
.Xr pw_dup 3
function or use the
.Xr auth_setpwd 3
function to copy the passwd struct into
.Fa as .
|