PAM Authentication
This page describes how to use PAM based authentication.
Overview
The pam authentication method uses the Pluggable Authentication Module (PAM) system available on some platforms. If the form of PAM authentication specified requires a username and password, the standard SOCKS version 5 username authentication method is used to supply the username and password to the Dante server. Note that the password is transmitted in clear-text with this authentication method. It should not be used over an insecure network.
Some PAM modules, but not necessarily all, support performing access control based on the IP address or hostname of the SOCKS client. This makes it possible to use PAM without the SOCKS client providing any username or password.
Dante compilation
Dante must be compiled with support for PAM in order to be able to use the PAM authentication method.
To check if a Dante binary has support for PAM, the following command can be used:
$ ./sockd -vv | grep build: | grep pam build: gssapi libwrap mon-data mon-disconnect pam preload sess2 upnp
If Dante has been compiled with PAM support, the word "pam" should be present somewhere in the above line. If nothing is output, Dante will need to be recompiled with PAM support enabled.
To compile Dante with PAM support, first run the configure script in the source archive and verify that the system PAM installation is found correctly. For the PAM support to be added to Dante, Dante has two basic requirements:
- A library called libpam must be present on the machine.
- A header file called security/pam_appl.h must be present.
On some platforms, the latter will typically only be available if a package called pam-devel or similar is installed.
When running configure, several lines of status information should be printed at the end, including a line with information about PAM. If something is missing on the system, or has not been found correctly by Dante, output similar to the following should be output:
PAM: Disabled, security/pam_appl.h missing
If all requirements are found correctly, the following should be output:
PAM: Enabled
At this point, it should be possible to compile the source code to get a sockd binary with PAM support. After compilation has completed, verify using the command described above that PAM support is actually supported by the binary.
PAM system environment setup
The PAM system on the server needs to be configured for use with Dante. This might involve adding a configuration file or line for the SOCKS server to the PAM setup. The changes depend on the operating system, but it will generally be identical to similar services, such as sshd.
The default PAM service name used by Dante is sockd, but this can be overridden in individual rules in the server configuration file by setting pamservicename to a different value. The client-rule example below shows how this is typically done. The default value can only be changed at compile time so it is necessary to specify this setting in each rule that should use a different servicename.
IMPORTANT: Care should be taken to verify that a pam configuration file corresponding to the pamservicename actually exists when this option is used, because on some platforms, such as FreeBSD, the default is for the PAM system to pass all traffic if a non-existing file is specified. It must be verified that valid requests are passed and that requests with an incorrect IP-address or user/password are blocked when PAM is used, as the decision on whether access should be granted or not involves the PAM system and is not entirely under Dante's control.
As an example, some UNIX distributions have a PAM service config files in the directory /etc/pam.d, which would make the default Dante PAM config file /etc/pam.d/sockd. For example:
%PAM-1.0 #auth required pam_sepermit.so auth include system-auth account required pam_nologin.so account include system-auth password include system-auth # pam_selinux.so close should be the first session rule session required pam_selinux.so close session required pam_loginuid.so # pam_selinux.so open should only be followed by sessions to be executed in the user context session required pam_selinux.so open env_params session optional pam_keyinit.so force revoke session include system-auth session required pam_limits.so
Note that the above file should not be copied verbatim; there are likely to be significant variations between operating systems, and even versions of any given operating system. Copying an existing file, such as the one for sshd should give a starting point that can be changed as desired.
Server privileges
#server identities (not needed on Solaris) user.privileged : root user.notprivileged : socks
The server will typically have to be started with root privileges to verify passwords via PAM. If this is the case, the user.privileged and user.notprivileged keywords should be set to ensure that the server will run as an unprivileged user when it does not need root privileges.
Syntax changes
In Dante 1.4.0, the name of the PAM authentication method was changed from simply pam, into either pam.address (for IP/hostname-only based PAM authentication, with no username/passwords exchanged) or pam.username (for username/password based PAM authentication). The old pam keyword semantics determined the correct meaning based on context, but this excluded some use-cases, and this keyword was thus deprecated.
Example clientmethod usage
PAM can in some cases be used within Dante's client-rules, where only the IP-address of the connecting client is available.
If used with a PAM authentication method that only requires the IP-address of the client connecting to Dante, it is possible to use PAM in a client-rule.
One such PAM method is pam_rhosts, which can be found on some platforms that support PAM. One limitation compared to e.g., rsh is that the the user name of the client will not be known. This applies to both the PAM USER and RUSER values, both of which the Dante server sets to rhostusr by default. This can by changed at compile-time in Dante by modifying the variables DEFAULT_PAM_USER and DEFAULT_PAM_RUSER, respectively. To use the pam_rhosts module it might be necessary to add this user to the machine the Dante server is running on in order for the pam_rhosts module to work with Dante.
Below is an example of the syntax used in Dante when one wants to use PAM from client-rules:
clientmethod: pam.address
client pass {
from: 0.0.0.0/0 to: 0.0.0.0/0
#the servicename should differ from the servicename in socks-rules
pamservicename: pam_host
}
The example above sets the pamservicename to pam_host, which is assumed to be configured in a way which makes it possible to authenticate based on the client hostname only. This value should be different from the PAM servicename used in the SOCKS rules (see below), where the username and password would also be available for deciding whether access should be granted or not.
With the above configuration, the pam_host PAM module would be used to determine whether connections should be accepted based on the IP address of the client. A PAM authentication failure would lead to the connection being closed. A PAM authentication success would cause SOCKS protocol negotiation to start, after which the corresponding socks-rules would be used to determine whether access should be granted or denied.
Example socks-rule usage
The more typical way to use PAM authentication is within socks-rules. The information provided to the PAM subsystem will then, in addition to the IP-address, also include the username and password supplied by the user.
socksmethod: pam.username
#standard client rule, accept all clients
client pass { from: 0/0 to: 0/0 }
#outgoing traffic, requiring pam.username authentication, as specified
#in the global socksmethod.
socks pass {
from: 0/0 to: 0/0
}