$ date

Sun Dec 04 17:50:21 UTC 2016

PAM and pam_lua Introduction

This is meant as a small introduction to PAM and pam_lua, mainly as a "what to read next" style guide.


PAM stands for "Pluggable Authentication Modules" and it is a library/infrastructure for just that.

First, we need to clear what it does.

PAM manages:

1) Credential authentication

2) Account management and credential changing

3) Session management.

There are three main parts involved in using PAM:

+-----+      +-------------+      +-------------+
| APP | <--> | PAM Library | <--> | PAM Modules |
+-----+      +-------------+      +-------------+

On pretty much any PAM-based system, there are multiple modules used, because they are supposed to be simple and chainable.

The combination of these pam modules do the job, resulting in a rather customizable setup.

A few common PAM modules are the following:


Configuration of PAM is quite nice. It is profile based, modular, ...

Sadly, a configuration guide would not only be OS specific, but also distribution specific.

Therefore, I won't cover it. I advise you to look at your distributions documentation.

I hope I could get the basics of PAM down. This writeup most likely contains mistakes, so be warned.


pam_lua is a pam module for Lua scripting, just like it's name sounds.

It allows Lua to be used to write PAM modules, allowing you to quickly and easily write new authentication methods.

It's located here.

It's README contains the documentation and an example.

It should be quite easy for anyone knowing Lua to write their own authentication script.

However, given that you write the script, if you fuck up, someone could get into your system.

One possible use case for this is a custom second-factor authentication method, which is what I intended it for.

Another one would be to set up the session by setting environment variables, printing a banner, the time or something similar.

Both aren't very hard to do with pam_lua and don't require recompiling anything. Or dealing with the raw PAM API.

$ cd ..