BSD authentication routines from BSDI. Presently this is not used but

the login_* helper programs and other support will be committed in the
near future.

1 files changed, 461 insertions, 0 deletions

diff --git a/lib/libc/gen/auth_subr.3 b/lib/libc/gen/auth_subr.3
new file mode 100644
index 00000000000..7df98cef99d
--- /dev/null
+++ b/lib/libc/gen/auth_subr.3
@@ -0,0 +1,461 @@
+.\"	$OpenBSD: auth_subr.3,v 1.1 2000/11/21 00:51:16 millert 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 March 20, 1997
+.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_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 <login_cap.h>
+.Fd #include <bsd_auth.h>
+.Ft auth_session_t *
+.Fn auth_open
+.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 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 int
+.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
+.Nm 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 the 1 or more of the following values ORed together:
+.Bl -tag -width AUTH_ROOTOKAYXX
+.It Li AUTH_OKAY
+The user was authenticated.
+.It Li AUTH_ROOTOKAY
+The user was authenticated with a root instance.
+.It Li AUTH_SECURE
+The user was authenticated via a mechanism which is not subject to
+eavesdropping attacks (such as provided by token cards).
+.El
+.sp
+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 Li 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 password, for instance.
+This value is stripped off for normal returns.
+.It Li 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 Li AUTH_EXPIRED
+The user's account has expired.
+.It Li AUTH_PWEXPIRED
+The user's password has expired and needs to be changed.
+.El
+.sp
+A session may be cleaned
+by calling
+.Fn auth_clean .
+This function causes any files created by a login script in this
+session and clears all state associated with this session.
+It is not necessary to call
+.Fn auth_clean
+if
+.Fn auth_close
+is called.
+.sp
+The remaining functions are described in alphabetical order.
+.sp
+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
+.Ft char *
+and terminated with a
+.Ev 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 preceeding
+.Fl v
+flag.
+The name and value are separated by an
+.Sq = :
+.sp
+.Li Ta Fl v Ar name=value
+
+.sp
+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.
+.sp
+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.
+.sp
+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 (
+.Pa /bin/sh ) .
+.sp
+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.
+.Nm 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.
+.sp
+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.
+.sp
+The
+.Fn auth_clrenv
+function clears any requests set by a login script for
+environment variables to be set.
+.sp
+The
+.Fn auth_clroption
+function clears the previously set option
+.Fa name .
+.sp
+The
+.Fn auth_clroptions
+function clears all previously set options.
+.sp
+The
+.Fn auth_getitem
+function returns the value of of
+.Fa item .
+The
+.Fa item
+may be one of:
+.Bl -tag -width AUTH_ROOTOKAYXX
+.It Li AUTH_CHALLENGE
+The latest challenge, if any, set for the session.
+.It Li 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 Li 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
+.Nm 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 Li AUTH_NAME
+The name of the user being authenticated.
+The name should include the instance, if any, that is being requested.
+.It Li AUTH_SERVICE
+The service requesting the authentication.
+Initially it is set to the default service which provides the traditional
+interactive service.
+.It Li 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
+.sp
+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.)
+.sp
+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 .
+.sp
+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.
+.sp
+The
+.Fn auth_setenv
+function adds/deletes any environment variables requested by the
+login script to the current environment.
+.sp
+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 item
+is
+.Li AUTH_ALL
+and
+.Fa value
+is
+.Li NULL
+then all items are cleared.
+.sp
+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 .
+.sp
+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 NULL, else it must be the password entry to use.
+.sp
+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 login.conf 5