.\" $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 .Fd #include .Fd #include .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 .