PageViews: 1,092 hits / 140 nets

Configuring Authenticaiton of DeleGate

Yutaka Sato

December 28, 2006

Authentication by an external command

DeleGate version 9.4.2 introduced an interface for "authentication by an external command". Although DeleGate supports the PAM standard interface for authentication, it could be not so easy to apply PAM to user's own or legacy schemes or data bases for authentication. Therefore a simple command interface for authentication can be useful to support simple implementation of user's own authentication or adaptations to existing schemes of authentication.

The following example shows how it is configured. In the example, the command for authentication is named "myauth". It is referred by DeleGate as " AUTHORIZER=-cmd{myauth}". User name and password to be authenticated can be passed in command-line arguments, environment variables, or in the standard input to the command. In the example, the user name "%U" is passed as a command-line argument while the password "%P" is passed in the environment variable "PASSWD".

A parameter to use authentication command "myauth":

AUTHORIZER="-cmd{myauth %U}{PASSWD=%P}"

The following is a simple example of an authentication program which accepts the user name "user1" with the password "pass1". The result of the authentication can be shown with the status response from the authentication program put to its standard-output, or the exit code of the program. In the example, the success of an authentication is indicated by the status response "230 " while the failure is indicated with "530 " (These are the status code of the FTP protocol).
An implementation of the "myauth" command:

#!/bin/sh if [ "$1" = "user1" -a "$PASSWD" = "pass1" ]; then echo "230 SUCCESS" else echo "530 FAILURE" fi

The "myauth" program is to be put to one of directories listed in the parameter LIBPATH or in the PATH environment variable.

The following is another example of an authentication command which gets user name and password via its standard-input. This way will be safer because it passes critical information like password through a pipe between processes which is relatively difficult to peep.

AUTHORIZER="-cmd{myauth}{}{%U\n%P\n}"

In the example, the string "\n" trailing %U and %P represents a new-line.

#!/bin/sh read USER read PASS if [ "$USER" = "user1" -a "$PASS" = "pass1" ]; then echo "230 SUCCESS" else echo "530 FAILURE" fi

Authentication by a FTP server

Using a FTP server as an authentication server is the firstly implemented scheme of authentication in early times of DeleGate. In this scheme, DeleGate uses only USER and PASS commands with the FTP server. Therefore, it is very easy to write your own authentication server of this scheme, as the following simple script to do authentication as a FTP server.

#!/bin/sh echo "220 Ready" read COM USER echo "331 Send pass" read COM PASS if [ "$USER" = "user1" -a "$PASS" = "pass1" ]; then echo "230 Ok" else echo "530 No" fi

You can invoke this script (named "ftpauth.sh" for example) from inetd, or by DeleGate as follows.

delegated -P9921 SERVER=exec XFIL=ftpauth.sh

The "ftpauth.sh" script is to be put to one of directories listed in the parameter LIBPATH.
This authentication server can be used as follows for example.

delegated -P8080 SERVER=http AUTHORIZER=localhost/9921

The above script can be used also as a local command for authentication as follows (since 9.4.2-pre6).

AUTHORIZER="-cmd{ftpauth.sh}{}{USER %U\nPASS %P\n}"

[CTX] [ALL]

---

AUTHORIZER parameter* ==  AUTHORIZER=authServList[@realmValue][:connMap]
       authServList  ==  [authForw,]authServ[,authServ]* | & | *
           authForw  ==  -map{inPat}{localPat}{fwdPat} | -strip | -fwd
           authServ  ==  authHost[/portNum][(reprUser)]
           authHost  ==  hostName | hostAddr
         realmValue  ==  word | {words separated with space}
            connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none
                    --  restriction: applicable to Telnet, FTP, NNTP, SMTP, IMAP,
                                     Socks, SockMux, and HTTP

Specify the server for authentication and authorization ("auth-server"). If specified, an access by a client is not permitted without authenticated successfully by the auth-server, sending an appropriate pair of user-name and pass-word over the application protocol. Two special authServ "-none" and "-never" are exceptions to make authentication unnecessary. If authServ is followed by "(reprUser)", the users successfully authenticated in the authServ are represented by reprUser as a representative user.

