nixos/pam: assemble rules from modular configuration

[Majiir]

Description

Refactors the security.pam module to assemble /etc/pam.d files from modular rule configuration. Rules can now be modified, added, toggled, and reordered.

Problem statement

The existing module is inflexible and does not allow a user to reconfigure the PAM stack:

• Module arguments cannot be changed if there is not already a corresponding option.
• Rule control settings cannot be changed.
• Rules cannot be reordered.
• New rules can only be added at the beginning or end of the stack.

See this Discourse thread for more discussion.

Design

A rule set is defined for each service and type (account, auth, password or session). A rule set is now expressed as an attribute set of named rules:

{
  security.pam.services.su.rules.auth = {
    wheel = {
      enable = true;
      control = "required";
      modulePath = "pam_wheel.so";
      order = config.security.pam.services.su.rules.auth.unix.order - 10;
    };
  };
}

The rule name (attribute key) can be used to merge multiple configurations of the same rule (e.g. to override a built-in rule).

Rules have an order option which determines the order the rules are written to the PAM config files. Built-in rules are automatically assigned an order value based on their hard-coded position. Some kind of ordering mechanism is necessary because the rules are now configured in an attribute set.

The new config options are hidden and marked experimental so that maintainers may freely modify the option design or the ordering of rules.

Example

{
  security.pam.services = let
    serviceCfg = service: {
      rules.auth = {
        unix = {
          control = lib.mkForce "requisite";
        };
        rssh = {
          order = config.security.pam.services.${service}.rules.auth.unix.order + 10;
          control = "sufficient";
          modulePath = "${pkgs.pam_rssh}/lib/libpam_rssh.so";
          settings.auth_key_file = "/etc/rssh/authorized_keys";
        };
      };
    };
  in lib.flip lib.genAttrs serviceCfg [
    "sudo"
    "su"
  ];
}

This example configures the PAM stack in ways not currently possible:

• The pam_rssh module is enabled and integrated into the existing service rules.
• The pam_unix rule is changed from requires to requisite.
• The pam_rssh rule is ordered after the pam_unix rule.
• The pam_rssh module is passed an additional auth_key_file argument.

Authentication section of the resulting /etc/pam.d/sudo file:

# Authentication management.
auth requisite pam_unix.so likeauth try_first_pass # 11600
auth sufficient /nix/store/cn5lccdcx38k81wjz42v63k8c82y2kkq-pam_rssh-1.1.0/lib/libpam_rssh.so auth_key_file=/etc/rssh/authorized_keys # 11610
auth required pam_deny.so # 12400

Review notes

• Changes are best reviewed commit-by-commit.
• Many of the commits can be reproduced with regex substitution.
• None of the commits change the behavior of the resulting PAM rules.

Related work

• nixos/pam: assemble via the module system #90640
• Use structured settings for PAM configuration #105098
• nixos/pam: rework of the entire module #105319

Since previous attempts lost steam and were abandoned, I'm hoping we can merge this smaller rework and iterate on the module design in subsequent PRs.

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • armv7l-linux (cross)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
    • pam-file-contents
    • pam-oath-login
    • pam-u2f
    • pam-ussh
    • pam-zfs-key
• Fits CONTRIBUTING.md.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/what-do-you-want-from-pam-security-pam-in-nixos/33265/1

[Majiir]

• Changed all new options to hidden.
• Renamed a couple of the new options.
• Improved commit readability.
• Fixed trailing whitespace issues.

This is ready for review! I've been running this on my daily driver without issues. The commits are easy to get through, I promise. Take a look and leave your comments! 🙇‍♂️

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/what-do-you-want-from-pam-security-pam-in-nixos/33265/8

[liff]

A quick thought (I haven’t spent time considering all the implications), but instead of a numerical ordering, would it make sense to use a DAG like home-manager does?

With something home-manager’s machinery the su example would become:

{
  security.pam.services.su.types.auth.rules = {
    unix = {
      control = lib.mkForce "requisite";
    };
    rssh = dag.entryAfter [ "unix" ] {
      control = "sufficient";
      modulePath = "${pkgs.pam_rssh}/lib/libpam_rssh.so";
      settings.auth_key_file = "/etc/rssh/authorized_keys";
    };
  };
}

This might make using entries with [value=N] controls somewhat unreliable, but I suspect that’s the case even with numbered ordering.

[rissson]

A quick thought (I haven’t spent time considering all the implications), but instead of a numerical ordering, would it make sense to use a DAG like home-manager does?

This might make using entries with [value=N] controls somewhat unreliable, but I suspect that’s the case even with numbered ordering.

