One Hat Cyber Team

Edit File: mod_auth_file.html

<!DOCTYPE html>
<html>
<head>
<title>ProFTPD module mod_auth_file</title>
</head>

<hr>
<center>
<h2>ProFTPD module <code>mod_auth_file</code></h2>
</center>
<hr>

This module is contained in the <code>mod_auth_file.c</code> file for
ProFTPD 1.3.x, and is compiled by default.

<h2>Directives</h2>
<ul>
 <li><a href="#AuthGroupFile">AuthGroupFile</a>
 <li><a href="#AuthUserFile">AuthUserFile</a>
</ul>

<hr>
<h3><a name="AuthGroupFile">AuthGroupFile</a></h3>
Syntax: AuthGroupFile path [id min-max] [name regex] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_file 
Compatibility: 1.2.7rc2

The <code>AuthGroupFile</code> directive configures an alternate group file for
providing group membership information; the specified file must have the same
format as the system <code>/etc/group</code> file, and if specified is used
during authentication and group lookups for directory/access control
operations. The path argument should be the full path to the specified
file. This directive can be configured on a per-server basis, so that virtual
FTP servers can each have their own authentication file, often in conjunction
with an <a href="#AuthUserFile"><code>AuthUserFile</code></a>.

Note that this file does not need to reside inside a
<code>chroot()</code>ed directory structure for anonymous or
<code>DefaultRoot</code> logins, as it is held open for the duration of a
session.

The optional parameters are used to set restrictions on the contents of
the specified file. The id restriction is used to specify a range
of GIDs that may appear in the file; when doing a lookup, if a group entry
has a GID that is less than the minimum or greater than the maximum is
encountered, that entry is ignored. The name restriction is used
to specify a regular expression that is applied to the name of a group
entry. If the group name does not match the regular expression, the group
entry is ignored. A leading <code>!</code> in the regular expression can
be used to negate the given expression.

Example:
<pre>
 # This makes an AuthGroupFile that can only have GIDs 2000 to 4000, and
 # whose groups must start with 'cust'
 AuthGroupFile /etc/ftpd/group id 2000-4000 name ^cust
</pre>

Note: In order to prevent other users from modifying the
<code>AuthGroupFile</code>, the <code>mod_auth_file</code> module
requires that the permissions on the file not be world-readable
or world-writable, and that the directory containing the
file not be world-writable. In addition, if the file is not a file
(e.g. the path points to a symlink, or a FIFO, etc), a warning
will be logged on server startup/restart.

<hr>
<h3><a name="AuthUserFile">AuthUserFile</a></h3>
Syntax: AuthUserFile path [id min-max] [home regex] [name regex] 
Default: None 
Context: server config, <code>&lt;VirtualHost&gt;</code>, <code>&lt;Global&gt;</code> 
Module: mod_auth_file 
Compatibility: 1.2.7rc2

The <code>AuthUserFile</code> directive configures an alternate passwd file for
providing user account information; the specified file must have the same
format as the system <code>/etc/passwd</code> file, and if specified is used
during authentication and user lookups for directory/access control operations.
The path argument should be the full path to the specified file. This
directive can be configured on a per-server basis, so that virtual FTP servers
can each have their own authentication file, often in conjunction with an
<a href="#AuthGroupFile"><code>AuthGroupFile</code></a>.

The optional parameters are used to set restrictions on the contents of
the specified file. The id restriction is used to specify a range
of UIDs that may appear in the file; when doing a lookup, if a user entry
has a UID that is less than the minimum or greater than the maximum is
encountered, that entry is ignored. The home restriction is used
to specify a regular expression that is applied to the home directory of a user
entry. If the home does not match the regular expression, the user entry
is ignored. The name restriction is used to specify a regular
expression that is applied to the name of a user entry. If the user name does
not match the regular expression, the user entry is ignored. A leading
<code>!</code> in these regular expressions can be used to negate the given
expression.

