NAME
pam_rsa - pam_rsa PAM-module
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.
* PUBLIC KEY DIRECTORY
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.
* PRIVATE KEY DIRECTORY
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.
* PRIVATE KEY’S FILENAME HASHING
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
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.
* LOGGING AUTHENTICATION RESULT
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
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.
* DEBUGGING
The debug argument enables logging debug information. This can be
useful when problems are encountered. Default is to not log debug
information.
* ASKING FOR A PASSWORD
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.
* ASKING FOR A PASSHPRASE
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.
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
* The first requirement is that a successful login authentication
must use a console that is considered trusted (i.e. it is listed
in /etc/securetty).
* Second, the system authentication must succeed. Success or
failure is determined by /etc/pam.d/system-auth, which could in
turn require something like the commonly used /etc/shadow
password authentication (pam_unix.so), or it could require
something else like LDAP-authentication (pam_ldap.so), or a
complex combination of almost anything one can think of.
* The third requirement is that logins are not currently denied by
the existence of /etc/nologin file.
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
(C)2006 Vesa-Matti Kari
License
LGPL
AUTHOR
Vesa-Matti Kari
email: pamrsa-bugs@laamanaama.helsinki.fi