Develop your application using the Websec client
IntroductionThis section explains the steps needed to install and use the provided Websec client, as well as the protocol understood by the Websec server.
Installing the Websec client
Using the provided Websec client
There are two main commands that Websec applications can use: query_token and expire_token. The Websec client is invoked as follows:
websec_client <app name> <command> <command arguments>
We first provide some examples of how the Websec client is used with various commands from the command line. This will illustrate the behavior of the Websec module under various circumstances. We then give some advice on how to use the client from within a CGI script.
Client behavior and how to invoke from the command line
Notice that only app first_app can affect a token that belongs to it. When a different application tries to query for information or expire the token 0cb9ab07942c8d42e1b7d13633970597, the Websec module indicates that it is an invalid token because different_app did not create this token. Note that although different_app's token has timed out, it should still explicitly expire it.% websec_client first_app query_token 0cb9ab07942c8d42e1b7d13633970597 203-PennNet ID nss 203-8-digit PennID 12345678 203-Timestamp 885418633 203 IP Address 221.43.721.159 % websec_client different_app query_token 0cb9ab07942c8d42e1b7d13633970597 301 Invalid token % websec_client different_app expire_token 0cb9ab07942c8d42e1b7d13633970597 301 Invalid token % websec_client different_app query_token 21dced09c24cf929f2a95a43eb9ed242 302 Token timed out % websec_client first_app expire_token 0cb9ab07942c8d42e1b7d13633970597 201 Success % websec_client different_app expire_token 21dced09c24cf929f2a95a43eb9ed242 201 Success
Note that the websec_client now also allows execution whereby every argument after the command itself can be provided through the program's standard input. This provides a greater level of security. This means that for the query_token and expire_token commands, the token would be passed via the Websec client's standard input, not via the command line.We now expound on the above explanation and give some insight on how to use the Websec client in a web application.
How to use within a CGI scriptFor each successive page of the web application, the Websec client must be used to query and/or expire a token. Once the user successfully authenticates on ISC's webserver, the Websec module will indicate this to the user and ask him or her to submit the form to continue with the application. When the user submits the form, the form field websec_token will be passed to the application's first page of the application, a POST CGI script which was specified by the application provider when the application was registered.
The Websec client provided with the distribution is intended to be built as an executable rather than as a library, so that web applications written in any language may still be able to use the Websec module. Example C, Perl, Java, PHP, and ASP/IIS routines which interface with the Websec client are available to assist you with your development.
Note that some developers may wish to use their own method of maintaining state between successive pages in their application and bypass the Websec module for this aspect. If this is the case for your application, it is important to check the validity of the token once on the first page of your application to ensure that the user properly authenticated. It is also imperative to expire the token from the Websec database. These steps will ensure that you can safely use your own method of maintaining state and prevent unauthorized users from gaining access to the application.
The Websec protocol
All of the messages accepted by or generated by the server are noted in the public_messages.h header file. The provided Websec client authenticates the connection with the server, executes one command, and quits the session.
In general, a client initiates a connection and must authenticate itself. All input arguments sent by the client to the server must be separated by tabs. The server will respond with a three-digit numeral followed by a space, a description, and, if necessary, a tab followed by a value.
[client]: helo <application name> <encryption type> [server]: 210 Pleased to ask you to authenticate: <2-digit salt>
If the greeting is invalid, the server disconnects.
The client then builds the password string as follows: "<password>, salt: <salt>". It then crypts this string using the provided salt. If the <encryption type> is 3des, it uses its primary and secondary keys to encrypt it.
[client]: password <password string determined above> [server]: 211 Success
If the password string is invalid, the server disconnects.
At this point, the client is logged in as the user <application name>. Any number of commands can be entered by the client, followed by a quit to disconnect from the server. If 3des is chosen as the encryption type, all messages between the client and server from this point on are encrypted using the two shared keys.
Here are some examples:
[client]: query_token <token1> [server]: 301 Invalid token lient]: query_token <token2> [server]: 302 Token timed out [client]: query_token <token3> [server]: 203-PennNet ID <PennNet ID> 203-8-digit PennID <user's 8 digit PennID number> 203-Timestamp <ctime that the user authenticated> 203 IP Address <IP address where the user authenticated> [client]: expire_token <token1> [server]: 301 Invalid token [client]: expire_token <token2> [server]: 201 Success [client]: expire_token <token3> [server]: 201 Success [client]: quit [server]: 220 Closing connection
Note that any response from the Websec which is in the 200 range means that the operation was successful. Any operation in the 300 range means that the token supplied or the application specified is invalid. The first two such examples above indicate an invalid token for that application. The third such example of an invalid token is one that at one time was valid, but has since timed out. In the case where a token has timed out, no information associated with that token will be returned. Any message in the 500 range indicates that an error occurred, either due to an error that the caller made or an internal error that occurred with the Websec server.
The following are the possible responses by the server. Please note, we only return the 9-digit PennID-digit to older Websec applications and we encourage those applications to discontinue use of the 9-digit PennID. Newer applications can opt to use get the 8-digit PennID from the Websec server.
201 Success 203-PennNet ID nss 203-9-digit PennID 123456789 203-8-digit PennID 12345678 203-Timestamp 88541863 203 IP Address 184.108.40.2069 210 Pleased to ask you to authenticate: <2-digit salt> 211 Success 220 Closing connection 301 Invalid token 302 Token timed out 500 Invalid command 501 Invalid greeting 502 Invalid password 503 Invalid encryption algorithm 510 Error receiving message 511 Internal error 512 Database error 520 Input data too long 521 Syntax error 540 Invalid permission
Information Systems and Computing
University of Pennsylvania
Comments & Questions