Linux – How do PAM advanced options work, exactly

authenticationlinuxpam

I've been reading everything I can find on PAM (e.g. http://wpollock.com/AUnix2/PAM-Help.htm), however I'm still confused about how precisely the advanced options are supposed to work. For example, every reference says this:

Each of the four control-flag keywords (required, requisite, sufficient, and
optional) have an equivalent expression in terms of the [...] syntax:

required
    [success=ok new_authtok_reqd=ok ignore=ignore default=bad]

My understanding is that modules can return a variety of tokens, and that the action associated with each token is described in the configuration file. Based on that understanding, what does

new_authtok_reqd=ok

have to do with the required control flag? What's the meaning/purpose of

ignore=ignore ?

This alone:

success=ok

is what I would think matches the required behavior, but does

default=bad

mean that if the module returns any other action token, the module fails? Is the action=value token success=ok overruled by default=bad, or vice versa? Which takes precendence? It's not clear from anything I've read.

More generally, suppose I have something like

[success=done default=die]

What happens if the module returns success and one other token?

Finally, I can't find the answer to this question, either: can every value ok, done, bad, die, ignore, reset, N be associated with any action? What would it even mean to say

[default=done] ?

Best Answer

PAM modules have over 30 different return values that are mapped to either pass or fail of the whole PAM stack as stated by the configuration.

It is noteworthy that a PAM module may behave different depending on the context (auth, account, password, session) that it is called in.

The pairs of value=action in square brackets describe which action to take for each possible return value of the PAM module.

A good explanation of values and actions can be found by carefully reading the above mentioned page to the end.

  • success=ok the module has returned success, this will be honored in the evaluation of the whole PAM stack, if no preceding module has failed, consider pass for the whole stack up to this point.
  • new_authtok_reqd=ok a new authentication token is required. E.g. in session context this might make the user change her/his password.
  • ignore=ignore the PAM module wants its result to be ignored, so we ignore it.
  • default=bad all other results make the PAM stack fail (but don't stop processing subsequent modules)

What happens if the module returns success and one other token?

PAM modules return only a single value.

Finally, I can't find the answer to this question, either: can every value ok, done, bad, die, ignore, reset, N be associated with any action? What would it even mean to say

[default=done] ?

This means: any token not mentioned here (i.e. every possible token) ends processing of the PAM stack and returns the result so far.

Related Topic