In message <Pine.NEB.4.05.9811232246280.26398-100000@duhnet.net>, Todd Vierling
 writes:
>I am running on the assumption that bsdauth contains *one* main function: an
>affirmative/negative response to the question "will you authenticate this
>user for a login session with these credentials?".  If this assumption is
>wrong, would someone please stand up and explain the BSD Auth system in a
>little more technical detail?

Hmm.

I'll just include the 'low level' man page; there's also a higher-level
interface, but this is the one that has all the weird features.

>BSD_AUTH(3)		 BSD Programmer's Manual		BSD_AUTH(3)
>
>NAME
>     auth_open, auth_call, auth_challenge, auth_check_change,
>     auth_check_expire, auth_clean, auth_close, auth_clrenv, auth_clroption,
>     auth_clroptions, auth_getitem auth_getstate, auth_getvalue,
>     auth_set_va_list, auth_setdata, auth_setenv, auth_setitem auth_setoption,
>     auth_setpwd, auth_setstate - interface to the BSD Authentication system
>
>SYNOPSIS
>     #include <login_cap.h>
>     #include <bsd_auth.h>
>
>     auth_session_t *
>     auth_open();
>
>     int
>     auth_close(auth_session_t *as);
>
>     int
>     auth_call(auth_session_t *as, char *path, ...);
>
>     char *
>     auth_challenge(auth_session_t *as);
>
>     quad_t
>     auth_check_change(auth_session_t *as);
>
>     quad_t
>     auth_check_expire(auth_session_t *as);
>
>     void
>     auth_clean(auth_session_t *as);
>
>     void
>     auth_clrenv(auth_session_t *as);
>
>     void
>     auth_clroption(auth_session_t * as, char *name);
>
>     void
>     auth_clroptions(auth_session_t *as);
>
>     char *
>     auth_getitem(auth_session_t *as, auth_item_t item);
>
>     int
>     auth_getstate(auth_session_t *as);
>
>     char *
>     auth_getvalue(auth_session_t *as, char *what);
>
>     void
>     auth_set_va_list(auth_session_t *as, va_list ap);
>
>     int
>     auth_setdata(auth_session_t *as, void *ptr, size_t len);
>
>     void
>     auth_setenv(auth_session_t *as);
>
>     int
>     auth_setitem(auth_session_t *as, auth_item_t item, char *value);
>
>     int
>     auth_setoption(auth_session_t *as, char *name, char *value);
>
>     int
>     auth_setpwd(auth_session_t *as, struct passwd *pwd);
>
>     int
>     auth_setstate(auth_session_t *as, int state);
>
>DESCRIPTION
>     These functions provide the lower level interface to the BSD Authentica-
>     tion system.  They all operate on a BSD Authentication session pointer,
>     as, which is returned by auth_open().  The session pointer must be passed
>     to all other BSD Authentication functions called.	The auth_open() func-
>     tion returns NULL if it was unable to allocate memory for the session.
>     The session is terminated by the auth_close() function, which also sets
>     any environment variables requested by the login script (assuming the us-
>     er was not rejected) or removes files created by the login script if the
>     authentication was not successful.	It returns the final state of the au-
>     thentication request.  A return value of 0 implies the user was not au-
>     thenticated.  A non-zero return value is made up the 1 or more of the
>     following values ORed together:
>
>     AUTH_OKAY	The user was authenticated.
>
>     AUTH_ROOTOKAY    The user was authenticated with a root instance.
>
>     AUTH_SECURE      The user was authenticated via a mechanism which is not
>		      subject to eavesdropping attacks (such as provided by
>		      token cards).
>
>     The full state of the session is returned by the auth_getstate() func-
>     tion.  In addition to the values above, it also may contain the bits:
>
>     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 users pass-
>		      word, for instance.  This value is stripped off for nor-
>		      mal returns.
>
>     AUTH_CHALLENGE   The user was not authenticated for access and a chal-
>		      lenge 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.
>
>     AUTH_EXPIRED     The users account has expired.
>
>     AUTH_PWEXPIRED   The users password has expired and needs to be changed.
>
>     A session may be cleaned by calling auth_clean().	This function causes
>     any files created by a login script in this session and clears all state
>     associated with this session.
>
>     The remaining functions are described in alphabetical order.
>
>     The fundamental function for doing BSD Authentication is auth_call().  In
>     addition to the pointer to the BSD Authentication session, it takes the
>     following parameters:
>
>     path    The full path name of the login script to run.  The call will
>	     fail if path does not pass the requirements of the secure_path(3)
>	     function.
>
>     ...     The remaining arguments, which should be of type char * and ter-
>	     minated with a NULL are passed to the login script at the end of
>	     the command line.
>
>     The auth_call() function, after verifying the path, creates a bi-direc-
>     tional pipe (socketpair) which is located on file descriptor 3 for the
>     child (the login script).	This is known as the ``back channel''. The ac-
>     tual command line passed to the child is made up of 3 parts.  The parame-
>     ters passed to auth_call() following path have appended to them any argu-
>     ments specified by the auth_set_va_list() function.  These are typically
>     the variable arguments passed to the function that calls auth_call().
>     Any option values set by the auth_setoption() function are inserted be-
>     tween the first argument (the command name) and the second argument with
>     a preceeding -v flag.  The name and value are separated by an `=':
>
>	  -v name=value
>
>     Once the login script has been spawned, any data specified by the
>     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 in-
>     formation, such as a password).  Once any data is written out,
>     auth_call() reads up to 8192 bytes of data from the back channel.	The
>     state of the session is determined from this data (see 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
>     auth_call() is retained.
>
>     The data read from the back channel is also used by the auth_getvalue()
>     and auth_close() functions.  Subsequent calls to auth_call() will cause
>     this data to be lost and overwritten with the new data read from the new
>     call.
>
>     The environment passed to the login script by auth_call() only contains
>     two values: PATH and SHELL. The PATH is set to the default path ( /bin
>     and /usr/bin) while the SHELL is set to the default system shell (
>     /bin/sh).
>
>     The auth_challenge() function queries the login script defined by the
>     current style for a challenge for the user specified by name. (See below
>     for the setting of the style and name). It internally uses the
>     auth_call() function.  The generated challenge is returned.  NULL is re-
>     turned on error or if no challenge was generated.	The challenge can also
>     be extracted by the auth_getchallenge() function, which simply returns
>     the last challenge generated for this session.
>
>     The auth_check_change() and auth_check_expire() functions check the pass-
>     word expiration (change) and account expiration times.  They return 0 if
>     no change or expiration time is set for the account.  They return a nega-
>     tive 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
>     AUTH_PWEXPIRED or 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 now password entry was set for the current
>     session.
>
>     The auth_clrenv() function clears any requests set by a login script for
>     environment variables to be set.
>
>     The auth_clroption() function clears the previously set option name.
>
>     The auth_clroptions() function clears all previously set options.
>
>     The auth_getitem() function returns the value of of item. The item may be
>
>     one of:
>
>     AUTH_CHALLENGE   The latest challenge, if any, set for the session.
>
>     AUTH_CLASS	The class of the user, as defined by the /etc/login.conf
>		      file.  This value is not directly used by BSD Authenti-
>		      cation, rather, it is passed to the login scripts for
>		      their possible use.
>
>     AUTH_NAME	The name of the user being authenticated.	The name
>		      should include the instance, if any, that is being re-
>		      quested.
>
>     AUTH_SERVICE     The service requesting the authentication.  Initially it
>		      is set to the default service which provides the tradi-
>		      tional interactive service.
>
>     AUTH_STYLE	The style of authentication being performed, as defined
>		      by the /etc/login.conf file. The style determines which
>		      login script should actually be used.
>
>     The auth_getvalue() function returns the value, if any, associated with
>     the specified internal variable what. These variables are set by login
>     scripts.  When a new login script is run (by the auth_call(function)) the
>     values from the previous login script are lost.  (See login.conf(5) for
>     details on internal variables.)
>
>     The auth_set_va_list() function establishes a variable argument list to
>     be used by the auth_call() function.  It is intended to be used by func-
>     tions which need to call auth_call() but take a variable number of argu-
>     ments themselves.	Since the arguments are not copied, the call to
>     auth_call() must be placed within the scope of ap. The auth_call() func-
>     tion will call va_end(3) on ap.
>
>     The auth_setdata() function makes a copy of len bytes of data pointed to
>     by ptr for use by auth_call().  The data will be passed on the back chan-
>     nel to the next login script called.
>
>     The auth_setenv() function adds any environment variables requested by
>     the login script to the current environment.
>
>     The auth_setitem() function assigns value to the specified item. The
>     items are described above with the auth_getitem() function.  In addition,
>     if item is AUTH_ALL and value is NULL then all items are cleared.
>
>     The auth_setoption() function requests that the option name be set with
>     the value of value when a script is executed by 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: -v name=value.
>
>     The function auth_setpwd() establishes the password file entry for the
>     authentication session.  If the name has already been set by
>     auth_setitem() then the pwd argument may be NULL, else it must be the
>     password entry to use.
>
>     The function auth_setstate() sets the sessions state to state. Typically
>     this is either AUTH_OKAY or 0.
>
>SEE ALSO
>     authenticate(3),  auth_compat(3),	login_cap(3),  login.conf(5)
>
>BSDI BSD/OS			March 20, 1997				4

-s