Note that even a client authorized by an auth-server is not permitted if the client's host does not pass other access controls (RELIABLE and PERMIT). To permit any authorized client regardless of its host, specify as RELIABLE="-a/*". Also RELIABLE="*" works for this purpose but is not safe on modifications of configuration and DeleGate.

Adding connMap, an auth-server can be selected conditionally on a combination of destination protocol, server host and client host. The authServList is a host name of authentication server, or a list of host names of authentication servers. If authServList is followed with "@realmValue", the value is used to define the realm of protection space in HTTP-DeleGate. It can be overridden by MountOption "realm=realmValue" for each MOUNT point.

Currently, the default protocol of remote authentication/authorization server is that of FTP protocol with USER and PASS commands. Thus any real FTP server can be used as an authentication/authorization server of DeleGate. Another way of maintaining DeleGate's own lists for authentication/authorization is using -Fauth function.

There are built-in auth-servers to be used as authServ as follows:

-none -- allow without caring if authentication is given or not

-never -- disallow without careing if authentication is given or not

-any -- any combination of username + password is acceptable

-anonftp -- username is "ftp" or "anonymous" and password includes "@"

-dgauth[.realm] -- password is sent safely as a digest (HTTP and APOP)

-pam/service -- username + password is checked by PAM

-list{user:pass,...} -- the pair of username and password is in the list

-userpass/user/pass -- equivalent to -list{user:pass}

-hostlist/ListName -- client's host is in the HOSTLIST=ListName:HostList

-fail.badpass -- disallow if the username exists but password is wrong

-fail.nopass -- disallow if password is not given or empty

-cmd{cmd arg ...}{ENV=val ...} -- external command for authentication

-ntht -- NTLM over HTTP (Win32 only)

-login -- logon to the local host (Win32 only)

-man -- manual authentication on demand

DGAuth: -dgauth[.realm][{user:pass,...}]


Authentication scheme based on digested password, specific to each application protocol, is enabled with "AUTHORIZER=-dgauth". This kind of authentication scheme, at least APOP proxy or HTTP Digest/Basic gateway does, requires the original cleartext of password. A simple way to do so is giving directly a list of pairs of username and password as -dgauth{user1:pass1,user2:pass2,...}. Another way is storing passwords by DeleGate with "-Fauth -a username:password -dgauth". Since passwords for -dgauth is stored in encrypted form, a keyword is required for the encryption. Specify the keyword as CRYPT=pass:keyword or answer it interactively afterwards. Otherwise, DGAuth can be delegated to a remote DGAuth server. DGAuth generates a session identifier which is retained identically during the session started by an authentication, then passed to CFI/CGI programs in environment variable "X_DIGEST_SESSION" and can be logged into PROTOLOG.

Example:

// a HTTP proxy or server with the Digest authentication with clients.
SERVER=http AUTHORIZER=-dgauth
// a POP proxy which uses APOP authentication with clients.
SERVER=pop MOUNT="* pop://server/*" AUTHORIZER=-dgauth


PAM: -pam[/service]


On platforms where PAM (Pluggable Authentication Modules) is available, it can be used for authentication with the syntax AUTHORIZER="-pam/service", for example as AUTHORIZER="-pam/passwd", AUTHORIZER="-pam/ftp" and so on.
Note that most of PAM authentications need to be executed under the privilege of superuser on Unix (with OWNER="root" option). But you can avoid running your DeleGate with superuser privilege by installing external program "dgpam" under DGROOT/subin/. Also PAM authentication can be delegated to a remote PAM server.

LIST: -list{user[:pass],...}


An element of the list can be user only without ":pass" which means matching user name only and don't care the password. In the "-list{user:pass,...}", substitution by "[date+format]" can be used in user and pass. For example, AUTHORIZER="-list{guest:[date+%y%m]}" means accepting usrename "guest" with password "0405" in May 2004.

