pam

oo7 PAM Module

A PAM (Pluggable Authentication Modules) module that integrates with the oo7 Secret Service daemon to automatically unlock keyrings during user authentication.

How It Works

The PAM module communicates with the oo7 daemon via a Unix domain socket to securely transmit the user's login password for keyring unlocking:

1. Socket Creation: The daemon (running as the user) creates the Unix domain socket at $XDG_RUNTIME_DIR/oo7/pam.sock (typically /run/user/$UID/oo7/pam.sock, or path specified by OO7_PAM_SOCKET)

   • Owner: The user running the daemon
   • Permissions: 0600 (read/write by owner only)
   • Process: The user's Secret Service daemon

2. Authentication Flow:

   • User enters their password during login e.g., GDM
   • PAM calls pam_oo7.so during the authentication phase
   • The PAM module writes the username and password to the socket
   • The daemon reads the credentials from the socket
   • The daemon uses the password to attempt unlocking the default keyring

Building

Build the PAM module as a shared library:

cargo build --release -p pam_oo7

The resulting library will be at: target/release/libpam_oo7.so

Installation

1. Copy the PAM module

sudo cp target/release/libpam_oo7.so /usr/lib64/security/pam_oo7.so
# or on some systems:
sudo cp target/release/libpam_oo7.so /lib/x86_64-linux-gnu/security/pam_oo7.so

2. Configure PAM

Add the module to your PAM configuration. For example, in /etc/pam.d/system-auth or /etc/pam.d/common-auth:

auth       optional     pam_oo7.so

Important: Use optional so that authentication doesn't fail if the oo7 daemon is not running.

Example PAM configuration for GDM

In /etc/pam.d/gdm-password:

#%PAM-1.0
auth       required     pam_env.so
auth       required     pam_unix.so
auth       optional     pam_oo7.so
account    required     pam_unix.so
password   required     pam_unix.so
password   optional     pam_oo7.so
session    required     pam_unix.so
session    optional     pam_oo7.so auto_start
session    optional     pam_systemd.so

Important: The module should be added to three PAM stacks:

• auth stack: Captures and stashes the password during authentication
• session stack: Retrieves the stashed password and sends it to the daemon for keyring unlocking
• password stack: Intercepts password changes and updates the keyring password to match

Password Change Support

When added to the password stack, the module will automatically update your keyring passwords when you change your user password (e.g., using passwd command). This ensures your keyrings remain accessible after password changes.

The module intercepts the password change operation:

1. Captures both the old and new passwords
2. Sends them to the daemon
3. The daemon validates the old password and re-encrypts all matching keyrings with the new password

Configuration

Environment Variables

• OO7_PAM_SOCKET: Path to the Unix domain socket for daemon communication
  • Default: $XDG_RUNTIME_DIR/oo7/pam.sock (typically /run/user/$UID/oo7/pam.sock)

License

The project is released under the MIT license.