Example:
<pre>
 # This makes an AuthUserFile whose user names must start with 'ftp', and
 # whose homes cannot start with /home.
 AuthUserFile /etc/ftpd/passwd name ^ftp home !^/home
</pre>

Note: In order to prevent other users from modifying the
<code>AuthUserFile</code>, the <code>mod_auth_file</code> module
requires that the permissions on the file not be world-readable
or world-writable, and that the directory containing the
file not be world-writable. In addition, if the file is not a file
(e.g. the path points to a symlink, or a FIFO, etc), a warning
will be logged on server startup/restart.

<hr>
<h2><a name="Installation">Installation</a></h2>
The <code>mod_auth_file</code> module is compiled by default.

Logging 
The <code>mod_auth_file</code> module supports <a href="../howto/Tracing.html">trace logging</a>, via the module-specific log channels:
<ul>
 <li>auth.file
</ul>
Thus for trace logging, to aid in debugging, you would use the following in
your <code>proftpd.conf</code>:
<pre>
 TraceLog /path/to/ftpd/trace.log
 Trace auth.file:20
</pre>
This trace logging can generate large files; it is intended for debugging use
only, and should be removed from any production configuration.

<a name="FAQ">
Frequently Asked Questions

<a name="Password8Characters">
Question: I found that only the first 8 characters of
passwords are used! This is a security bug! 
Answer: No, it is not.

The default Unix password hashing scheme uses the <a href="http://en.wikipedia.org/wiki/Data_Encryption_Standard">Data Encryption Standard</a> (DES) algorithm.
As per the <code>crypt(3)</code> man page, only the first 8 characters
of the password are used. Thus this 8 character limitation comes from
the underlying system authentication, not from proftpd. The whole
purpose of the PAM system was to enable replacing the use of DES with other
authentication algorithms, which do not have this 8 character limitation.

Later, other <code>crypt(3)</code> implementations were made which can also
support algorithms such as MD5, or Blowfish. Some platforms support these
enhanced versions of <code>crypt(3)</code>, some do not. The
<a href="../utils/ftpasswd.html"><code>ftpasswd</code></a> script can generate
<code>AuthUserFiles</code> which use the MD5 algorithm instead of DES.

<a name="AuthFilePermissions">
Question: Why does <code>mod_auth_file</code> refuse
to use an <code>AuthUserFile</code> (or <code>AuthGroupFile</code>) that is
world-readable/writable? I see messages like the following logged:
<pre>
 mod_auth_file/1.0: unable to use world-readable AuthUserFile '/etc/proftpd/ftpd.passwd'
</pre>
or:
<pre>
 mod_auth_file/1.0: unable to use world-writable AuthUserFile '/etc/proftpd/ftpd.passwd'
</pre>
 
Answer: If an <code>AuthUserFile</code> or
<code>AuthGroupFile</code> is world-writable, then any user on the system
can edit that file. They can create new users, or change the entries
for existing users such that those users have different privileges, perhaps
even root privileges. In short, having <code>AuthUserFile</code> or
<code>AuthGroupFile</code> with world-writable permissions is an unsafe
configuration, and now <code>mod_auth_file</code> prevents this.

If the <code>AuthUserFile</code> is world-readable, then any user on the
system can read that file, including the hashed password. This can allow
for offline dictionary/cracking attempts against those hashes. This is also an
unsafe configuration, and thus <code>mod_auth_file</code> does not allow
world-readable <code>AuthUserFiles</code>.

Similarly, <code>mod_auth_file</code> will refuse to use an
<code>AuthUserFile</code> or <code>AuthGroupFile</code> if that file lives
in a directory, and that directory has world-writable permissions (even if
the configured file itself is not world-writable). A world-writable
directory would allow any system user to delete the <code>AuthUserFile</code>, and add their own, or to add a symlink, etc. It is another
unsafe configuration against which <code>mod_auth_file</code> now guards.

</body>
</html>