12.2 HTTP Basic Authentication

Basic authentication is the simplest and least secure that HTTP has to offer. It essentially transmits user passwords as cleartext, although they are encoded into printable characters . For example, if the user types her name as Fannie and her password as FuRpAnTsClUb , the user-agent first combines the two into a single string, with name and password separated by a colon :

 Fannie:FuRpAnTsClUb 

Then it encodes this string with base64 encoding, as defined in RFC 2045. It looks like this in the HTTP headers:

 Authorization: Basic RmFubmllOkZ1UnBBblRzQ2xVYgo= 

Anyone who happens to capture your users' HTTP requests can easily get both the username and password:

 % echo RmFubmllOkZ1UnBBblRzQ2xVYgo=  /usr/local/lib/python1.5/base64.py -d Fannie:FuRpAnTsClUb 

As required by the HTTP/1.1 RFC, Squid doesn't forward "consumed" authorization credentials to other servers. In other words, if the credentials are for access to Squid, the Authorization header is removed from outgoing requests. ^[1]

^[1] Unless you configure a peer with the login=PASS option.

You'll notice that some of the Basic authenticators can be configured to check the system password file. Because Basic credentials aren't encrypted, it is a bad idea to combine login passwords with cache access passwords. If you choose to use the getpwnam authenticator, make sure you fully understand the implications of having your users' passwords transmitted in the clear across your network.

HTTP Basic authentication supports the following auth_param parameters:

• auth_param basic program command

• auth_param basic children number

• auth_param basic realm string

• auth_param basic credentialsttl time-specification

The program parameter specifies the command, including arguments, for the helper program. In most cases, this will be the pathname to one of the authentication helper programs that you compiled. By default, they live in /usr/local/squid/libexec .

The children parameter tells Squid how many helper processes to use. The default value is 5, which is a good starting point if you don't know how many Squid needs to handle the load. If you specify too few, Squid warns you with messages in cache.log .

The realm parameter is the authentication realm string that the user-agent should present to the user when prompting for a username and password. You can use something simple, such as "access to the Squid caching proxy."

The credentialsttl parameter specifies the amount of time that Squid internally caches authentication results. A larger value reduces the load on the external authenticator processes, but increases the amount of time until Squid detects changes to the authentication database. Note, this only affects positive results (i.e., successful validations). Negative results aren't cached inside Squid. The default TTL value is two hours.

Here is a complete example:

 auth_param basic program /usr/local/squid/libexec/pam_auth auth_param basic children 10 auth_param basic realm My Awesome Squid Cache auth_param basic credentialsttl 1 hour acl KnownUsers proxy_auth REQUIRED http_access allow KnownUsers 

Next I will discuss the Basic authentication helper programs that come with Squid.

12.2.1 NCSA

./configure ”enable-basic-auth-helpers=NCSA

The NCSA authentication helper is relatively popular due to its simplicity and history. It stores usernames and passwords in a single text file, similar to the Unix /etc/passwd file. This password file format was originally developed as a part of the NCSA HTTP server project.

You pass the path to the password file as the program's single command-line argument in squid.conf :

 auth_param basic program /usr/local/squid/libexec/ncsa_auth     /usr/local/squid/etc/passwd 

You can use the htpasswd program that comes with Apache to create and update the password file. Also, you can download it from http://www.squid-cache.org/htpasswd/. From that page, you can also download the chpasswd CGI script, which allows users to change their own passwords if necessary.

12.2.2 LDAP

./configure ”enable-basic-auth-helpers=LDAP

The LDAP helper interfaces to a Lightweight Directory Access Protocol server. The OpenLDAP libraries and header files must be installed before you can compile the squid_ldap_auth helper. You can find OpenLDAP at http://www.openldap.org/.

The squid_ldap_auth program requires at least two arguments: the base distinguished name (DN) and the LDAP server hostname. For example:

 auth_param basic program /usr/local/squid/libexec/squid_ldap_auth    -b "ou=people,dc=example,dc=com"  ldap.example.com 

The LDAP helper has a Unix manual page that describes all of its options and parameters. However, Squid's manual pages aren't normally installed when you run make install . You can read the manual page by locating it in the source tree and manually running nroff . For example:

 % cd helpers/basic_auth/LDAP % nroff -man squid_ldap_auth.8  less 

12.2.3 MSNT

./configure ”enable-basic-auth-helpers=MSNT

The MSNT authenticator interfaces to a Microsoft NT domain database via the Server Message Block (SMB) protocol. It uses a small configuration file, named msntauth.conf , which must be placed in the $prefix/etc or ”sysconfidr directory. You can specify up to five NT domain controllers in the configuration file. For example:

 server pdc1_host bdc1_host my_nt_domain server pdc2_host bdc2_host another_nt_domain 

By default, the MSNT authenticator allows any user validated by the server. However, it also has the ability to allow or deny specific usernames. If you create an allowusers file, only the users listed there are allowed access to Squid. You might want to use this feature if you have a large number of users on the NT server, but only a small number who are allowed to use the cache. Alternatively, you can create a denyusers file. Any user listed in that file is automatically denied access, even before checking the allowusers file.

Alternatively, you can allow or deny specific usernames by placing them in the proxy_auth ACL as described in Section 6.1.2.12.

For additional documentation, see the README.html file in the helpers/basic_auth/MSNT directory.

12.2.4 Multi-domain-NTLM

./configure ”enable-basic-auth-helpers=multi-domain-NTLM

The multi-domain-NTLM authenticator is similar to MSNT. Both send queries to a Windows NT domain database. Whereas MSNT queries up to five domain controllers, the multi-domain-NTLM authenticator requires users to insert the NT domain name before their username, like this:

   ntdomain   \   username   

