Man Linux: Main Page and Category List


       pam_rsa - pam_rsa PAM-module




       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

       Let’s  take  one  example  to  illustrate  the  pam_rsa  authentication
       process.  Assume that a user foo tries to authenticate to a host called  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, the hashed hostname is equivalent  to
       the output of running this shell command:

       echo -n | 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, the pam_rsa module
       running on will search foo’s private key from file:


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


       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

       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:


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

       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


       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

       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.


       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

       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.

       *      DEBUGGING

       The debug argument enables  logging  debug  information.  This  can  be
       useful  when  problems  are  encountered.  Default  is to not log debug


       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
       auth     required service=system-auth
       auth     required

       *      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  (,  or  it  could  require
              something else  like  LDAP-authentication  (,  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

       auth     required
       auth     required debug
       auth     required service=system-auth
       auth     required

       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
       auth     sufficient debug
       auth     sufficient 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.


               pam_rsa PAM module

               configuration file for pam_rsa PAM module

               directory for system-wide general PAM service settings

               system-wide general PAM service settings (older alternative  to


       pamrsakp(8),     pam(8),     automount(8),     autofs(5),    autofs(8),


              (C)2006 Vesa-Matti Kari



       Vesa-Matti Kari