The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Authen-SimplePam-0.1.24
River stage zero No dependents
++
/ Authen::SimplePam

NAME

Authen::SimplePam - Simple interface to PAM authentication

SYNOPSIS

  use Authen::SimplePam;
  $auth = new Authen::PAM;
  $auth->auth_user( $user, $password, $service );
  $auth->change_password ( $user, $old_password, $new_password );

DESCRIPTION

This module simplifies the use of PAM to Authenticate users.

It makes things simple so that no PAM knowledge is necessary.

API

The API is simple:

  • new

    Creates a Authen::SimplePam object.

  • username ( $username )

    If the parameter $username is set, it sets the username. It will return the current username.

  • user ( $username )

    Same as username().

  • name ( $username )

    Same as username().

  • current_password ( $password )

    The user current password. If $password is given, the password is set. It will return the current set password.

  • password ( $password )

    Same as current_password().

  • old_password( $password )

    Same as current_password().

  • new_password ( $password )

    If $password is present, it will set the user new password. It returns the current set new password.

  • service ( $service )

    If $service is given, it will set the PAM service to use. It will return the current service set.

  • pam_result ()

    Returns the last PAM result code.

  • error_code ()

    Returns undef if no error has happened, otherwise returns the error code.

  • error_message ()

    Returns undef if no error has happened, otherwise returns the error message.

    Note that the error message is the pam message give to a PAM_ERROR_MSG call.

    Other error might have happened, but did not set PAM_ERROR_MSG, but is in the result code from the functions auth_user () and change_password ().

  • auth_user ($user, $password, $service)

    Authenticates a user $user, with the passwod $password agains service $service.

    Note that $user, $password and $service are optional. If given they will overwrite any previously given one.

    If no $serice has being yet specified, it will defaults to the service 'login'.

    If no $username has being yet specified, it will defaults to the current EFECTIVE USER ID (EUID).

    It will return Authen::SimplePam own result code. If you would like to know the real PAM result code, use pam_result() to get it.

    To get and string representation of the result, use result2string () .

  • result2string ($result)

    Converts a result returned by auth_user() or change_password () to a string.

RETURN CODES

These are the return codes returned by auth_user and change_password.

0 Error using the Authen::PAM module.

Usually broken installation.

1 Success.

The password match.

2 Error.

The password does not match.

3 Insufficient Credentials.

For some reason the application does not have enough credentials to authenticate the user. E.g. A non-root user trying to authenticate/validate the root user password.

4 Authentication information unavailable.

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

5 User Unknown.

The supplied username is not known to the authentication service

6 Maximum tries.

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

7 Unknown error.

Some unpredictable error happened.

8 Authentication manipulation error.

Some error regarding the authentication happened. Usually the service being used is invalid or is not well configured or requires some kind of special behaviour from Authen::SimplePam.

*TODO* Finish description of return values.

NOTES

MODULES

It is important to know that the way PAM will act depends on the underlying modules being used and how they are stacked on the services.

So far, theis module has being tested with pam modules pam_pwdb.so (which is a newer version of pam_unix.so) and pam_cracklib.so which tests the stregth of new passwords.

Other modules might ask for different data and give different errors.

Authen::SimplePAM is written in a way that it is simple to insert this new authentication modules.

SERVICES

Different services might have different results.

e.g. It is common to deny login to the user root if he is not using a console if the service is 'login', however other services (like kde) might allow this.

If you use different PAM configuration and Authen::SimplePam is not working, you can try to contact the author and provide as much information as possible in order to let him understand what is missing and improve the module.

CHANGING PASSWORD

It is important to understand that changing passwords might not be as simple as it seem and you probably can not do it unless you are the root user.

The reason is simple, for most of the cases where the password is stored in the /etc/passwd or /etc/shadow or any file in the system, the user needs written permission to update it. Usually only root has it.

As a side note the passwd program that changes the password, runs suid.

There is an issue (at least with pam_pwdb.so and pam_unix.so modules) with suid.

If the UID (user id) is different from the EUID (effective user id), and EUID is 0 (root), these modules will ask for the current password before updating the account information.

Usually EUID == 0 and UID != EUID means that it is running in a suid script/app, so this extra care is needed.

However if UID == EUID == 0, means that the user is really root, so no confirmation of the current password is needed to change an user account.

This can be done with $< = $> = 0; in a suid script, however this might be a great security risk and I discourage that.

BUGS

Plesse report bugs, sugestions and Criticism to the AUTHOR.

LICENSE

GPL

AUTHOR

Raul Dias <raul@dias.com.br>

SEE ALSO

Authen::PAM.