3.2. Authentication management
Prev | Chapter 3. What is expected of a module | Next

## 3.2. Authentication management

To be correctly initialized, `PAM_SM_AUTH` must be #define'd prior to including `<security/pam_modules.h>`. This will ensure that the prototypes for static modules are properly declared.

### 3.2.1. Service function for user authentication

    #define PAM_SM_AUTH

    #include <security/pam_modules.h>

`int pam_sm_authenticate(` | pamh, |
| flags, |
| argc, |
| argv`)`; |

`pam_handle_t *pamh`;
`int flags`;
`int argc`;
`const char **argv`;

#### 3.2.1.1. DESCRIPTION

The `pam_sm_authenticate` function is the service module's implementation of the pam_authenticate(3) interface.

This function performs the task of authenticating the user.

Valid flags, which may be logically OR'd with PAM_SILENT, are:

PAM_SILENT

  Do not emit any messages.

PAM_DISALLOW_NULL_AUTHTOK

  Return PAM_AUTH_ERR if the database of authentication tokens for this authentication mechanism has a NULL entry for the user. Without this flag, such a NULL token will lead to a success without the user being prompted.

#### 3.2.1.2. RETURN VALUES

PAM_AUTH_ERR

  Authentication failure.

PAM_CRED_INSUFFICIENT

  For some reason the application does not have sufficient credentials to authenticate the user.

PAM_AUTHINFO_UNAVAIL

  The modules were not able to access the authentication information. This might be due to a network or hardware failure etc.

PAM_SUCCESS

  The authentication token was successfully updated.

PAM_USER_UNKNOWN

  The supplied username is not known to the authentication service.

PAM_MAXTRIES

  One or more of the authentication modules has reached its limit of tries authenticating the user. Do not try again.

### 3.2.2. Service function to alter credentials

    #define PAM_SM_AUTH

    #include <security/pam_modules.h>

`int pam_sm_setcred(` | pamh, |
| flags, |
| argc, |
| argv`)`; |

`pam_handle_t *pamh`;
`int flags`;
`int argc`;
`const char **argv`;

#### 3.2.2.1. DESCRIPTION

The `pam_sm_setcred` function is the service module's implementation of the pam_setcred(3) interface.

This function performs the task of altering the credentials of the user with respect to the corresponding authorization scheme. Generally, an authentication module may have access to more information about a user than their authentication token. This function is used to make such information available to the application. It should only be called after the user has been authenticated but before a session has been established.

Valid flags, which may be logically OR'd with PAM_SILENT, are:

PAM_SILENT

  Do not emit any messages.

PAM_ESTABLISH_CRED

  Initialize the credentials for the user.

PAM_DELETE_CRED

  Delete the credentials associated with the authentication service.

PAM_REINITIALIZE_CRED

  Reinitialize the user credentials.

PAM_REFRESH_CRED

  Extend the lifetime of the user credentials.

The way the auth stack is navigated in order to evaluate the `pam_setcred`() function call, independent of the `pam_sm_setcred`() return codes, is exactly the same way that it was navigated when evaluating the `pam_authenticate`() library call. Typically, if a stack entry was ignored in evaluating `pam_authenticate`(), it will be ignored when libpam evaluates the `pam_setcred`() function call. Otherwise, the return codes from each module specific `pam_sm_setcred`() call are treated as required.

#### 3.2.2.2. RETURN VALUES

PAM_CRED_UNAVAIL

  This module cannot retrieve the user's credentials.

PAM_CRED_EXPIRED

  The user's credentials have expired.

PAM_CRED_ERR

  This module was unable to set the credentials of the user.

PAM_SUCCESS

  The user credential was successfully set.

PAM_USER_UNKNOWN

  The user is not known to this authentication module.

These, non-PAM_SUCCESS, return values will typically lead to the credential stack failing. The first such error will dominate in the return value of `pam_setcred`().

Prev | Up | Next
3.1. Overview | Home | 3.3. Account management