1.\" $OpenBSD: authenticate.3,v 1.12 2009/07/15 07:53:56 schwarze Exp $ 2.\" 3.\" Copyright (c) 1997 Berkeley Software Design, Inc. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by Berkeley Software Design, 16.\" Inc. 17.\" 4. The name of Berkeley Software Design, Inc. may not be used to endorse 18.\" or promote products derived from this software without specific prior 19.\" written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN, INC. ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN, INC. BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" BSDI $From: authenticate.3,v 2.7 1998/09/03 20:27:20 prb Exp $ 34.Dd $Mdocdate: July 15 2009 $ 35.Dt AUTHENTICATE 3 36.Os 37.Sh NAME 38.Nm auth_approval , 39.Nm auth_cat , 40.Nm auth_checknologin , 41.Nm auth_mkvalue , 42.Nm auth_userchallenge , 43.Nm auth_usercheck , 44.Nm auth_userokay , 45.Nm auth_userresponse , 46.Nm auth_verify 47.Nd simplified interface to the BSD Authentication system 48.Sh SYNOPSIS 49.Fd #include <sys/types.h> 50.Fd #include <login_cap.h> 51.Fd #include <bsd_auth.h> 52.Ft int 53.Fn auth_userokay "char *name" "char *style" "char *type" "char *password" 54.Ft auth_session_t * 55.Fn auth_userchallenge "char *name" "char *style" "char *type" "char **challengep" 56.Ft auth_session_t * 57.Fn auth_usercheck "char *name" "char *style" "char *type" "char *password" 58.Ft int 59.Fn auth_userresponse "auth_session_t *as" "char *response" "int more" 60.Ft int 61.Fn auth_approval "auth_session_t *as" "struct login_cap *lc" "char *name" "char *type" 62.Ft int 63.Fn auth_cat "char *file" 64.Ft void 65.Fn auth_checknologin "struct login_cap *lc" 66.Ft char * 67.Fn auth_mkvalue "char *value" 68.Ft auth_session_t * 69.Fn auth_verify "auth_session_t *as" "char *style" "char *name" "..." 70.Sh DESCRIPTION 71These functions provide a simplified interface to the BSD Authentication 72system 73.Pq see Xr bsd_auth 3 . 74The 75.Fn auth_userokay 76function provides a single function call interface. 77Provided with a user's name in 78.Ar name , 79and an optional 80.Ar style , 81.Ar type , 82and 83.Ar password , 84the 85.Fn auth_userokay 86function returns a simple yes/no response. 87A return value of 0 implies failure; a non-zero return value implies success. 88If 89.Ar style 90is not 91.Dv NULL , 92it specifies the desired style of authentication to be used. 93If it is 94.Dv NULL 95then the default style for the user is used. 96In this case, 97.Ar name 98may include the desired style by appending it to the user's name with a 99single colon 100.Pq Sq \: 101as a separator. 102If 103.Ar type 104is not 105.Dv NULL 106then it is used as the authentication type (such as 107.Dq auth-myservice ) . 108If 109.Ar password 110is 111.Dv NULL 112then 113.Fn auth_userokay 114operates in an interactive mode with the user on standard input, output, 115and error. 116If 117.Ar password 118is specified, 119.Fn auth_userokay 120operates in a non-interactive mode and only tests the specified passwords. 121This non-interactive method does not work with challenge-response 122authentication styles. 123For security reasons, when a 124.Ar password 125is specified, 126.Fn auth_userokay 127will zero out its value before it returns. 128.Pp 129The 130.Fn auth_usercheck 131function operates the same as the 132.Fn auth_userokay 133function except that it does not close the BSD Authentication session created. 134Rather than returning the status of the session, it returns 135a pointer to the newly created BSD Authentication session. 136.Pp 137The 138.Fn auth_userchallenge 139function takes the same 140.Ar name , style , 141and 142.Ar type 143arguments as does 144.Fn auth_userokay . 145However, rather than authenticating the user, it returns a possible 146challenge in the pointer pointed to by 147.Ar challengep . 148The return value of the function is a pointer to a newly created 149BSD Authentication session. 150This challenge, if not 151.Dv NULL , 152should be displayed to the user. 153In any case, the user should provide a password which is 154the 155.Ar response 156in a call to 157.Fn auth_userresponse . 158In addition to the password, the pointer returned by 159.Fn auth_userchallenge 160should be passed in as 161.Ar as 162and the value of 163.Va more 164should be non-zero if the program wishes to allow more attempts. 165If 166.Va more 167is zero then the session will be closed. 168The 169.Fn auth_userresponse 170function closes the BSD Authentication session and has the same 171return value as 172.Fn auth_userokay . 173For security reasons, when a 174.Ar response 175is specified, 176.Fn auth_userresponse 177will zero out its value before it returns. 178.Pp 179The 180.Fn auth_approval 181function calls the approval script for the user of the specified 182.Ar type . 183The string 184.Dq approve- 185will be prepended to 186.Ar type 187if missing. 188The resulting type is used to look up an entry in 189.Pa /etc/login.conf 190for the user's class. 191If the entry is missing, the generic entry for 192.Dq approve 193will be used. 194The 195.Ar name 196argument will be passed to the approval program as the name of the user. 197The 198.Ar lc 199argument points to a login class structure. 200If it is 201.Dv NULL 202then a login class structure will be looked up for the class of 203user 204.Ar name . 205The 206.Fn auth_approval 207function returns a value of 0 on failure to approve the user. 208.Pp 209Prior to actually calling the approval script, the account's 210expiration time, the associated nologin file, and existence 211of the account's home directory 212.Po 213if 214.Li requirehome 215is set for this class 216.Pc 217are checked. 218Failure on any of these points causes the 219.Fn auth_approval 220function to return a value of 0 and not actually call the approval script. 221.Pp 222The 223.Fn auth_cat 224function opens 225.Ar file 226for reading and copies its contents to standard output. 227It returns 0 if it was unable to open 228.Ar file 229and 1 otherwise. 230.Pp 231The 232.Fn auth_checknologin 233function must be provided with a pointer to a login class. 234If the class has a 235.Dq nologin 236entry defined and it points to a file that can be opened, 237the contents of the file will be copied to standard output and 238.Xr exit 3 239will be called with a value of 1. 240If the class does not have the field 241.Dq ignorenologin 242and the file 243.Pa /etc/nologin 244exists its contents will be copied to standard output and 245.Xr exit 3 246will be called with a value of 1. 247.Pp 248The 249.Fn auth_verify 250function is a front end to the 251.Xr auth_call 3 252function. 253It will open a BSD Authentication session, if needed, and will set 254the style and user name based on the 255.Ar style 256and 257.Ar name 258arguments, if not 259.Dv NULL . 260Values for the style and user name in an existing BSD Authentication 261session will be replaced and the old values freed (if the calling program 262has obtained pointers to the style or user name via 263.Xr auth_getitem 3 , 264those pointers will become invalid). 265The variable arguments are passed to 266.Fn auth_call 267via the 268.Xr auth_set_va_list 3 269function. 270The, possibly created, BSD Authentication session is returned. 271The 272.Xr auth_getstate 3 273or 274.Xr auth_close 3 275function 276should be used to determine the outcome of the authentication request. 277.Pp 278The 279.Fn auth_mkvalue 280function takes a NUL-terminated string pointed to by 281.Ar value 282and returns a NUL-terminated string suitable for passing 283back to a calling program on the back channel. 284This function is for use by the login scripts themselves. 285The string returned should be freed by 286.Xr free 3 287when it is no longer needed. 288A value of 289.Dv NULL 290is returned if no memory was available for the new copy of the string. 291.Sh SEE ALSO 292.Xr auth_subr 3 , 293.Xr getpwent 3 , 294.Xr pw_dup 3 295.Sh CAVEATS 296The 297.Fn auth_approval , 298.Fn auth_usercheck , 299.Fn auth_userokay , 300and 301.Fn auth_userchallenge 302functions call 303.Xr getpwnam 3 304or 305.Xr getpwuid 3 , 306overwriting the static storage used by the 307.Xr getpwent 3 308family of routines. 309The calling program must either make a local copy of the passwd struct 310pointer via the 311.Xr pw_dup 3 312function or, for 313.Fn auth_approval 314and 315.Fn auth_usercheck 316only, use the 317.Xr auth_setpwd 3 318function to copy the passwd struct into a BSD Authentication session structure 319which can then be passed to 320.Fn auth_approval 321or 322.Fn auth_usercheck . 323