FOR ARCHIVAL PURPOSES ONLY The following instructions apply to using Websec to authenticate for web applications. Websec was retired in December 2009 and replaced by a new authentication system, Penn Weblogin.

Develop your application using the Websec client

Introduction

• Installing the Websec client.
• Using the Websec client.
  • Client behavior and how to invoke from the command line.
  • How to use the client within a CGI script.
• Understanding the Websec protocol.

1. In the dist_client.h file, choose the location of the application password file (as defined by WEBSEC_AUTH_FILE), and indicate the Websec server hostname and port number.

2. Create the application password file (mentioned above):

   The Websec password file contains all of the clients applications, their password, and primary and secondary keys. Each entry is in the following tab-delimited format:

   <application name> <application password> <key1> <key2>

   As you create new Websec applications on this machine, continue to add lines to this file. Note that this file should only be readable by the applications which use the Websec client.

3. Copy the password file to the location specified in the dist_client.h file, making it readable only by the processes which need to read it.

4. In the Makefile in this directory, modify the TARGETDIR, OWNER, and GROUP specifications. The client should only be executable by the applications, so modify the OWNER and GROUP permissions appropriately.

5. Modify the LIBS variable, appropriate for your environment.

6. make clean, make install, and make clean.

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.

% 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.

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.

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  222.111.72.519

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