---
name: "pam_rsa"
section: "8"
platform: "linux"
package: "libpam-rsa"
version: "0.8-9-2.1"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/pam_rsa"
---

# pam\_rsa(8)

pam\_rsa PAM-module

## 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)](/automount/8.md), [*autofs*(5)](/autofs/5.md), [*autofs*(8)](/autofs/8.md), [*auto.master*(5)](/auto.master/5.md).

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)](/pamrsakp/8.md) 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)](/syslog/3.md) 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)](/pamrsakp/8.md), [*pam*(8)](/pam/8.md), [*automount*(8)](/automount/8.md), [*autofs*(5)](/autofs/5.md), [*autofs*(8)](/autofs/8.md), [*auto.master*(5)](/auto.master/5.md).

## LICENSE AND COPYRIGHT

- Copyright

  (C)2006 Vesa-Matti Kari

- License

  LGPL

## AUTHOR

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