The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Authen::SimplePam - Simple interface to PAM authentication


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


This module simplifies the use of PAM to Authenticate users.

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


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.


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.



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 (which is a newer version of and 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.


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.


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 and 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.


Plesse report bugs, sugestions and Criticism to the AUTHOR.




Raul Dias <>