AUTHSRV(8)

NAME
authsrv - network user authentication daemon for third-party systems

SYNOPSIS
authsrv [-daemon] [-s]

DESCRIPTION
The Firewall Toolkit user authentication daemon (authsrv) acts as a piece of "middleware" to provide a unified interface for several strong authentication systems and the firewall.

The Firewall Toolkit user authentication management system allows you to easily integrate several different strong authentication systems into your general firewall administration. From within authsrv you can create, modify, disable, delete, and examine users. authsrv maintains a database for this information.

The Firewall Toolkit supports a variety of strong authentication options. The authentication management system understands the types of passwords that these systems use, and provides a consistent user interface to these systems. Currently supported systems are:

SecurID
    This system, available from Security Dynamics, uses a time-based password computed using custom algorithm. Unlike TIS authsrv and other compatible products, OpenFWTK implementation uses builtin algorithm and does not require RSA ACE/Server.

Secure Net Key (SNK)
    This system, from Digital Pathways, uses a random challenge password based on DES encryption.

S/Key,
    also known as OPIE (RFC1938) This system, from Bellcore, uses a one-time password based on variety of digest algorithms selectable by user.

SoftMD5
    Legacy OTP system provided for compatibility with TIS fwtk.

Reusable Passwords
    This system, a part of the user authentication system included with the Firewall Toolkit, is a reusable password option.

Reusable Passwords (SSO)
    A "temportary reusable password system" available as part of authentication agents support, like auth_telnetd (8) .

Transparent Authentication (SSO)
    "User+host" credentials authentication system available as part of authentication agents support, like auth_telnetd (8) .

The various proxies use the information in the user authentication management system any time you have configured the proxies to require authentication. Using the default Firewall Toolkit configuration, this occurs any time a user from an untrusted network tries to access a service inside the perimeter. Recall that untrusted networks are those from which the firewall will accept requests only after authentication by the user.

  Users
User names you create in the user authentication management system are used only for strong authentication. The user names must match the user names for the strong authentication system you are using.

The user names in the user authentication management system do not generally need to match user names on the firewall itself. By default, you do not create any user accounts on the firewall, unless those accounts are used for system-wide authentication by PAM , sshd (8) authentication modules and alikes.

  Groups
The Firewall Toolkit user authentication management system also makes use of groups. Groups allow you to permit or deny services based on groups of user names, rather than individual user names. For example, you can configure the telnet proxy to permit service to everyone in group sales.

Just as is the case with user names, the groups that you create in the Firewall Toolkit user authentication management system are not the same as the groups you create on the firewall or on the internal network. You can of course use the same names, for easier administration. Up to 10 groups are supported per user (Gauntlet and TIS fwtk supported only one).

  Administrators
In addition, the user authentication management system also supports the notion of administrators within the system. Global administrators can create both groups and users. Initially, root is the only global administrator. Creating another global administrator is part of the configuration process for the user authentication system. Within each group, you can also designate group administrators who can create and modify users only within their own group.

As with general UNIX system administration, you have the ability to create a hierarchical system in which you have multiple groups and group administrators. You can also create a monolithic system in which there are multiple administrators and few group administrators.

OPTIONS

  Command Line Options
authsrv recognizes the following command line options (whether started from the command line or from within /etc/rc.local):

-daemon
    Indicates that authsrv runs as a daemon, listening sockets as defined in netperm-table (see configuration options below).

-s  Indicates that authsrv runs in interactive mode, even if stdin is not a tty (useful for batch processing).

  Configuration Options
authsrv reads configuration rules from the /usr/local/etc/netperm-table. It reads all rules using the authsrv and * (wildcard) keywords. authsrv reads the netperm-table from top to bottom. If there are multiple rules in the table that could apply for a particular attribute, authsrv uses the first one that it finds. See netperm-table(5) for a more complete explanation of netperm-table syntax and precedence.

authsrv recognizes the following attributes:

