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.
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.
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.
pubkey_dir [value] (default: /etc/pamrsa)
specifies the directory that contains the RSA public keys. The value must be an absolute path starting with a '/'. A trailing '/' is allowed but not required.
Note that the public keys are actually contained within X509 PEM-format certificates. The certificate PEM-file for user foo must be called foo.pem so that pam_rsa can find the correct public key from pubkey_dir. Each public PEM-file must contain exactly one certificate.
Like the configuration file itself, the pubkey_dir or its contents must not be modifiable by others than trusted administrators. If a malicious user manages to modify an existing public key or to add a new one, then depending on the configuration, he might gain unauthorized access using a corresponding private key.
privkey_dir [value] (default: /autofs/usb/private)
specifies the base directory for finding the RSA private keys. The value must be an absolute path starting with a '/'. A trailing '/' is allowed but not required.
Each private PEM-file must contain exactly one RSA private key.
Note that unlike pubkey_dir, this directory does not contain any keys. Rather it functions as a base directory for the hostname related subdirectories and for the private keys that are contained in those subdirectories. See Description section for a complete explanation of the role of privkey_dir option.
You must make sure nobody gets access to your private keys.
privkey_name_hash [value] (default: sha1)
specifies whether the private key's filename should be SHA1 hashed or not. The value must be either sha1 or none. This value is case insensitive.
To fully understand the meaning of the privkey_name_hash option, please see Description section and option privkey_dir.
pam_prompt [value] (default: password:)
specifies the prompt that could be presented to a PAM-aware application that calls pam_rsa. The value must be less than 128 characters.
Note that if ask_pass or ask_passphrase argument is not passed to pam_rsa module (from a service specific configuration in the general PAM-framework), then the value of pam_prompt is ignored, since the default is to not ask for passwords or passphrases.
Applications can also choose to ignore prompts set by PAM-modules and use their own prompts instead.
Note also that in any case, even if ask_pass argument is passed to pam_rsa, the module will simply store the password in the PAM-framework's memory for possible later use by other PAM-modules. In other words, pam_rsa itself does not do password authentication, but see also the explanation for module argument ask_passphrase.
log_auth_result [value] (default: true)
specifies whether pam_rsa authentication results should be logged even in cases when the result is success. Authentication failures are always logged regardless of the value of this option.
The value should be one of [true, yes, on] to set the option on, or one of [false, no, off] to set the option off. This value is case insensitive.
If the system headers define LOG_AUTHPRIV facility for syslog(3) at compile time, then pam_rsa will use that facility for its logging purposes. Otherwise it will fall back to the obsolete LOG_AUTH.
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.
The debug argument enables logging debug information. This can be useful when problems are encountered. Default is to not log debug information.
The ask_pass argument causes the module to ask for a password. Even if this argument is given, the module does not do any password validation, but only stores the password in case later PAM modules want to use it.
Default is to not ask for a password.
Note that ask_pass and ask_passphrase are mutually exclusive.
See also the related configuration option pam_prompt.
The ask_passphrase argument causes the module to ask for a passphrase. Note that this is different from ask_pass. First, the passphrase will not be saved for other PAM modules. Second (unlike the password), the passphrase is actually used by pam_rsa. Its purpose is to decrypt passphrase-encrypted PEM-format RSA private keys.
If ask_passphrase argument is given, user will always be prompted for passphrase, but if the RSA private key is not encrypted, the passphrase will be ignored.
Default is to not ask for a passphrase.
Note that ask_passphrase and ask_pass are mutually exclusive.
See also the related configuration option pam_prompt.
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.
Vesa-Matti Kari
email: pamrsa-bugs@laamanaama.helsinki.fi