man/man5/rlm_pap.5

   1 .TH rlm_pap 5 "3 February 2004" "" "FreeRADIUS Module"
   2 .SH NAME
   3 rlm_pap \- FreeRADIUS Module
   4 .SH DESCRIPTION
   5 The \fIrlm_pap\fP module performs PAP authentication.
   6 .PP
   7 This module performs authentication when the Access-Request contains a
   8 User-Password attribute AND when a "known good" password has been
   9 configured for the user.  In addition, it takes care of decoding the
  10 "known good" password from hex or Base64 encoding to a form it can use
  11 for authentication.
  12 .PP
  13 As a result, as of 1.1.4, the "encryption_scheme" configuration item
  14 SHOULD NOT BE USED, and the rlm_ldap configuration
  15 item "password_header" SHOULD NOT BE USED.  Those items will continue to work
  16 in 1.1.4, and existing systems will work un-changed after upgrading to
  17 1.1.4.  We recommend, though, that sites using multiple instances of
  18 rlm_pap see if they can replace those multiple instances with one instance,
  19 using the new "auto_header" configuration, and remove the "password_header"
  20 configuration from rlm_ldap.
  21 .PP
  22 The configuration item(s):
  23 .IP auto_header
  24 Automatically discover password headers.  Permitted values are "yes"
  25 and "no".  For backwards compatibility, the default is "no".
  26 .IP
  27 The recommended value is "yes".
  28 .IP encryption_scheme
  29 No longer used, and therefore no longer documented.
  30 .PP
  31 When "auto_header" is set to "yes", the module will look in the
  32 configuration list for the User-Password attribute or the new
  33 Password-With-Header attribute.  If found, it will then look at the
  34 string value of those attributes, for one of the following headers:
  35 .PP
  36 .DS
  37 .br
  38         {clear}
  39 .br
  40         {cleartext}
  41 .br
  42         {crypt}
  43 .br
  44         {md5}
  45 .br
  46         {smd5}
  47 .br
  48         {sha1}
  49 .br
  50         {ssha1}
  51 .br
  52         {nt}
  53 .br
  54         {x-nthash}
  55 .br
  56         {ns-mta-md5}
  57 .DE
  58 .PP
  59 The text following the header is taken as the "known good" password,
  60 either cleartext, crypted, hashed, or hashed with a salt.  If the text
  61 is hex or Base64 encoded, it will be decoded to obtain the correct
  62 form of the "known good" password.  The User-Password in the
  63 Access-Request will then be crypted, or hashed as appropriate, and
  64 compared to the "known good" password.  If they match, the user is
  65 authenticated, otherwise the module returns reject.
  66 .SH CAVEATS
  67 In order for the "auto_header = yes" functionality to work, the
  68 \fIpap\fP module MUST be listed LAST in the \fIauthorize\fP section of
  69 \fIradiusd.conf\fP.  This lets other modules such as LDAP blindly add
  70 a "known good" password to the configuration items, and the PAP module
  71 will just figure it out.  In most cases, multiple instances of the PAP
  72 module, along with complex logic to determine which one to call when,
  73 can be replaced with one instance of the module, with it listed last
  74 in the \fIauthorize\fP section.
  75 .PP
  76 Note that the \fIns_mta_md5\fP module is no longer necessary, and can
  77 be removed.
  78 .PP
  79 Also, setting "Auth-Type = Local" or "Auth-Type = Crypt-Local" is no
  80 longer necessary.  Any such settings SHOULD BE DELETED.  Simply list
  81 \fIpap\fP LAST in the \fIauthorize\fP section, and the module will
  82 take care of figuring out what to do.  (Have we emphasized that enough?)
  83 .PP
  84 Another reason to list the module last is that it will take care of
  85 normalizing any crypt'd or hashed password retrieved from a database.
  86 So it is now safe to have clear-text passwords as "{clear}...",
  87 because the PAP module will take care of removing the "{clear}" prefix
  88 from the password.  Any other modules that need access to the
  89 cleartext password will
  90 .PP
  91 The module uses a number of new attributes.
  92 .IP Password-With-Header
  93 This attribute should contain a "known good" password, with a header
  94 such as "{crypt}, or "{md5}", etc.  It should be used when the
  95 passwords retrieved from a DB may have different headers.  When
  96 \fIpap\fP is listed in the \fIauthorize\fP section, the module will
  97 examine this attribute, and use it to create one of the other
  98 attributes listed below.  That other attribute is then used for
  99 authentication.
 100 .IP
 101 If the passwords in a DB do not have a header, and are always in one
 102 particular form, then the attributes listed below can be used
 103 directly.  In that case, the PAP module will do hex or Base64 decoding
 104 of the attribute contents, if necessary.  So \fIpap\fP should still be
 105 listed in the \fIauthorize\fP section, because it will enable the
 106 maximum flexibility for the server, and minimize configuration for the
 107 administrator.
 108 .IP Cleartext-Password
 109 This attribute should contain the cleartext for a "known good"
 110 password.  Previously, the User-Password attribute was overloaded to
 111 contain this, both in the FAQ and in databases in many sites.  Any
 112 configuration that sets a cleartext form of the password using
 113 User-Password SHOULD UPDATE to using Cleartext-Password.  Doing so
 114 will simplify a number of debugging issues.
 115 .IP Crypt-Password
 116 This attribute has been around for a while, but is documented here for
 117 completeness.  It contains the crypt'd form of the password.
 118 .IP MD5-Password
 119 This attribute contains the MD5 hashed form of the password.
 120 .IP SMD5-Password
 121 This attribute contains the MD5 hashed form of the password, with a salt.
 122 .IP SHA1-Password
 123 This attribute contains the SHA1 hashed form of the password.
 124 .IP SSHA1-Password
 125 This attribute contains the SHA1 hashed form of the password, with a salt.
 126 .IP NT-Password
 127 This attribute has been around for a while, but is documented here for
 128 completeness.  It contains the NT hash form of the password, as used
 129 by Active Directory and Samba.
 130 .SH SECTIONS
 131 .BR authorize
 132 .BR authenticate
 133 .PP
 134 .SH FILES
 135 .I /etc/raddb/radiusd.conf
 136 .PP
 137 .SH "SEE ALSO"
 138 .BR radiusd (8),
 139 .BR radiusd.conf (5)
 140 .SH AUTHOR
 141 Alan DeKok <aland@freeradius.org>