AUTH_APPROVAL(3) | Library Functions Manual | AUTH_APPROVAL(3)

# NAME

`auth_approval`, `auth_cat`, `auth_checknologin`, `auth_mkvalue`, `auth_userchallenge`, `auth_usercheck`, `auth_userokay`, `auth_userresponse`, `auth_verify` — simplified interface to the BSD Authentication system

# SYNOPSIS

`#include <sys/types.h>`
`#include <login_cap.h>`
`#include <bsd_auth.h>`

int
`auth_userokay`(char *name, char *style, char *type, char *password);

auth_session_t *
`auth_userchallenge`(char *name, char *style, char *type, char **challengep);

auth_session_t *
`auth_usercheck`(char *name, char *style, char *type, char *password);

int
`auth_userresponse`(auth_session_t *as, char *response, int more);

int
`auth_approval`(auth_session_t *as, struct login_cap *lc, char *name, char *type);

int
`auth_cat`(char *file);

void
`auth_checknologin`(struct login_cap *lc);

char *
`auth_mkvalue`(char *value);

auth_session_t *
`auth_verify`(auth_session_t *as, char *style, char *name, ...);

# DESCRIPTION

These functions provide a simplified interface to the BSD Authentication system (see auth_subr(3)). The `auth_userokay`() function provides a single function call interface. Provided with a user's name in name, and an optional style, type, and password, the `auth_userokay`() function returns a simple yes/no response. A return value of 0 implies failure; a non-zero return value implies success. If style is not `NULL`, it specifies the desired style of authentication to be used. If it is `NULL` then the default style for the user is used. In this case, name may include the desired style by appending it to the user's name with a single colon (‘:’) as a separator. If type is not `NULL` then it is used as the authentication type (such as “auth-myservice”). If password is `NULL` then `auth_userokay`() operates in an interactive mode with the user on standard input, output, and error. If password is specified, `auth_userokay`() operates in a non-interactive mode and only tests the specified passwords. This non-interactive method does not work with challenge-response authentication styles. For security reasons, when a password is specified, `auth_userokay`() will zero out its value before it returns.

The `auth_usercheck`() function operates the same as the `auth_userokay`() function except that it does not close the BSD Authentication session created. Rather than returning the status of the session, it returns a pointer to the newly created BSD Authentication session.

The `auth_userchallenge`() function takes the same name, style, and type arguments as does `auth_userokay`(). However, rather than authenticating the user, it returns a possible challenge in the pointer pointed to by challengep. The return value of the function is a pointer to a newly created BSD Authentication session. This challenge, if not `NULL`, should be displayed to the user. In any case, the user should provide a password which is the response in a call to `auth_userresponse`(). In addition to the password, the pointer returned by `auth_userchallenge`() should be passed in as as and the value of more should be non-zero if the program wishes to allow more attempts. If more is zero then the session will be closed. The `auth_userresponse`() function closes the BSD Authentication session and has the same return value as `auth_userokay`(). For security reasons, when a response is specified, `auth_userresponse`() will zero out its value before it returns.

The `auth_approval`() function calls the approval script for the user of the specified type. The string “approve-” will be prepended to type if missing. The resulting type is used to look up an entry in /etc/login.conf for the user's class. If the entry is missing, the generic entry for “approve” will be used. The name argument will be passed to the approval program as the name of the user. The lc argument points to a login class structure. If it is `NULL` then a login class structure will be looked up for the class of user name. The `auth_approval`() function returns a value of 0 on failure to approve the user.

Prior to actually calling the approval script, the account's expiration time, the associated nologin file, and existence of the account's home directory (if `requirehome` is set for this class) are checked. Failure on any of these points causes the `auth_approval`() function to return a value of 0 and not actually call the approval script.

The `auth_cat`() function opens file for reading and copies its contents to standard output. It returns 0 if it was unable to open file and 1 otherwise.

The `auth_checknologin`() function must be provided with a pointer to a login class. If the class has a “nologin” entry defined and it points to a file that can be opened, the contents of the file will be copied to standard output and exit(3) will be called with a value of 1. If the class does not have the field “ignorenologin” and the file /etc/nologin exists, its contents will be copied to standard output and exit(3) will be called with a value of 1.

The `auth_verify`() function is a front end to the auth_call(3) function. It will open a BSD Authentication session, if needed, and will set the style and user name based on the style and name arguments, if not `NULL`. Values for the style and user name in an existing BSD Authentication session will be replaced and the old values freed (if the calling program has obtained pointers to the style or user name via auth_getitem(3), those pointers will become invalid). The variable arguments are passed to `auth_call`() via the auth_set_va_list(3) function. The, possibly created, BSD Authentication session is returned. The auth_getstate(3) or auth_close(3) function should be used to determine the outcome of the authentication request.

The `auth_mkvalue`() function takes a NUL-terminated string pointed to by value and returns a NUL-terminated string suitable for passing back to a calling program on the back channel. This function is for use by the login scripts themselves. The string returned should be freed by free(3) when it is no longer needed. A value of `NULL` is returned if no memory was available for the new copy of the string.

# SEE ALSO

auth_subr(3), getpwent(3), pw_dup(3)

March 31, 2022 | Debian