Networked Account Manager Protocol


This is the documentation for the Networked Account Manager (NAM) Protocol. The Networked Account Manager Protocol allows multiple machines running the drink server software to connect to one server, thus allowing for centralized user data-storage and management.

The original protocol was developed by Michael Douglas [nodata@csh.rit.edu] and DJ Edwards [dazig@csh.rit.edu]. Kevin Thompson [antiduh@csh.rit.edu] has also contributed to minor improvements.

Index:
Command Summary
add-username/password
 Adds the specified username to the database of users.

bye
Tells the server to end the session and close the socket connecting it to the client.

cau-login/password
Authenticates a Networked Account Client to the Networked Account Server. This is not a user login.

dec-username/amount
Decrements the user's balance by the specified amount.

gub-username
Queries the specified users balance.

inc-username/amount
Increments the specified user's balance. 

isp-username/password
Used to authenticate users logging into clients. Checks to make sure the supplied username and password match.

isv-username
Asks whether or not the specified user is registered with the accounting system.

iua-username
Asks whether or not the specified user is an administrator.

nop
Stands for 'No Operation'. Simply used to 'ping' the server, to determine the connection is still valid.

rem-username
Unregisters the specified user.

sua-username/status
Sets the user's administrator flag to the provided boolean status.

ver
Shows the current version of the NAS. The string returned does not contain spaces.
Acronyms:
NAM - Networked Account Manager
The protocol that defines how account management is done between two systems. In the implementation for the drink software, these two systems are connected by a single TCP socket.
NAS - Networked Account Server, aka 'server'
The server that implements the NAM protocol. The server is responsible for all data storage and manipulation. In one system there is usually only one server, and one or more clients.
NAC - Networked Account Client, aka 'client'
The client that uses the NAM protocol to connect to the NAS. Multiple clients may connect to one server.
Document Conventions:
  • All commands sent to the server from the client will be prefixed by a single colon ':'. This colon is not part of the actual data sent to the server, it is just to provide clarity in examples provided in this document.
  • All commands sent to the client from the server will be prefixed by a single greater-than symbol '>'. Again, this is just for the document example clarity.
  • Parts of the command that are shown in italics represents the actual data that would be provided. For example, add-username simply means that username is replaced with the actual username, such as 'nodata'.

