HP-UX Reference (11i v2 07/12) - 3 Library Functions N-Z (vol 7)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

111

112

113

114

115

116

117

118

119

120

pam_authenticate(3) pam_authenticate(3)

NAME

pam_authenticate() - perform authentication within the PAM framework

SYNOPSIS

cc [ ﬂag ... ] ﬁle ...

-lpam [ library ... ]

#include <security/pam_appl.h>

int pam_authenticate(pam_handle_t *

pamh, int ﬂags);

DESCRIPTION

pam_authenticate()

is called to authenticate the current user. The user is usually required to enter

a password or similar authentication token depending upon the authentication service conﬁgured within

the system. In the case of smart card authentication this token would be a PIN (Personal Identiﬁcation

Number). The user in question should have been speciﬁed by a prior call to

pam_start() or

pam_set_item()

. The following ﬂags may be set in the ﬂags ﬁeld:

PAM_SILENT

Authentication service should not generate any messages

PAM_DISALLOW_NULL_AUTHTOK

The authentication service should return

PAM_AUTH_ERROR if the user has a null authentica-

tion token

APPLICATION USAGE

Refer to pam(3) for information on thread-safety of PAM interfaces.

NOTES

In the case of authentication failures due to an incorrect username or password, it is the responsibility of

the application to retry

pam_authenticate()

and to maintain the retry count. An authentication ser-

vice module may implement an internal retry count and return an error

PAM_MAXTRIES if the module

does not want the application to retry.

If the PAM framework can not load the authentication module, then it will return

PAM_ABORT. This indi-

cates a serious failure and that the application should not attempt to retry the authentication.

For security reasons, the location of authentication failures is hidden from the user. Thus, if several

authentication services are stacked and a single service fails,

pam_authenticate() requires that the

user re-authenticate to all the services.

A null authentication token in the authentication database will result in successful authentication unless

PAM_DISALLOW_NULL_AUTHTOK

was speciﬁed. In such cases, there will not be any prompting for the

user to enter an authentication token.

The authentication can be done through a smart card. In this case the user plugs their smart card in the

smart card reader and is required to enter their smart card PIN.

RETURN VALUE

Upon successful completion, PAM_SUCCESS is returned. In addition to the error return values described

in pam(3), the following values may be returned:

PAM_AUTH_ERR Authentication failure.

PAM_CRED_INSUFFICIENT Can not access authentication data due to insufﬁcient credentials.

PAM_AUTHINFO_UNAVAIL Underlying authentication service can not retrieve authentication infor-

mation.

PAM_USER_UNKNOWN User not known to the underlying authentication module.

PAM_MAXTRIES An authentication service has maintained a retry count which has been

reached. No further retries should be attempted.