########################################################################## # # # # # Claims_DB_listener.sh # # Planned Authentication Procedure # # Document Date: 29 November 2009 # # Document Author: B Tasker # # # # # ########################################################################## Contents --------- - Aim - Methods - Implementation - User Authentication - Hostname Authentication - Request Methods - Server Responses Aim ----- To allow Claims_DB Server Administrators to require connecting clients to authenticate. Methods -------- Two methods of authentication will be supported - User - Hostname User authentication will require the connecting client to provide a valid username and password combination. Hostname authentication will examine the remote clients I.P. Address and optionally it's DNS name in order to see if that client has been granted access (whitelist based authentication - Default DENY) Implementation ---------------- Both authentication methods can be active at the same time, or alternatively either can be activated independantly. It is expected that in most cases the username & password will be supplied by the Front end running on the client rather than the user themselves. For both authentication methods the Server admin will have a choice of supplying either a single token in the config file, or multiple tokens in a database. The storage location of the tokens will be stored in the config file (i.e. Config or DB). The server will be running Claims_DB so it is logical to provide the ability to store tokens in a Claims_DB Database. Both authentication methods will require an independant table (i.e. Hosts and users) There will be 3 levels of access granted - Admin - Read - Read/Write Admin access will allow the connecting user/host to update the Claims_DB_listener authorisation database. Read access will allow the user to read from any stored database (except the Claims_DB_listener authorisation database), but not to write to them. Read/Write will provide full access to all databases except the Claims_DB_listener authorisation database. If a User/Host is provided in the config file, it will be assumed that they have full admin read/write access. However as the details are stored in the config file, there is not likely to be a Claims_DB_listener authorisation database present, and the user will be unable to remotely update the configuration file. The server admin will not be able to store tokens in both the Config file and a Database. It will be one or the other. User Authentication --------------------- The user password will be stored as a salted hash. This will be comprised of the hostname of the server, the username and the password. A script will be provided for admins to generate the necessary hash when creating users. It is strongly recommended that if User based authentication is activated, the server admin should configure the webserver that Claims_DB_listener relies on to ensure that all transactions take place over an encrypted connection. Otherwise clients will transmit usernames & passwords in plain text. If the network is trusted, then an unencrypted connection could be used. But it would still be wise to activate SSL. Hostname Authentication ------------------------- The system will use the information provided to it by the webserver in order to ascertain the client's IP address and hostname. This will then be checked against the token(s) in the config file/DB. The server admin will be able to specify whether to check the Hostname or the I.P. Address. It is expected that hostnames will be more effective in a DHCP environment where I.P. addresses change regularly. Request Methods ----------------- The Hostname authentication method requires no additional input from clients, all processing will take place on the database server. Database requests can be placed as normal. The User authentication procedure will require clients to provide a username under the variable USER and a Password under the variable PASS. Existing clients may need updating to support this functionality (it's advised to store the username and password in your front-end's config file in case it needs changing) An example call using User authentication would be Claims_DB_listener.sh?USER=Myuser&PASS=MyPass&METHOD=2&DBNAME=MyDB&TABLE=MyTable Server Responses ------------------ No new responses will be added to Claims_DB_listener to support the change. In order to try and maximise security, feedback will not suggest that authentication failed. - If a user/host fails to authenticate they will simply receive the response ERROR - If a user with read privileges attempts to write to a database, they will receive the error INHIBITED In order to help with application developement, an extra option will be added to the config file - AUTH_DEBUG. If AUTH_DEBUG is set to Y then a failure to authenticate will return the error "ACCESS DENIED INVALID USER/HOSTNAME" Additionally, if a user with read access attempts to write to a database, they will receive the response "ACCESS DENIED INSUFFICIENT PRIVILEGES" AUTH_DEBUG will not be remotely updateable, and must be set by the server admin. It is strongly recommended that for day to day use this should be set to N. ########################################################################## # # # Copyright Ben Tasker 2009 # # Released under GNU GPL V3 # # See http://benscomputer.no-ip.org/LICENSE # # # # DOCUMENT END # # # ##########################################################################