Protocol Conventions:
  • All commands are in the form of cmd-data/extendeddata, for example inc-antiduh/50 (increments a user's balance).
  • Not all commands need or use the extended portion of data, for example gub-antiduh (retrieves the users balance).
  • All acknowledgements are returned in the form of ack-data. If the command was requesting data, such as the users balance, data might be '50'. Most often, however, a simple 'ack-true' is returned to let the client know that the command completed successfully, especially if the command was not requesting data.
  • The NAM protocol is strictly a server-bound protocol. All commands are issued from the client to the server. 
  • Command names are not case sensitive, nor should they be interpreted as so. Data however is treated as case sensitive. This is especially applicable in the situations where usernames are being passed about. 

Connection Details:
  • The server is to listen on port 6464 for connections from clients. Incoming connections will be filtered to prevent unauthorized access in two ways:
    1. First, the server will only accept connections from clients whose IP address is known to the server. If the client is not known, a small message will be sent to the client, and then it will be disconnected.
    2. Second, once the client has successfully solicited a connection to the server, the server will require the client to authenticate itself by means of a username and password. If the client issues any other command other than the authentication command, the return will always be negative - 'ack-false'. Only one attempt is allowed. If the client fails, an 'ack-false' is sent, and it is immediately disconnected.
    Keep in mind that this is not a user trying to log in - a wrong password will continue to be a wrong password until the administrator intervenes and changes the (stored) password that the client is to send.
  • The client may tell the server to kill the connection by issuing the 'bye' command. 
  • The client may test to see if the connection is still active by sending the 'nop' command. This may be useful on embedded systems where connection faults may not be immediately apparent.
  • For commands, if the wrong number of parameters is provided the server will return 'ack-false'. This is also the result with unrecognized commands.

NAM Server-Bound Commands:
These are commands that the client may issue to the server. There are no client-bound commands in the NAM protocol. If the wrong number of parameters are specified, the command will automatically fail. This should be assumed for every command.
For instance, 'gub-antiduh/extradata' will fail because 'gub' only needs to know which user to retrieve the balance for - it needs no additional data.
Similarly, 'inc-antiduh' will fail because the amount to increment antiduh's account was not specified.

add-username/password
Registers a new user with the NAS. The user is created with default values - their balance is set to zero and their admin flag is set to false. 

The password field is provided simply in the case that the drink system were to switch to drink-specific passwords.
As of the writing of this document, the drink system uses the CSH imap server to validate username-password pairs. If the system is not using drink specific passwords, then the password field is discarded. The password, even if blank, must be provided regardless - for example 'add-jason/' is valid. The command will fail if a non-zero-length password must be provided.

The command will also fail if the specified user is already registered.

Example:

:add-jason/whisperwhisper
>ack-true
Server Responses:

>ack-true
The user was successfully registered.

>ack-false
The command may have failed for a variety of reasons:
  • The user was already registered, and therefore could not be re-registered.
  • The command was improperly formed.
  • The password was zero-length, yet the system is using Drink-Specific passwords (which means a password must be provided).

See also rem


bye
Tells the server to end the session and close the socket connecting it to the client. 
This command will not fail if extra parameters are specified, such as 'bye-data/moreData'.

Example:

:bye
>ack-true
>[socket closes]

Server Response:

>ack-true
The server will always respond ack-true to this command. It will never fail. After it responds, the socket it closed by the server.


cau-login/password
Stands for 'client authentication'. 
Authenticates the Networked Account Client with the Networked Account Server. 

When the client first connects, it is required to authenticate. If the client issues any command prior to authenticating, the commands will always return negative, which usually means 'ack-false'. 
The clients username and password pair is also tied to its IP. That is to say, the username, password and IP all have to match in order for the client to pass authentication. 

If the client fails authentication, 'ack-false' will be sent and the client's connection will be severed.

The login is the login specific to the machine that is logging in.
The password is the password that matches that login.

Example:

:cau-machine1/whisperwhisper
>ack-true

Server Response:

>ack-true
The clients username, password, and IP all matched. The client is now authorized to send commands.

>ack-false [disconnect]
The client failed authentication, and was disconnected from the server. This means that the client supplied username and password, as well as the IP it was connecting from did not match.


dec-username/amount
Decrements a user's balance by the specified amount. A users balance may be negative.
Note that the command will fail in the case that the username is not a registered user or the amount to decrement their account was not a number.

This example first retrieves a users balance, and then sets it to -50 credits:

:gub-antiduh
>ack-3000
:dec-antiduh/3050
>ack-true

Server Responses:

>ack-true
The user's balance was successfully decremented.

>ack-false
The username supplied was not a recognized username or the specified amount was not a number.

See also gub, inc.

gub-username
Stands for 'get user balance'.
Queries a specified user's balance. The returned data is the number of credits the user has on their account.
If the user is not known, then the returned balance is zero.

Example:

:gub-antiduh
>ack-3000
Server Responses:

>ack-n
Specifies that the user has n credits left.

>ack-false
The wrong number of parameters were specified.

See also dec, inc


inc-username/amount
Increments the specified user's balance by the provided amount. If the amount is not a number or if the username is not a registered user, the command will fail. If the command succeeds, the return will be true.

Example:

:inc-nodata/100
>ack-true
Server Response:

>ack-true
The specified amount was added to the user's credit balance.

>ack-false
The command failed either because the specified amount was not a number, or the user was not already registered.

See also dec, gub.


isp-username/password
Determines whether or not the supplied username and password pair match. This is used to authenticate users who are connecting to clients. Returns true if the username and password match, false otherwise.

Example:

:isp-antiduh/whisperwhisper
>ack-true
Server Responses:

>ack-true
The password provided for the specified username was correct, meaning that the user is now authenticated.

>ack-false
The username and password did not match; the user is not authenticated.

isv-user
Queries whether or not the given user is a user who is registered with the drink accounting system.
Returns true if the user is recognized, false otherwise.

Examples:

:isv-antiduh
>ack-true

:isv-blarg
>ack-false
Server Responses:

>ack-true
Signifies that the provided user is a known user.

>ack-false
Signifies that the provided user is not a known user.


iua-username
Queries a user's administrator status. If the user is unknown, false will be returned.

Example:

:iua-antiduh
>ack-true

:iua-blarg
>ack-false
Server Responses:

>ack-true
Signifies that the given user is an administrator.

>ack-false
Signifies that either the given user is not recognized or is recognized but is not an administrator.

See also sua



nop
Stands for 'no operation'. It is used to 'ping' the server, to determine if the connection to the server is still valid.
This command may be especially useful if the software is running on an embedded system, where connection failures may not be immediately apparent. If a response is not sent in a timely fashion, the command could be deemed invalid. 

The command will not fail if extra parameters are specified, such as 'nop-data/moreData'.
The command will always return 'ack-true'.

Example:
:nop
>ack-true
Server Response:

>ack-true
The server always returns 'ack-true'. The command will never fail.


rem-username
Unregisteres a known user. If the user is known and the command is successful, the return is true.
If the user is not already registered, or the command failed for an unknown reason, the return is false.

Example:

:rem-antiduh
>ack-true
Server Responses:

>ack-true
The user was successfully removed.

>ack-false
The command failed. Most likely, the user was not already registered.

See also add


sua-username/status
Changes a users administrator flag status. The flag controls the users ability to use privileged commands in an end-user client. 
The status field is either 'true' or 'false', which is the new value of the user's administrator flag.
The command will fail if the status flag is not either 'true' or false, or if the specified user is not already registered.

Example:
:sua-antiduh/true
>ack-true
Server Responses:

>ack-true
The user's administrator flag was successfully changed.

>ack-false
The command failed. Most likely, the given user was not already registered.

See also iua


ver
Shows the current version of the NAS. The string returned does not contain any spaces, and is not formatted specifically for parsing, moreso for displaying to the user. However, the version number is the last part of the string, and immediately follows the last instance of the letter 'v'.

Example:
:ver
>ack-NetAcctServer_v1.30
Server Response:

>ack-NetAcctServer_vN
The response is always in the above form, where N is the 'major.minor' version tag.



This document is maintained by Kevin Thompson [antiduh@csh.rit.edu].

Revision: $Revision: #6 $
Last Changed: $Date: 2003/08/20 $