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