To connect clients to the iiitAccessServer, the server two has two interfaces. For applications written in Java a RMI interface exits, while other application may talk to the server using a TCP/IP socket.
Both interfaces are described in following sections.
Applications written in Java may talk to the iiitAccessServer using RMI. This method has the advantage, that there is a ready-to-use client library, which implements in addition to the pure communication a local cache. As a very simple example of a RMI client, you may look at SimpleClient. This program allows to send requests to the server and display the responses. Another example is the program ShutDown, which can be used to shut down a server running on the local host.
To create Java clients, the binary packages includes a client library named iiitAccessClient.jar. This jar file contains only those classes needed for the client.
The classes the RMI interface consists of are described in detail in the Guide for Java programmers.
Applications not written in Java can use the TCP/IP interface to talk to the iiitAccessServer. With a simple protocol and an also simple command language commands can be sent to the server and responses can be received.
When opening the socket, the iiitAccessServer shall greet you with a message like:
iiitAccessServer - For help send command "HELP" OK
The iiitAccessServer is now ready to receive commands.
The different commands will described below in separate chapters.
Every command will be answered with a result – if there is one – and a line with the content
OK
or with an error message
ERROR <number>: <message text>
All possible error messages are also described below.
After the response has been finished with OK or ERROR ..., the iiitAccessServer is ready again to receive the next command.
The following commands are defined and will be discussed in the next chapters:
HELPQUITSHUTDOWNSETUSER=<user>EXPR=<expression>
The server does not distinguish between upper- and lower case.
The command HELP is thought for interactive sessions. It gives you a short overview of the valid commands:
HELP - This help QUIT - Close connection SETUSER=<user> - Set user for expressions EXPR=<expression> - Evaluate expression OK
This command closes the current session. It responses with a short notice:
Closing connection
This response does not end with OK, because the server will not accept any further command from this connection.
The command SHUTDOWN takes a special role. It shuts down the iiitAccessServer. For security reasons, this command will only be accepted if send from localhost, e.g. with a telnet session like this one:
> telnet localhost 54321
The server responses with short notice like:
Closing connection and shutting down
This response does not end with OK also.
The command SETUSER=<user> sets the current user for ongoing requests of user rights. The name of the user must be sent as a parameter of the command:
setuser=joe OK
Last but not least the command EXPR=<expression> will be used to send the requests to the server. The parameter may be the name of a group, the name of a person, the name of an expression or even a dynamically created expression consisting of those components. Here are some examples:
setuser=joe OK expr=confirm false OK expr=joe true OK expr=confirm-joe false OK expr=confirm+joe true OK
The server responses with true if the user is a member of the result set or false otherwise. The responses will finish with OK.
All error messages consist of the key-word ERROR, a unique error numer and a textual message. Currently, there are four different error messages defined, which will be discussed in the next chapters.
This error message has the unique number 100. It will be sent if the command could not be recognized. Here are some examples:
help=1234 ERROR 100: Unknown command asdf ERROR 100: Unknown command setuser ERROR 100: Unknown command ERROR 100: Unknown command
This error message with the number 101 will be returned, if the command line contains syntactical errors. Here are some examples:
setuser= ERROR 101: Syntax error a+b ERROR 101: Syntax error a + b ERROR 101: Syntax error a s d f ERROR 101: Syntax error
This error message will be sent if you requested a user right but did not set a current user. The error number is 200.
iiitAccessServer - For help send command "HELP" OK expr=confirm ERROR 200: No user set
If the expression could not be evaluated, you will get this error message with the error number 201. The cause of the error will be appended to the textual message. The following example shows the response if there is a syntactical error inside the expression, but there are other causes possible.
expr=confirm*joe ERROR 201: Expression <confirm*joe> can not be evaluated - There is something strange near position 7 in <confirm*joe>
(In reality, this message will be printed in one line)
The error message will be printed if the global configuration attribute VerifyUser is true and an invalid user ID is passed to the command SETUSER.
iiitAccessServer - For help send command "HELP" OK setuser=joe OK setuser=bob ERROR 202: Invalid user ID
The possibilities of the iiitAccessServer are described in detail in our White Paper. Therefore we will give you an overview of the syntax of expressions only.
As shown in the picture, two groups can be combined. Mathematically spoken, the set C is a union of sets
C = A ∪ B.
Because set operations can not be expressed with the common ASCII character set, it will be written as
C = A + B
inside iiitAccessServer.
The second example shows the intersection of the sets C and D with the exclusion of set E. The mathematically correct representation of this operation
F = C ∩ D \ E = (A ∪ B) ∩ D \ E
can also not be written with the ASCII characters. Therefore it will be written as
F = C & D - E = (A + B) & D - E.
inside iiitAccessServer. The result will include all users which are members of groups C and D but not members of group E.
All these formulas can be written as Strings this way: