pam_rsa PAM-module

VM Kari

Mar 30 2006

Version 0.8-4

pam_rsa - pam_rsa PAM-module

Table of Contents

Synopsis

/etc/security/pam_rsa.conf

Description

The pam_rsa PAM-module is for local PAM-authentication with RSA keypairs. It cannot be used for authenticating to PAM-services on remote hosts. This manual page describes both the module and its configuration file.

The basic idea is that RSA private keys are stored on removable and easily portable medias like USB memory sticks. It is recommended that the private keys are protected with a passphrase. The corresponding public keys are stored on the hosts that users wish to authenticate to.

As a prerequisite, the target hosts should be set up in a such a way that their operating system will automatically detect a USB memory stick when it is inserted into host's USB port.

However, it is not sufficient that the OS just detects the device. The pam_rsa module must have access to the file system in order to read the RSA private keys, so the storage medias must be automatically mounted too. One way to arrange automatic mounting and unmounting is to use automounter. See automount(8), autofs(5), autofs(8), auto.master(5).

The module reads its configuration from file /etc/security/pam_rsa.conf. Because the file contains very important authentication settings, it is imperative that the ownership and permissions are properly set so that nobody except trusted administrators can modify or remove the file. Similar care must be taken to ensure that both the public and private keys are stored safely.

Let's take one example to illustrate the pam_rsa authentication process. Assume that a user foo tries to authenticate to a host called bar.example.com. First, pam_rsa searches foo's public key from an X509 PEM-file pubkey_dir/foo.pem. If the file is not found, or does not contain an RSA public key suitable for encryption, then the authentication fails immediately.

Otherwise, pam_rsa encrypts a certain message with foo's public key. Next pam_rsa determines the hostname of the machine it runs on, and creates a shortened SHA1 hashed string from the name. Continuing with our example host bar.example.com, the hashed hostname is equivalent to the output of running this shell command:

echo -n bar.example.com | sha1sum | cut -b -8

Now pam_rsa forms pathname privkey_dir/ec9f855e/ and if the value of configuration option privkey_name_hash is sha1 (which is its default), it performs a similar SHA1 hashing of the username:

echo -n foo | sha1sum | cut -b -8

So if foo tries to access host bar.example.com, the pam_rsa module running on bar.example.com will search foo's private key from file:

privkey_dir/ec9f855e/0beec7b5.pem

or if privkey_name_hash is set to none, pam_rsa will try this location:

privkey_dir/ec9f855e/foo.pem

If the RSA private key cannot be found, authentication fails. Otherwise if foo's private key successfully decrypts the message that pam_rsa has previously encrypted, then foo's pam_rsa authentication succeeds.

Otherwise the pam_rsa authentication fails.

Note that even though hashing of the private key's filename can be turned off with a configuration option privkey_name_hash, the hostname is always hashed.

This example demonstrated that it is necessary to name directories and PEM-files exactly as the module expects. If the naming is wrong, pam_rsa authentication will not work.

The pamrsakp(8) utility script can be used to generate keypairs for the pam_rsa module.

Configuration file syntax

The configuration file syntax is very simple. Options are defined one per line. Each option is followed by whitespace and a value, in the following fashion:

option[whitespace]value

[whitespace] is defined as at least one space or horizontal tab character

Lines may begin with whitespace. Lines may end with whitespace.

Lines must have less than 1024 characters.

The comment character '#' begins a comment that extends to the end of the line. Comments are allowed on the same lines as option settings provided that comment elimination leaves a syntactically valid line.

Valid options, values, default values and their meanings are explained below.

Configuration file semantics

If the configuration file does not set an option, then a default value is used. Setting no options is acceptable, but the file /etc/security/pam_rsa.conf must exist and be readable.

Each option may be set at most once in the configuration file. Redefining options causes the module to fail.

Unless noted otherwise, all options and values are case sensitive.

Arguments

Arguments may be passed to the module from service spefific PAM-configuration files.

No arguments are required. Specifying the same argument more than once is allowed, but causes a warning to be logged.

Examples

For example, /etc/pam.d/login could be general PAM configuration file for service login (console login). The authentication section could look like the following. It defines three requirements for successful login authentication:

auth required pam_securetty.so
auth required pam_stack.so service=system-auth
auth required pam_nologin.so

If it is required that pam_rsa authentication must also succeed, an obvious modification to the existing configuration is to simply add a line:

auth required pam_securetty.so
auth required pam_rsa.so debug
auth required pam_stack.so service=system-auth
auth required pam_nologin.so

Here is another example. This configuration still requires secure ttys just like the previous example, but does no longer care about /etc/nologin files. It is now sufficient that either of pam_rsa or system's default authentication succeeds:

auth required pam_securetty.so
auth sufficient pam_rsa.so debug
auth sufficient pam_stack.so service=system-auth

That means login service does not require a password.

The debug argument can be helpful when diagnosing problems, but should not be used once things are correctly set up and working smoothly.

Files

/lib/security/pam_rsa.so
pam_rsa PAM module
/etc/security/pam_rsa.conf
configuration file for pam_rsa PAM module
/etc/pam.d/
directory for system-wide general PAM service settings
/etc/pam.conf
system-wide general PAM service settings (older alternative to /etc/pam.d/*)

See also

pamrsakp(8), pam(8), automount(8), autofs(5), autofs(8), auto.master(5).

License and Copyright

Copyright
© 2006 Vesa-Matti Kari

License
LGPL

Author

Vesa-Matti Kari
email: pamrsa-bugs@laamanaama.helsinki.fi