Example:

AUTHORIZER="-list{u1:p1,u2:p2}(local),-pam,-none(anonymous)"
// a user may be authenticated as "local" or as some user name in PAM,
// or "anonymous" otherwise


CMD: -cmd{cmd arg ...}[{ENV=val ...}[{input-pattern}]]

Do the authentication with an external command cmd. Values to be used the authentication to be passed to the command is specified with the format as "%format" like %U for username and %P for password. A parameter can be passed in command-line argument, in environment variable or in the standard input of the command. If the environment and input-pattern is omitted as AUTHORIZER="-cmd{cmd}, the pair of user name and password is passed by default as if implicitly specified as AUTHORIZER="-cmd{cmd}{DG_USER=%U DG_PASS=%P}{USER %U\nPASS %P\n}".

The result of the authentication by the command is shown in its output string or by its exit code. The command may puts a string to its standard output to show the result in the form of a status response of the FTP protocol, that is, "230" for success and "530" for failure. Otherwise the exit code of the process is used, the value zero for success and non-zero values for failure.

Example: passing username in argument while password in environment variable

AUTHORIZER="-cmd{myauth %U}{MYPASS=%P}"

[the content of the myauth command]
#!/bin/sh
if [ "$1" = "user1" -a "$MYPASS" = "pass1" ]; then
  echo "230 SUCCESS"
else
  echo "530 FAILURE"
fi


AUTHFORW: -map{inPat}{localPat}{fwdPat} | -strip | -fwd


(available only in FTP and POP currently)
The "-map" prefix is used to split incoming authentication information of USER and PASS (in inPat pattern) into a pair of authentications, the one to be used locally by authServList (in localPat) and another to be forwarded to the server (in fwdPat). Each authentication information to be matched or generated is represented by a string of a pair of a user name and a password as "username:password". If the username string generated by fwdPat ends with a substring as "@Host" then it is striped and the Host is used as the destination server. The string is matched and generated by the pattern specification format common to the one used for pattern matching in the MOUNT parameter.
Example: -strip

1A) AUTHORIZER="-map{%S@%S:%S@%S}{%(0):%(2)}{%(1):%(3)},-list{u1:p1},-pam"


1B) AUTHORIZER="-strip,-list{u1:p1},-pam" ## equiv. to the above


incoming auth. <-- USER user1@user2@host2 + PASS pass1@pass2
local auth. by u1 or PAM <-- USER user1 + PASS pass1
outgoing to the server h2 <-- USER user2 + PASS pass2

Example: -fwd

2A) AUTHORIZER="-map{%S:%S}{%S:%S}{%S:%S},-list{u1:p1},-pam"


2B) AUTHORIZER="-fwd,-list{u1:p1},-pam" ## equiv. to the above


Example:

3A) AUTHORIZER="-map{%S}{%S}{},-list{u1:p1},-pam"


3B) AUTHORIZER="-list{u1:p1},-pam" ## equiv. to the above


As shown in the above example 1), "-strip" is used to support a nested username and password as USER "u1@u2@u3@h3@h2@h1" and PASS "p1@p2@p3". It strips the first element before '@' in the USER and PASS to be used for local authentication, strips the last element after '@' in USER as the destination server, then forwards remaining string to the destination server. "-fwd" specifies to use the same USER and PASS both for the local authentication and the authentication with a server.

If only authentication of user is necessary without authorization, the following special name will be useful as a authServList.

"&" -- the client host (user name on the client host is required)
"*" -- any authHost specified by the client as "user@authHost"

Example:

// clients from outside of local.domain is required authentication
SERVER=telnet AUTHORIZER="&:::!*.local.domain"
// any clients is allowed if the user is authenticated with localhost
SERVER=telnet AUTHORIZER="localhost" RELIABLE="*"
// using DeleGate's own list of "-socksusers" maintained with "-Fauth"
SERVER=socks AUTHORIZER=-socks.users

---