The multi-domain-NTLM helper program is a relatively short Perl script. It relies on the Authen::SMB package from CPAN (http://www.cpan.org). If you don't hardcode the domain controller hostnames in the Perl script, it utilizes the nmblookup program from the Samba package (www.samba.org) to discover them automatically.

The Perl script is named smb_auth.pl . It might look like this in squid.conf :

 auth_param basic program /usr/local/squid/libexec/smb_auth.pl 

Documentation for multi-domain-NTLM is thin, but if you understand Perl, you should be able to figure it out by reading the code.

12.2.5 PAM

./configure ”enable-basic-auth-helpers=PAM

In a sense, Pluggable Authentication Modules (PAM) are the glue between authentication methods (e.g., one-time passwords, kerberos, smart cards) and applications requiring authentication services (e.g., ssh , ftp , imap ). Your system's /etc/pam.conf file describes which methods to use for each application.

To use Squid's PAM authentication helper, you need to add "squid" as a service in the /etc/pam.conf file and specify which PAM modules to use. For example, to use the Unix password file on FreeBSD, you might put this in pam.conf :

 squid  auth  required  pam_unix.so  try_first_pass 

To check the Unix password database, the pam_auth process must run as root. This is a security risk and you must manually make the executable setuid root. If pam_auth doesn't run as root, and it is configured to check the Unix password database, every request for authentication fails.

The PAM authenticator is documented with a manual page that you can find in the helpers/basic_auth/PAM directory.

12.2.6 SASL

./configure ”enable-basic-auth-helpers=SASL

The Simple Authentication and Security Layer (SASL) is an IETF proposed standard, documented in RFC 2222. It is a protocol for negotiating security parameters for connection-based protocols (e.g., FTP, SMTP, HTTP). However, the SASL authenticator is similar to the PAM authenticator. It interfaces with a third-party library to query a number of different authentication databases.

Specifically, Squid's SASL authenticator requires the Cyrus SASL library developed by Carnegie Mellon University. You can find it at http://asg.web.cmu.edu/sasl/.

You can configure the SASL authenticator to check the traditional password file, the PAM system, or any of the other databases supported by CMU's library. For further information, see the README file in the helpers/basic_auth/SASL directory.

12.2.7 SMB

./configure ”enable-basic-auth-helpers=SMB

SMB is another authenticator for Microsoft Windows databases. The authenticator itself is a C program. That program executes a shell script each time it talks to the Windows domain controller. The shell script contains commands from the Samba package. Thus, you'll need to install Samba before using the SMB authenticator.

The SMB authenticator program, smb_auth takes the Windows domain name as an argument. For example:

 auth_param basic program /usr/local/squid/libexec/smb_auth -W MYNTDOMAIN 

You can list multiple domains by repeating the -W option. For full documentation, see http://www.hacom.nl/~richard/software/smb_auth.html.

12.2.8 YP

./configure ”enable-basic-auth-helpers=YP

The YP authenticator checks a system's "Yellow Pages" (a.k.a. NIS) directory. To use it with Squid, you need to provide the NIS domain name and the name of the password database, usually passwd.byname on the authenticator command line:

 auth_param basic program /usr/local/squid/libexec/yp_auth my.nis.domain passwd.byname 

The yp_auth program is relatively simple, but doesn't have any documentation.

12.2.9 getpwnam

./configure ”enable-basic-auth-helpers=getpwnam

This authenticator is simply an interface to the getpwnam( ) function found in the C library on Unix systems. The getpwnam( ) function looks in the system password file for a given username. If you use YP/NIS, getpwnam( ) checks those databases as well. On some operating systems, it may also utilize the PAM system. You can use this authenticator if your cache users have login accounts on the system where Squid is running. Alternatively, you could set up " nologin " accounts in the password file for your cache users.

12.2.10 winbind

./configure ”enable-basic-auth-helpers=winbind

Winbind is a feature of the Samba suite of software. It allows Unix systems to utilize Windows NT user account information. The winbind authenticator is a client for the Samba winbindd daemon. You must have Samba installed and the winbindd daemon running before you can use this authenticator.

The name of the winbind Basic authenticator is wb_basic_auth . It typically looks like this in squid.conf :

 auth_param basic program /usr/local/squid/libexec/wb_basic_auth 

12.2.11 The Basic Auth API

The interface between Squid and a Basic authenticator is quite simple. Squid sends usernames and passwords to the authenticator process, separated by a space and terminated by a newline. The authenticator reads the username and password pairs on stdin . After checking the credentials, the authenticator writes either OK or ERR to stdout .

Any "URL-unsafe" characters are encoded according to the RFC 1738 rules. Thus, the name "jack+jill" becomes "jack%2bjill". Squid accepts usernames and passwords that contain whitespace characters. For example "a password" becomes "a%20password". The authenticator program should be prepared to handle whitespace and other special characters after decoding the name and password.

You can easily test a Basic authenticator on the command line. Simply run the authenticator program in a terminal window and enter usernames and passwords. Or, you can do it like this:

 % echo "bueller pencil"  ./ncsa_auth /tmp/passwd OK 

Here is a simple template authenticator written in Perl:

 #!/usr/bin/perl -wl use URI::Escape; $=1;                   # don't buffer stdout while (<>) {     ($u,$p) = split;     $u = uri_unescape($u);     $p = uri_unescape($p);     if (&valid($u,$p)) {         print "OK";     } else {         print "ERR";     } } sub valid {     my $user = shift;     my $pass = shift;     ... }