During my original rework I decided against doing something like this especially because it may end with an inconsistent ordering of options. I quite like the way this PR deals with it by recommending referencing existing entries' order.

[lorenzleutgeb]

I also think that a DAG would be better.

1. The fact that one can specify a constant for order is a footgun.
2. order defaulting to 1000 + i * 10 raises eyebrows:
   a. What if I refer to more than 10 rules to be in order after each other (using the ... + 1 mechanism suggested)? Looks like I would get two rules with the same order value.
   b. What if I create more than 1000 / 10 rules? Again, it looks like I would get two rules with the same order value.
3. How are rules with the same order value placed? If there's no tie-breaking, I fear that this will be done non-deterministically, or at least the user loses control of whichever deterministic process does the ordering.

@rissson could you please explain or give an example for an "inconsistent ordering"? Generally, if the order implied by the DAG is not total, then yes, there are multiple ways of manifesting the rules in a sequence. But in that case, one can add an edge. And some deterministic tie-breaking should be considered. However, you get similar (the same?) issues with just numbering (see (2.) and (3.) above).

[Majiir]

Thanks for linking the home-manager reference. I think the DAG option is interesting!

Both DAG and order face ambiguous ordering scenarios, and I think both can be made to tie-break on the rule name. In the case of order, I think this happens already because sort is a stable sort.

With order, we can define well-known values, for example 1000 could mean "first pass", 2000 could mean "2FA", etc. With DAG, we can do something similar by ordering rules before/after some well-defined labels (almost like systemd targets).

I don't know how the DAG option handles config overrides. Is it practical for users to reorder rules? If there is a graph a -> b -> c, then setting c -> b would create a cycle, so the user would have to somehow unset b -> c in order to get a -> c -> b. Reordering like this is simpler with order at first glance.

I'm not worried about exhausting the rule space with order. We can make the spacing 100 or 1000 and make it arbitrarily unlikely that someone will declare that many PAM rules.

What if I create more than 1000 / 10 rules? Again, it looks like I would get two rules with the same order value.

The values don't wrap around. If there are many rules, the value will just get arbitrarily large. The order for a rule defined in the hardcoded list in pam.nix is 1000 + i * 10, but the default for the submodule is simply 1000.

This might make using entries with [value=N] controls somewhat unreliable, but I suspect that’s the case even with numbered ordering.

Yes, I think it's a (mild) problem with both. It can be solved with substack rules so that [value=N] controls are never needed.

---

My thinking is that for now, it doesn't matter much which one we choose. The new options are all hidden from the manual, so we can freely change the option interface in a follow-up PR. It should be easy to find and update usages inside nixpkgs.

I lean toward sticking with order because (a) it's more clear how rules may be reordered, and (b) it looks like the DAG option involves pulling some code from home-manager into nixpkgs lib. I would also like to experiment with the user experience of the DAG option to make sure it supports the main use cases.

Overall, I'm aiming to make a series of PRs to overhaul pam.nix, so it's not important that this one gets everything perfect.

Questions for all:

1. Do you agree that it's okay to stick with order for at least this first round of changes?

2. Do you think the new options being hidden is enough to let us safely break the interface in the future?

[infinisil]

Very nice PR! I love the individual commits, makes this very reviewable! The overall idea is solid, though I made some suggestions below.

[Majiir]

@infinisil Thank you for the review! This is ready for another pass.

[infinisil]

Looking good!

[infinisil]

For the record: I'm still not entirely happy about the order option, but I don't think it matters very much, these options will be marked as experimental, and it looks like you intend to continue with this effort after this is merged @Majiir.

I think it's okay to merge this as is, but let's give @rissson and @kwohlfahrt some more time to give their approval or suggestions too.

[rissson]

This is already a massive improvement as you now don't have to override the whole generated file to get what you need.

For the record: I'm still not entirely happy about the order option, but I don't think it matters very much, these options will be marked as experimental

The main issue is being sure that the order is always the same no matter what. As a user, saying that rule A needs to be after rule B is not sufficient enough. Perhaps the order being described as an int is not enough. We could also imagine asking the user for an ordered list that contains the order they want their rules in.

I'm very happy to see this making some progress, and am excited to see the next steps!

[SuperSandro2000]

I am here because I just hit a merge conflict on rebasing my fork where I changed the pam module rather than using options because the old module just didn't allow it. I just wanted to say a huge thank you to everyone involved that helped closing this giant gap! ❤️

[mjm]

I've been eagerly awaiting this PR landing in unstable so I could reorder my swaylock auth lines and make both fprintd and password work, thank you for the work that went into this!