The XML Security Framework for Web Applications
Joseph P. Attardi
Jesse M. Heines
University of Massachusetts Lowell
Dept. of Computer Science
One University Avenue, Lowell, MA 01854
01-1-978-934-3634
{jattardi,heines}@cs.uml.edu
1. INTRODUCTION 3. PACKAGE OVERVIEW
Java Servlet containers such as Apache Tomcat (1) There are three main components of the XSF.
contain built-in, container-managed services that There is a set of JSP pages that are utilized by an
provide security features to Web applications (2). application, a set of helper classes that are utilized
However, in some cases these services can be by the JSPs, and the XML files that contain user
either too complex or insufficient for an and configuration data for an application.
application at hand. The XML Security Framework
(XSF) is a set of JavaServer Pages (JSPs) and 3.1 JSP Pages
helper classes that implement a robust, easy-to-use There are several JSP files included as part of the
security framework for a wide range of Web XSF. Some are for authentication and
applications. User names, passwords, and other authorization for a protected page. These are used
configuration information is stored in XML files. by simply including them in a page to protect.
This document describes the basic architecture and Other JSP files are for interfacing with the helper
functionality of the XSF. classes that implement the security functionality
“behind the scenes”. These are usually accessed by
The XML Security Framework uses dom4j, an sending an HTTP POST request with several form
open-source XML framework for Java, for all its fields, depending on the action to be taken. The
XML processing (3). JSP files included are:
authenticate.jsp: Protects a JSP page by
2. FEATURES requiring a user to be authenticated before
The XSF has several robust features that can be permitting access to it.
integrated with any JSP-based Web application: require-admin.jsp: Further protects a JSP
Password Protection – JSP pages are page by only allowing access to users with
protected on a page-by-page basis. administrative privileges, if desired.
Authentication – User names and security-common.jsp: This contains several
passwords are stored on the server and a variables and methods that are needed for
user can be authenticated. Passwords are interacting with the security classes, and
encrypted with a hash algorithm, similar to should also be included on every protected
the UNIX password encryption scheme. page.
Authorization – Users can have different security.jsp: This is the main interface to
permission or authorization levels and the security classes. It performs one of
access rights can be granted or denied based several actions on the password file.
on those levels.
User Attributes – Extended attributes for a 3.2 Support Classes
user can be stored in the password file and Several helper or support classes are included with
accessed through public APIs for which the XSF. These classes actually interact with the
JavaDocs are available. password and configuration files. All classes are in
Logging – The XSF also includes a logging the edu.uml.cs.xmlsecurity package and are as
subsystem which logs both page accesses follows:
and security-related events.
edu.uml.cs.xmlsecurity.ConfigHandler: This Edits a user's information in the
editInfo:
class provides access to an application's password file.
configuration data. This data is stored in an The location of this application's
XML configuration file. configuration file. This is needed so the
edu.uml.cs.xmlsecurity.LogMgr: This class location of the password file, log files, and
provides services to write entries to the other properties can be looked up.
application logs. The base directory, relative to the
edu.uml.cs.xmlsecurity.SecurityHandler: application root, of the JSP page making the
This is the core security class. It provides all request. This is used to properly redirect the
access to the password file and has services request to an appropriate response page.
such as adding/removing users, Other parameters are expected depending on
authenticating users, encrypting passwords, the action to be performed. For example, the
etc. login action expects user and pass
edu.uml.cs.xmlsecurity.User: This is a parameters.
user's authentication token. When a user is
successfully authenticated, a User object is When a request is sent to the security.jsp page for
created and placed in their HTTP session. a particular action, the security.jsp page then
This allows the XSF to see that the user is interacts with the support classes such as
authenticated, and also provides access to all edu.uml.cs.xmlsecurity.SecurityHandler or
the user's information from the password edu.uml.cs.xmlsecurity.ConfigHandler to carry out
file. the requested action.
3.3 XML Files Each action has certain result pages associated
There are two XML files that every application with it in the configuration file. For example, for
must have in order to use the XSF. the login action, there are corresponding login-
password.xml: This is the password file. It success-page and login-failure-page properties in
contains the user names, encrypted the configuration file. Depending on the outcome
passwords, and other attributes for each of the operation, the security.jsp page will
user. forward the user to the appropriate page and
security-config.xml: This is the main display an informative result message.
configuration file. It allows the developer to
configure elements such as the log directory, 4.2 The SecurityHandler Class
the location of the login page, etc. All operations on the password file are carried out
by the SecurityHandler class. It opens the XML
4. ARCHITECTURAL OVERVIEW password file and adds to, removes from, or reads
Now that the various components of the XSF have this file as needed. The dom4j APIs are used
been discussed, we can move on to a more detailed extensively in SecurityHandler to serialize XML
look at the architecture of the software. data and look up user records with XPath searches.
For example, the following code snippet looks up
4.1 security.jsp: The Main Component all of a user's attributes and creates a new
For any JSP page to interact with the XSF, it must edu.uml.cs.xmlsecurity.User object with the data:
submit a request to the security.jsp page. It Node node_user;
expects certain parameters to be passed to it to
// Try to find a matching node.
determine what action to take for a given request: If no is found matching
The action to perform, one of the following: // the requested name, we have to throw
login: Authenticates and logs in a user. an exception here.
node_user =
logout: Clears a user's authentication doc_passwords.selectSingleNode("/user-
information, logging them out. list/user[name=\"" + str_name + "\"]");
signup: Signs up a new user for an if (node_user == null)
throw new
account. NoSuchUserException(str_name);
pwChange: Changes a user's password.
remove: Removes a user.
return new Security events: These events occur when a
User(node_user.selectSingleNode("name").getText
(), user logs in, logs out, changes their
password, etc.
node_user.selectSingleNode("course").getText(), These two event types are handled by two methods
node_user.selectSingleNode("section").getText() in the LogMgr class: logActivity() and
, logSecurity().
node_user.selectSingleNode("auth-
level").getText(), 4.5 The User Class
The User class acts as an “authentication token”
node_user.selectSingleNode("directory").getText which contains a user's information. A User object
());
is placed in a user's HTTP session whenever the
SecurityHandler also encrypts users' passwords. user is authenticated. This class contains methods
The password is run through a one-way hash for retrieving values such as the username,
algorithm, the SHA-1 (Secure Hash Algorithm) authorization level, and any other attributes that are
algorithm (4) as follows. First, the password is in the password file.
converted to a byte array. The byte array is then
run through the SHA-1 algorithm (a 5. PASSWORD PROTECTION &
java.security.MessageDigest object): AUTHENTICATION
MessageDigest md_sha = To password-protect a JSP page, include the
MessageDigest.getInstance("SHA-1"); authenticate.jsp and security-common.jsp files in
md_sha.update(str_pass.getBytes());
byte[] b_digest = md_sha.digest(); the page to be protected:
password is placed in a new byte array. When
encrypted password are BASE64-encoded so that it is When a user requests a page protected in this
printable. manner, the code in authenticate.jsp first looks in
Example: If we run the string password through the the user's HTTP session for a User object, bound to
SHA-1 algorithm then BASE64-encode the result, we the name “authenticated”. It makes this check by
get the encrypted password calling session.getAttribute(“authenticated”). If
W6ph5Mm5Pz8GgiULbPgzG37mj9g=. the method call returns null, then the user has no
authentication token. The code then issues an
4.3 The ConfigHandler Class HTTP redirect to a login page so the user will be
The function of the ConfigHandler class is to read able to log in and access the protected resources. If
properties from the security-config.xml file. Just the call to session.getAttribute() returns a valid
like SecurityHandler, it uses the dom4j APIs to User object, then the user is already authenticated
process the XML data. The primary method of and the page is displayed to them.
ConfigHandler, getField(), is very simple. Like the
earlier example for SecurityHandler, this method If the user was not authenticated, they are
just uses XPath to locate the corresponding field. redirected to a login page as described above. This
Node node_field = page contains a simple HTML form with fields for
doc_config.selectSingleNode("/security-config/" the username and password. It also contains some
+ str_field);
return (node_field == null ? null : hidden fields – those expected by the security.jsp
node_field.getText()); file (see section 4.1 for more details). The user
fills out the form and submits their credentials to
4.4 The LogMgr Class the security.jsp page to be authenticated.
Another useful feature of the XSF is logging. The
LogMgr class keeps track of two kinds of events: Upon receiving this request, the security.jsp file
Activity events: These events occur when a looks in the configuration file for the location of
user views a page. It allows the the password file. It then opens the file and
administrator to see who is visiting what retrieves the user's encrypted password. Since the
pages. SHA-1 algorithm is a one-way hash, the stored
password cannot be decrypted. Therefore, the
user's submitted password is run through the same
SHA-1 hash. If the result of the hash matches the A user logging in
encrypted password in the password file, the user A user logging out
has entered the correct password. An incorrect login attempt
A user changing their password
Once the user's credentials have been A non-administrative user attempting to
authenticated, a new User object is created and access an administrative-only resource
populated with the user's data from the password These events are all logged in the security.jsp file
file. This object, the authentication token through calls to logSecurity().
mentioned above, is placed in the user's HTTP
session. The user then gets a HTTP redirect to the 7. AUTHORIZATION LEVELS
login success page, as defined in the configuration One of the fields in the password file is that of an
file. authorization, or permission, level. In the current
version of the software there are only two
6. LOGGING EVENTS authorization levels – student (a normal,
The LogMgr class handles the logging system. Log unprivileged user) and admin (a full administrative
files are kept by the month - when a new month user with all privileges). Certain actions in the
starts, a new log file is created. There are two types security.jsp file are restricted to administrators
of events that are logged – activity events and only: changing the password of another user,
security events. removing a user account, etc. The User object has
a method, isAdmin() which will return true if the
The log files are, of course, XML. A sample log user is an administrative user. This can be used to
entry looks like this: hide content from a non-administrative user in a
JSP page:
2003-12-14
23:50:44 Administrator Page
timestamp>1071445844270
joe
Viewed page: In addition to adding content to pages for
/umlgui/index.jsp administrators, you can also designate a page as
being an administrative-only page. This is
The log file contains two timestamp formats. One accomplished with the require-admin.jsp file. To
is a nice human-readable format, and the other is designate a page as administrative-only, simply
the standard Java way of representing a timestamp. include the require-admin.jsp file along with
It is a long representing the number of seconds security-common.jsp and authenticate.jsp.
since midnight on January 1, 1970. This allows an
manipulate the date in any way desired. If a non-administrative user attempts to access
such a page, they will be redirected to an “access
6.1 ACTIVITY LOGGING denied” page and an entry will be made in the
Whenever a user accesses a protected page, the security log of the action.
page access is logged in the activity log. The code
that calls logActivity() in the LogMgr is contained 8. SUMMARY AND FUTURE WORK
also in the authenticate.jsp file. Before checking This document provided a tour of the architecture
the user's session for an authentication token, it and features of the XML Security Framework, the
checks to see if the user's has a LogMgr instance end product of my Independent Study in the fall of
associated with it. If not, it will instantiate a new 2003 at the University of Massachusetts Lowell.
LogMgr to handle logging events for this user. If the The framework went through several intermediate
user has been authenticated and is allowed to beta versions from September to December 2003.
proceed, the authenticate.jsp code then calls Version 1.0 was successfully built and tested on
logActivity() to log the page access. December 12, 2003 and is currently being
integrated into other Web application projects.
6.2 SECURITY LOGGING
A security event is one with some security-related That being said, this is only a 1.0 release. There are
implications. Some examples include many more useful features that could be added to
this framework. However, due to its modular http://www.cafesoft.com/products/cams/tomcat
design using only JSPs and helper classes, this -security.html (accessed December 2, 2003).
package can easily be extended or integrated into (3) MetaStuff Ltd (2003). dom4j: The Flexible
other future security-related projects. XML Framework for Java. Posted at
http://www.dom4j.org/ (accessed December 2,
9. REFERENCES 2003).
(1) Apache Foundation (2003). Tomcat Home (4) National Institute of Standards and Technology
Page. Posted at (1995). Secure Hash Standard. Posted at
http://www.itl.nist.gov/fipspubs/fip180-
http://jakarta.apache.org/tomcat/ (accessed
1.htm (accessed December 8, 2003).
December 19, 2003).
(2) Cafesoft (2003). Tomcat Security Overview and
Analysis. Posted at