listen-socket inet:port[@bind-address]
    Accept connections on IPv4 port. It is STRONGLY discouraged to run authsrv on firewall host's loopback interface as it used to be on TIS Firewall Toolkit and Gauntlet firewalls, as it requires tricky configuration to prevent firewall users from abusing this interface.

    port
        Specifies port number or service name from /etc/services

    bind-address
        Specifies address to bind (ip in dotted notation, host names are not allowed.

listen-socket unix:socket-path [-user user]
    Accept connections on unix socket. It is the preffered operating mode.

    socket-path
        Specifies unix socket path to autnentication socket.

    user
        Specifies the user ID for process owner allowed to connect to authentication server. This option is valid only if operating system grants peer credential requests for local sockets. user may be either numeric or name from the /etc/passwd file.

badsleep seconds
    Specifies the amount of time the authentication server disallows logins from a user who has attempted (and failed) to login five times in a row.

    seconds
        Specifies the number of seconds the authentication server sleeps before allowing login attempts from a user who has attempted (and failed) to login five times in a row. If this option is set to 0, the authentication server allows an unlimited number of unsuccessful login attempts. If this option is not set, the authentication server disables the account after the user attempts (and fails) to login five times in a row.

database path
    Specifies the pathname of the database that the authentication server uses. This option is mandatory, unless you compile the authentication server with a specific database path.

directory directory
    Specifies the directory that authsrv makes its root directory before providing service.

groupid group
    Specifies the name of the group authsrv uses when running.

    group
        Specifies either a name or numeric id from the /etc/group file.

permit-hosts hosts
    Specifies single hosts, entire networks, or subnets. Specify by IP address or host name. The wildcard * is valid.

deny-hosts hosts
    Specifies the hosts that cannot use authsrv.

    hosts
        Specifies single hosts, entire networks, or subnets. Specify by IP address or host name. The wildcard * is valid.

nobogus true
    Specifies that the authentication server indicates when a user name does not exist when users attempt to login and fail.

    If this option is not specified and a user enters a non-existent user name, the authentication server always responds with a bogus SNK challenge.

    Note that you must remove or comment out this setting if you wish to disable it. The settings nobogus false and nobogus off are not valid.

{permit | deny}-authentication {user users | group groups} service host [time start end ]
    Specifies explicitly if authentication is permitted or denied for particular users or groups at particular times of day. Note that the program requesting authentication should provide correct information about its name and originating host; some third-party modules do not.

    user users
        Specifies the names of users for which the proxies use this rule. The wildcard * is valid.

    group groups
        Specifies the names of groups for which the proxies use this rule. The wildcard * is valid.

    service
        Specifies the name of a service for which this rule applies, p.e. ftp-gw or sshd . The wildcard * is valid.

    host
        Specifies the originating host for session requested authentication. Specify individual machines, entire networks, or subnets. Use IP addresses or host names. The wildcard * is valid.

    time
        Indicates that this rule goes into effect and stops having an effect at a particular time.

    start
        Specifies the time at which the proxy begins using this rule. Specify time in hours and minutes (between 00:00 and 23:59).

    end Specifies the time at which the proxy stops using this rule. Specify time in hours and minutes (between 00:00 and 23:59).

{permit | deny}-operation {user users | group groups} service src dst [options] [time start end ]
    Specifies explicitly permitted or denied operations for particular users or groups at particular times of day. Note that the authentication server only uses these rules when the proxy uses the -extnd attribute.

    user users
        Specifies the names of users for which the proxies use this rule. The wildcard * is valid.

    group groups
        Specifies the names of groups for which the proxies use this rule. The wildcard * is valid.

    service
        Specifies the name of a service for which this rule applies. Valid values are:

        •   ftp-gw FTP proxy

        •   rlogin-gw Rlogin proxy

        •   telnet-gw TELNET proxy

        •   * all of these proxies

    src Specifies the originating host for session requested operation. Specify individual machines, entire networks, or subnets. Use IP addresses or host names. The wildcard * is valid.

    dst Specifies the connection destination host. IP address or hostname is recommended. NOTE -- src/dst pair replaces 'destination' option from TIS authsrv. Unlike TIS authsrv , both source and destination are controlled.

    options
        Specifies particular operations for each protocol that can be controlled. Valid values are:

        •   ftp-gw Consult the ftpd(1) man page

        •   rlogin-gw none

        •   tn-gw none

    time
        Indicates that this rule goes into effect and stops having an effect at a particular time.

    start
        Specifies the time at which the proxy begins using this rule. Specify time in hours and minutes (between 00:00 and 23:59).

    end Specifies the time at which the proxy stops using this rule. Specify time in hours and minutes (between 00:00 and 23:59).

timeout seconds
    Specifies the number of seconds authsrv is idle (with no network activity) before disconnecting

permit-unknown names
    Specifies a list of additional names that authsrv checks (in addition to the authentication database) when checking for extended permissions on a per user basis. If the user name is not in the authentication database, or in the list of names, authsrv logs the attempt and indicates that the user is not valid. If the user name is found in the list of names, authsrv assigns the user name to the group unknown.

    names
        Specifies a list of names, separated by spaces. The wildcard * is valid.

userid user
    Specifies the user ID authsrv uses when running.

    user
        Specifies either a name or numeric id from the /etc/passwd file.

COMMANDS
authsrv recognizes the following commands from within its command line interface:

adduser user [fullname]
    Adds a user to the authentication database. You must be a global administrator or a group administrator to use this command. If you are a group administrator, users you create are the automatically made members of your group. Note that you still must enable a user after you have added the user.

    user
        Name of the user to be added to the authentication database. The user names must match the user names for the strong authentication system you are using. The user names in the user authentication management system do not generally need to match user names on the firewall itself.

    fullname
        The user's full name or other descriptive text about the user. Use quotes for information that contains spaces.

addgroup user group [group..]
    Makes the user a member of the specified group(s). You must be a global administrator to use this command. Unlike obsolete group command described below, addgroup keeps existing groups for the user intact.

authenticate user 'service domain.name/ipaddr'
    authorize user 'service domain.name/ipaddr'

    Performs the first part of authenticating as the specified user with the authentication database. You must use the response command to finish authenticating. After successfully authenticating as the specified user, you operate as that user, with all their privileges.

    Contrary to TIS authsrv specification, the part after user name is not optional anymore, nor it is treated as 'comment'; it is used in conjunction with permit-authentication config line.

    service
        Name of a program (typically, proxy) requested authentication.

    domain.name
        Fully qualified domain name of proxy client in dotted notation.

    ipaddr
        IPv4 address of proxy client.

deluser user
    Deletes the specified user from the authentication database. You must be a global administrator a group administrator to use this command. If you are a group administrator, the user must be a member of your group.

disable user
    Disable the specified user from the authentication database. The user's information remains in the database, but does not allow the user to use the system. The user authentication system disables users after a set number (configurable by the administrator) of failed login attempts. You must be the database administrator or a group administrator to use this command. If you are a group administrator, the user must be a member of your group.

display user
    Displays the status, authentication protocol, and last login of the specified user. You must be the database administrator or a group administrator to use this command. If you are a group administrator, the user must be a member of your group.

enable user [onetime]
    Allows users who have been disabled to use the system again. You must be the database administrator or a group administrator to use this command. If you are a group administrator, the user must be a member of your group.

    user
        Name of a user.

    onetime
        Enables the user for one successful authentication. After the user successfully authenticates once, authsrv automatically disables the user.

exit
    Exits authsrv.

group user group [group..]
    Makes the user a member of the specified group(s). You must be a global administrator to use this command. The group list for user is being overrided by the command; thus if user was a member of a group not specified by the command, it is being excluded from that group. This interface is osolete and implemented for compatibility reasons only, use addgroup and revoke instead.

help
    Displays a list of valid commands for authsrv.

list [group]
ls [group]
    Lists all users in the system, or the members of the specified group. Group administrators may list their own groups, but not the entire database.

operation { user users | group groups } service [ source destination ] [ options ] [ time start end ]
    Determines whether there are any matching per user restrictions specified for this user in the netperm-table. All options match those specified in the netperm-table. operation group syntax is considered obsolete, as operation user performs all necessary group checks. It may be unsupported in future releases.

passwd [user] passwordtext
password [user] passwordtext
    Sets the password for the current user. You must be the database administrator or a group administrator to use this command. If you are a group administrator, the user must be a member of your group.

    user
        Name of a user. If you specify a user name, changes the password for the specified user.

    passwordtext
        Password for the current or specified user. Valid values depend on the protocol being used. For the default protocols, valid values are:

    SecurID
        The seed in hex

    SNK Eight 3-digit groups used to key the SNK calculator for this user

    S/Key
        The seed for the user's password

    password
        A reusable password. Use quotes if the password contains spaces.

proto user protocol
    Sets the authentication protocol for the specified user to the named protocol. You must be the database administrator or a group administrator to use this command. If you are a group administrator, the user must be a member of your group.

    user
        Name of a user.

    protocol
        The name of the authentication protocol. Available protocols depends on the protocols compiled into authsrv. By default, valid values are:

        •   MDAuth

        •   SecurID

        •   Snk

        •   Skey-md4

        •   Skey-md5

        •   Skey-SHA1

        •   Skey-rmd160

        •   password

quit
    Exits authsrv.

rename user newname [fullname]
    Changes the existing record for the existing user with the specified information.

    user
        Name of an existing user in the authentication database.

    newname
        The new user name that you wish to use.

    fullname
        The new user's full name or other descriptive text about the user. Use quotes for information that contains spaces.

revoke user group
    Excludes the user from members of the specified group. You must be a global administrator to use this command.

response text
    Allows you to enter the appropriate password or token to finish authenticating as the specified user with the authentication database. Use quotes for information that contains spaces.

superwiz user
    Makes the specified user a global administrator.

unwiz user group [group..]
    Removes the group administrator flags from the specified user. You must be a global administrator to use this command. This command has no effect on global administrators. To remove global administrator privileges from a user, delete and recreate the user.

wiz user group [group..]
    Makes the specified user a group administrator of the group(s) of which they are currently a member.

?   Displays a list of valid commands for authsrv.

SSO AUTH AGENT PROTOCOL
Single sign-on function is imlemented via "authentication agent" interface, which interacts with authsrv via unix domain socket and allows treating workstations as "authenticated" or using session passwords with protocols that do not work with OTP. When the proxy issues authenticate command, authsrv checks if a unix socked with name /usr/local/var/ip-address.user.sock exists and accepts connections. If it does not, authentication process continues as usual; if it is, an authentication request (the authenticate command received from application) is being sent, followed by newline. The response is received via the same socket and consists of string auth or auth followed by space and session password if one was provided and a newline as well. If authentication fails, response can be any text explaining the reason, as long as it does not start with auth.

EXAMPLES
This example shows the configuration lines in the netperm-table that the authentication server uses the authentication database in /usr/local/etc/fw-authdb:

    authsrv:        database /usr/local/etc/fw-authdb

This example shows an administrator running as root starting authsrv on the firewall, creating and enabling a new user in the authentication database.

root@firewall # authsrv
-administrator mode-
authsrv# list
Report for users in database
user       group      longname      status proto      last
----       -----      --------      -----  -----      ----
fwadmin                               y    Skey-md5   Thu May  2 11:41:42 2007
scooter               Scooter Lindley y    Snk        Wed May  1 09:02:12 2007
authsrv# adduser john 'John Whorfin'
ok - user added initially disabled
authsrv# enable john
enabled
authsrv# proto john Snk
changed
authsrv# pass '160 270 203 065 022 034 232 162' john
Secret key changed
authsrv# list
Report for users in database
user       group      longname      status proto      last
----       -----      --------      -----  -----      ----
fwadmin                               y    Skey-md5   Thu May  2 11:41:42 2007
scooter               Scooter Lindley y    Snk        Wed May  1 09:02:12 2007
john                  John Whorfin    ena  Snk        never
authsrv# quit
#

FILES

/etc/rc.local
    Command script that controls automatic reboot, and includes startup information for authsrv.

/usr/local/etc/fw-authdb
    The database containing user authentication information.

/usr/local/etc/netperm-table
    The network permissions file contains configuration information for the Firewall Toolkit Internet Firewall, including authsrv.

BUGS
Silly TIS DES encryption mode for authsrv communications is deprecated and no longer supported. Given it was signle-pass symmetric key DES anyways and authsrv announces itself with fixed banner, sucn an encryption protocol is worse than nothing as it may provide false sense of security. No more. It is gone for good. Use transport mode IPSEC or any crypto tunnel of your choice if you need distributed firewall infrastructure. If not, it is strongly encouraged to stay with Unix socket communications.

Report bugs to the fwtk-users@buoy.com mailing list. Include a complete example, explaining what you expected to happen and what actually happened. Be sure to indicate the type of system (operating system, hardware, etc.) you are using, as well as the version of the authsrv proxy.

AUTHOR
Alexei Kravchuk.

SEE ALSO
netperm-table(5), rc(8), authmgr(8)