.TH AUTHSRV 8 "August 2007" "OpenFWTK" .SH NAME authsrv \- network user authentication daemon for third-party systems .SH SYNOPSIS .BI "authsrv [-daemon] [-s]" .SH DESCRIPTION .IX "authsrv" "" "\(em network user authentication daemon" The Firewall Toolkit user authentication daemon .RB ( authsrv ) acts as a piece of "middleware" to provide a unified interface for several strong authentication systems and the firewall. .PP The Firewall Toolkit user authentication management system allows you to easily integrate several different strong authentication systems into your general firewall administration. From within .B authsrv you can create, modify, disable, delete, and examine users. .B authsrv maintains a database for this information. .PP 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: .TP .B 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. .TP .B Secure Net Key (SNK) This system, from Digital Pathways, uses a random challenge password based on DES encryption. .TP .B S/Key, also known as .B OPIE (RFC1938) This system, from Bellcore, uses a one-time password based on variety of digest algorithms selectable by user. .TP .B SoftMD5 Legacy OTP system provided for compatibility with TIS fwtk. .TP .B Reusable Passwords This system, a part of the user authentication system included with the Firewall Toolkit, is a reusable password option. .TP .B Reusable Passwords (SSO) A "temportary reusable password system" available as part of authentication agents support, like .I auth_telnetd (8) \. .TP .B Transparent Authentication (SSO) "User+host" credentials authentication system available as part of authentication agents support, like .I auth_telnetd (8) \. .PP 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. .SS 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. .PP 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 .I PAM , .I sshd (8) authentication modules and alikes. .SS 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 .BR sales . .PP 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). .SS 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, .B 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. .PP 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. .SH OPTIONS .SS Command Line Options .B authsrv recognizes the following command line options (whether started from the command line or from within .IR /etc/rc.local ): .TP .BI "-daemon " Indicates that .B authsrv runs as a daemon, listening sockets as defined in .IR netperm-table (see configuration options below). .TP .BI "-s " Indicates that .B authsrv runs in interactive mode, even if stdin is not a tty (useful for batch processing). .SS Configuration Options .B authsrv reads configuration rules from the .IR "/usr/local/etc/netperm-table" . It reads all rules using the .B authsrv and .B * (wildcard) keywords. .B authsrv reads the .I netperm-table from top to bottom. If there are multiple rules in the table that could apply for a particular attribute, .B authsrv uses the first one that it finds. See .BR "netperm-table" (5) for a more complete explanation of .I netperm-table syntax and precedence. .PP .B authsrv recognizes the following attributes: .TP .BI "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. .RS .TP .I port Specifies port number or service name from .I /etc/services .TP .I bind-address Specifies address to bind (ip in dotted notation, host names are not allowed. .RE .TP .BI "listen-socket unix:" socket-path " [-user " user "]" Accept connections on unix socket. It is the preffered operating mode. .RS .TP .I socket-path Specifies unix socket path to autnentication socket. .TP .I 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. .I user may be either numeric or name from the .I /etc/passwd file. .RE .TP .BI "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. .RS .TP .I 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. .RE .TP .BI "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. .TP .BI "directory " directory Specifies the directory that .B authsrv makes its root directory before providing service. .TP .BI "groupid " group Specifies the name of the group .B authsrv uses when running. .RS .TP .I group Specifies either a name or numeric id from the .I /etc/group file. .RE .TP .BI "permit-hosts " hosts Specifies single hosts, entire networks, or subnets. Specify by IP address or host name. The wildcard * is valid. .RE .TP .BI "deny-hosts " hosts Specifies the hosts that cannot use .BR authsrv . .RS .TP .I hosts Specifies single hosts, entire networks, or subnets. Specify by IP address or host name. The wildcard * is valid. .RE .TP .B nobogus true Specifies that the authentication server indicates when a user name does not exist when users attempt to login and fail. .RS .PP 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. .PP Note that you must remove or comment out this setting if you wish to disable it. The settings .B nobogus false and .B nobogus off are not valid. .RE .\"Can't use the TP and BI commands because the syntax of the operation .\"command won't fit on one line .sp 1 .B {permit | deny}-authentication {user .I users .B | group .IB groups } .I service host .B [time .I start end .B ] .RS 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. .RE .RS .TP .BI "user " users Specifies the names of users for which the proxies use this rule. The wildcard * is valid. .TP .BI "group " groups Specifies the names of groups for which the proxies use this rule. The wildcard * is valid. .TP .I service Specifies the name of a service for which this rule applies, p.e. .I ftp-gw or .I sshd \. The wildcard * is valid. .TP .I 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. .TP .B time Indicates that this rule goes into effect and stops having an effect at a particular time. .TP .I start Specifies the time at which the proxy begins using this rule. Specify time in hours and minutes (between 00:00 and 23:59). .TP .I end Specifies the time at which the proxy stops using this rule. Specify time in hours and minutes (between 00:00 and 23:59). .RE .sp 1 .B {permit | deny}-operation {user .I users .B | group .IB groups } .I service src dst .BI [ options ] .B [time .I start end .B ] .RS 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 .B \-extnd attribute. .RE .RS .TP .BI "user " users Specifies the names of users for which the proxies use this rule. The wildcard * is valid. .TP .BI "group " groups Specifies the names of groups for which the proxies use this rule. The wildcard * is valid. .TP .I service Specifies the name of a service for which this rule applies. Valid values are: .RS .IP \(bu 4n ftp-gw FTP proxy .IP \(bu 4n rlogin-gw Rlogin proxy .IP \(bu 4n telnet-gw TELNET proxy .IP \(bu 4n * all of these proxies .RE .TP .I 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. .TP .I dst Specifies the connection destination host. IP address or hostname is recommended. .B NOTE -- src/dst pair replaces \'destination\' option from TIS authsrv. Unlike TIS .I authsrv , both source and destination are controlled. .TP .I options Specifies particular operations for each protocol that can be controlled. Valid values are: .RS .IP \(bu 4n ftp-gw Consult the .BR ftpd (1) man page .IP \(bu 4n rlogin-gw none .IP \(bu 4n tn-gw none .RE .TP .B time Indicates that this rule goes into effect and stops having an effect at a particular time. .TP .I start Specifies the time at which the proxy begins using this rule. Specify time in hours and minutes (between 00:00 and 23:59). .TP .I end Specifies the time at which the proxy stops using this rule. Specify time in hours and minutes (between 00:00 and 23:59). .RE .TP .BI "timeout " seconds Specifies the number of seconds .B authsrv is idle (with no network activity) before disconnecting .TP .BI "permit-unknown " names Specifies a list of additional names that .B 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, .B authsrv logs the attempt and indicates that the user is not valid. If the user name is found in the list of names, .B authsrv assigns the user name to the group .BR unknown . .RS .TP .I names Specifies a list of names, separated by spaces. The wildcard * is valid. .RE .TP .BI "userid " user Specifies the user ID .B authsrv uses when running. .RS .TP .I user Specifies either a name or numeric id from the .I /etc/passwd file. .RE .SH COMMANDS .B authsrv recognizes the following commands from within its command line interface: .TP .BI "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. .RS .TP .I 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. .TP .I fullname The user's full name or other descriptive text about the user. Use quotes for information that contains spaces. .RE .TP .BI "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 .B group command described below, .B addgroup keeps existing groups for the user intact. .sp 1 .TP .BI "authenticate " user " \'" "service domain.name/ipaddr" "\'" .br .BI "authorize " user " \'" "service domain.name/ipaddr" "\'" .sp 1 .RS Performs the first part of authenticating as the specified user with the authentication database. You must use the .B response command to finish authenticating. After successfully authenticating as the specified user, you operate as that user, with all their privileges. .sp Contrary to TIS .I authsrv specification, the part after .I user name is not optional anymore, nor it is treated as \'comment\'; it is used in conjunction with .I permit-authentication config line. .TP .I service Name of a program (typically, proxy) requested authentication. .TP .I domain.name Fully qualified domain name of proxy client in dotted notation. .TP .I ipaddr IPv4 address of proxy client. .RE .TP .BI "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. .TP .BI "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. .TP .BI "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. .TP .BI "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. .RS .TP .I user Name of a user. .TP .B onetime Enables the user for one successful authentication. After the user successfully authenticates once, .B authsrv automatically disables the user. .RE .TP .B exit Exits .BR authsrv . .TP .BI "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 .I 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 .B addgroup and .B revoke instead. .TP .B help Displays a list of valid commands for .BR authsrv . .PP .BI "list [" group "]" .br .BI "ls [" group "]" .RS 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. .RE .\"Can't use the TP and BI commands because the syntax of the operation .\"command won't fit on one line .sp 1 .B operation { .B user .I users | .B group .I groups } .I service [ .I source .I destination ] [ .I options ] [ .B time .I start end ] .RS Determines whether there are any matching per user restrictions specified for this user in the .IR netperm-table . All options match those specified in the .IR netperm-table . .B operation group syntax is considered obsolete, as .B operation user performs all necessary group checks. It may be unsupported in future releases. .RE .sp 1 .BI "passwd [" user "] " passwordtext .br .BI "password [" user "] " passwordtext .RS 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. .TP .I user Name of a user. If you specify a user name, changes the password for the specified user. .TP .I passwordtext Password for the current or specified user. Valid values depend on the protocol being used. For the default protocols, valid values are: .TP .B SecurID The seed in hex .TP .B SNK Eight 3-digit groups used to key the SNK calculator for this user .TP .B S/Key The seed for the user's password .TP .B password A reusable password. Use quotes if the password contains spaces. .RE .RE .TP .BI "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. .RS .TP .I user Name of a user. .TP .I protocol The name of the authentication protocol. Available protocols depends on the protocols compiled into .BR authsrv . By default, valid values are: .RS .IP \(bu 4n MDAuth .IP \(bu 4n SecurID .IP \(bu 4n Snk .IP \(bu 4n Skey-md4 .IP \(bu 4n Skey-md5 .IP \(bu 4n Skey-SHA1 .IP \(bu 4n Skey-rmd160 .IP \(bu 4n password .RE .RE .TP .B quit Exits .BR authsrv . .TP .BI "rename " "user newname" " [" "fullname" "]" Changes the existing record for the existing user with the specified information. .RS .TP .I user Name of an existing user in the authentication database. .TP .I newname The new user name that you wish to use. .TP .I fullname The new user's full name or other descriptive text about the user. Use quotes for information that contains spaces. .RE .TP .BI "revoke " "user group" Excludes the user from members of the specified group. You must be a global administrator to use this command. .TP .BI "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. .TP .BI "superwiz " user Makes the specified user a global administrator. .TP .BI "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. .TP .BI "wiz " "user group [group..]" Makes the specified user a group administrator of the group(s) of which they are currently a member. .TP .B ? Displays a list of valid commands for .BR authsrv . .SH SSO AUTH AGENT PROTOCOL Single sign-on function is imlemented via "authentication agent" interface, which interacts with .BR 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 .B authenticate command, .BR authsrv checks if a unix socked with name .IR "/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 .I authenticate command received from application) is being sent, followed by newline. The response is received via the same socket and consists of string .B auth or .B 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 .BR auth . .SH EXAMPLES This example shows the configuration lines in the .I netperm-table that the authentication server uses the authentication database in .IR /usr/local/etc/fw-authdb : .sp 1 .nf .na .RS authsrv: database /usr/local/etc/fw-authdb .RE .fa .fi .sp 1 This example shows an administrator running as .B root starting .B authsrv on the firewall, creating and enabling a new user in the authentication database. .sp 1 .nf .na root@firewall # authsrv -administrator mode- .RB "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 .RB "authsrv# " "adduser john 'John Whorfin'" ok - user added initially disabled .RB "authsrv# " "enable john" enabled .RB "authsrv# " "proto john Snk" changed .RB "authsrv# " "pass '160 270 203 065 022 034 232 162' john" Secret key changed .RB "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 .RB "authsrv# " quit # .fa .fi .SH FILES .IP /etc/rc.local Command script that controls automatic reboot, and includes startup information for .BR authsrv . .IP /usr/local/etc/fw-authdb The database containing user authentication information. .IP /usr/local/etc/netperm-table The network permissions file contains configuration information for the Firewall Toolkit Internet Firewall, including .BR authsrv . .SH BUGS Silly TIS DES encryption mode for .BR authsrv communications is deprecated and no longer supported. Given it was signle-pass symmetric key DES anyways and .BR 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. .PP 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. .SH AUTHOR Alexei Kravchuk. .SH SEE ALSO .BR netperm-table "(5), " rc "(8), "authmgr "(8)"