1.\" $OpenBSD: authenticate.3,v 1.11 2008/04/04 17:42:39 millert 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: April 4 2008 $ 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 <login_cap.h> 50.Fd #include <bsd_auth.h> 51.Ft int 52.Fn auth_userokay "char *name" "char *style" "char *type" "char *password" 53.Ft auth_session_t * 54.Fn auth_userchallenge "char *name" "char *style" "char *type" "char **challengep" 55.Ft auth_session_t * 56.Fn auth_usercheck "char *name" "char *style" "char *type" "char *password" 57.Ft int 58.Fn auth_userresponse "auth_session_t *as" "char *response" "int more" 59.Ft int 60.Fn auth_approval "auth_session_t *as" "struct login_cap *lc" "char *name" "char *type" 61.Ft int 62.Fn auth_cat "char *file" 63.Ft void 64.Fn auth_checknologin "struct login_cap *lc" 65.Ft char * 66.Fn auth_mkvalue "char *value" 67.Ft auth_session_t * 68.Fn auth_verify "auth_session_t *as" "char *style" "char *name" "..." 69.Sh DESCRIPTION 70These functions provide a simplified interface to the BSD Authentication 71system 72.Pq see Xr bsd_auth 3 . 73The 74.Fn auth_userokay 75function provides a single function call interface. 76Provided with a user's name in 77.Ar name , 78and an optional 79.Ar style , 80.Ar type , 81and 82.Ar password , 83the 84.Fn auth_userokay 85function returns a simple yes/no response. 86A return value of 0 implies failure; a non-zero return value implies success. 87If 88.Ar style 89is not 90.Dv NULL , 91it specifies the desired style of authentication to be used. 92If it is 93.Dv NULL 94then the default style for the user is used. 95In this case, 96.Ar name 97may include the desired style by appending it to the user's name with a 98single colon 99.Pq Sq \: 100as a separator. 101If 102.Ar type 103is not 104.Dv NULL 105then it is used as the authentication type (such as 106.Dq auth-myservice ) . 107If 108.Ar password 109is 110.Dv NULL 111then 112.Fn auth_userokay 113operates in an interactive mode with the user on standard input, output, 114and error. 115If 116.Ar password 117is specified, 118.Fn auth_userokay 119operates in a non-interactive mode and only tests the specified passwords. 120This non-interactive method does not work with challenge-response 121authentication styles. 122For security reasons, when a 123.Ar password 124is specified, 125.Fn auth_userokay 126will zero out its value before it returns. 127.Pp 128The 129.Fn auth_usercheck 130function operates the same as the 131.Fn auth_userokay 132function except that it does not close the BSD Authentication session created. 133Rather than returning the status of the session, it returns 134a pointer to the newly created BSD Authentication session. 135.Pp 136The 137.Fn auth_userchallenge 138function takes the same 139.Ar name , style , 140and 141.Ar type 142arguments as does 143.Fn auth_userokay . 144However, rather than authenticating the user, it returns a possible 145challenge in the pointer pointed to by 146.Ar challengep . 147The return value of the function is a pointer to a newly created 148BSD Authentication session. 149This challenge, if not 150.Dv NULL , 151should be displayed to the user. 152In any case, the user should provide a password which is 153the 154.Ar response 155in a call to 156.Fn auth_userresponse . 157In addition to the password, the pointer returned by 158.Fn auth_userchallenge 159should be passed in as 160.Ar as 161and the value of 162.Va more 163should be non-zero if the program wishes to allow more attempts. 164If 165.Va more 166is zero then the session will be closed. 167The 168.Fn auth_userresponse 169function closes the BSD Authentication session and has the same 170return value as 171.Fn auth_userokay . 172For security reasons, when a 173.Ar response 174is specified, 175.Fn auth_userresponse 176will zero out its value before it returns. 177.Pp 178The 179.Fn auth_approval 180function calls the approval script for the user of the specified 181.Ar type . 182The string 183.Dq approve- 184will be prepended to 185.Ar type 186if missing. 187The resulting type is used to look up an entry in 188.Pa /etc/login.conf 189for the user's class. 190If the entry is missing, the generic entry for 191.Dq approve 192will be used. 193The 194.Ar name 195argument will be passed to the approval program as the name of the user. 196The 197.Ar lc 198argument points to a login class structure. 199If it is 200.Dv NULL 201then a login class structure will be looked up for the class of 202user 203.Ar name . 204The 205.Fn auth_approval 206function returns a value of 0 on failure to approve the user. 207.Pp 208Prior to actually calling the approval script, the account's 209expiration time, the associated nologin file, and existence 210of the account's home directory 211.Po 212if 213.Li requirehome 214is set for this class 215.Pc 216are checked. 217Failure on any of these points causes the 218.Fn auth_approval 219function to return a value of 0 and not actually call the approval script. 220.Pp 221The 222.Fn auth_cat 223function opens 224.Ar file 225for reading and copies its contents to standard output. 226It returns 0 if it was unable to open 227.Ar file 228and 1 otherwise. 229.Pp 230The 231.Fn auth_checknologin 232function must be provided with a pointer to a login class. 233If the class has a 234.Dq nologin 235entry defined and it points to a file that can be opened, 236the contents of the file will be copied to standard output and 237.Xr exit 3 238will be called with a value of 1. 239If the class does not have the field 240.Dq ignorenologin 241and the file 242.Pa /etc/nologin 243exists its contents will be copied to standard output and 244.Xr exit 3 245will be called with a value of 1. 246.Pp 247The 248.Fn auth_verify 249function is a front end to the 250.Xr auth_call 3 251function. 252It will open a BSD Authentication session, if needed, and will set 253the style and user name based on the 254.Ar style 255and 256.Ar name 257arguments, if not 258.Dv NULL . 259Values for the style and user name in an existing BSD Authentication 260session will be replaced and the old values freed (if the calling program 261has obtained pointers to the style or user name via 262.Xr auth_getitem 3 , 263those pointers will become invalid). 264The variable arguments are passed to 265.Fn auth_call 266via the 267.Xr auth_set_va_list 3 268function. 269The, possibly created, BSD Authentication session is returned. 270The 271.Xr auth_getstate 3 272or 273.Xr auth_close 3 274function 275should be used to determine the outcome of the authentication request. 276.Pp 277The 278.Fn auth_mkvalue 279function takes a NUL-terminated string pointed to by 280.Ar value 281and returns a NUL-terminated string suitable for passing 282back to a calling program on the back channel. 283This function is for use by the login scripts themselves. 284The string returned should be freed by 285.Xr free 3 286when it is no longer needed. 287A value of 288.Dv NULL 289is returned if no memory was available for the new copy of the string. 290.Sh SEE ALSO 291.Xr auth_subr 3 , 292.Xr getpwent 3 , 293.Xr pw_dup 3 294.Sh CAVEATS 295The 296.Fn auth_approval , 297.Fn auth_usercheck , 298.Fn auth_userokay , 299and 300.Fn auth_userchallenge 301functions call 302.Xr getpwnam 3 303or 304.Xr getpwuid 3 , 305overwriting the static storage used by the 306.Xr getpwent 3 307family of routines. 308The calling program must either make a local copy of the passwd struct 309pointer via the 310.Xr pw_dup 3 311function or, for 312.Fn auth_approval 313and 314.Fn auth_usercheck 315only, use the 316.Xr auth_setpwd 3 317function to copy the passwd struct into a BSD Authentication session structure 318which can then be passed to 319.Fn auth_approval 320or 321.Fn auth_usercheck . 322