Overview

Security in Resin consists of four separate functions:

• Authentication: Who is trying to use the resource?
  • login-config: How the client sends the user and password.
  • authenticator: How the server checks the user and password to authenticate a user.
• Authorization: Is the client allowed to use the resource?
• Encryption (SSL): Protecting data from prying eyes.
• Security Manager (for ISPs only) : Protecting users from each other.

By using Resin's login support, applications can add security without writing an entire authentication library. If the predefined authentication methods, XML and database user lookup, are inadequate, Resin provides an API to write custom authentication code.

The easiest authenticator to understand is the XmlAuthenticator. It lets you put users and passwords directly in the configuration file. The following example uses "Basic" authentication for login. Basic authentication asks the browser to pop open a window prompting for a username and password. (Basic authentication is discouraged because it is not secure unless you use it with SSL, but it's the easiest example.) The only user defined here is "Harry Potter" and he has the password "quidditch". He also plays the "user" role.

<web-app>
<login-config auth-method='basic'>
  <authenticator>
    <class-name>com.caucho.http.security.XmlAuthenticator</class-name>
    <init-param user='Harry Potter:quidditch:user'/>
  </authenticator>
</login-config>
<security-constraint url-pattern='/users-only/*' role-name='user'/>
</web-app>

In the above example, the <security-constraint> checks for authorization. Only users playing the "user" role can access the /users-only directory.

Authentication

login-config

auth-method

form-login-config

authenticator

XmlAuthenticator

The XmlAuthenticator (com.caucho.http.security.XmlAuthenticator), stores the authentication in either an xml file or in the configuration itself.

When configuring the XmlAuthenticator in the resin.conf (or web.xml), each init-param user adds a new configured user. The value contains the username, password, and the roles the user plays.

<authenticator>
  <class-name>com.caucho.http.security.XmlAuthenticator</class-name>
  <init-param user='Harry Potter:quidditch:user,gryffindor'/>
  <init-param user='Draco Malfoy:pureblood:user,slytherin'/>
</authenticator>

Because the plain text passwords in the example above are a serious security issue, most sites will use the password-digest attribute described below to protect the passwords.

attribute	meaning
user	specifies an allowed user. May be repeated.
password-digest	selects the signature method to protect the password
path	specifies a path to an XML file containing the users and passwords.
logout-on-session-timeout	If true, the user will be logged out when the session times out	true

The passwords can be specified in a separate *.xml file. The password file looks like:

<authenticator>
  <user name='Harry Potter' password='quidditch' role='gryffindor'/>
  <user name='Draco Malfoy' password='pureblood' role='slytherin'/>
</authenticator>

Sites should use password-digest to protect the passwords.

JdbcAuthenticator

The JdbcAuthenticator (com.caucho.http.security.JdbcAuthenticator), asks a backend database for the password matching the user's name. It uses the DataSource specified by the pool-name option, or the JNDI java:comp/env/jdbc/db-pool by default. pool-name refers to a DataSource configured with resource-ref.

The following are the attributes for the JdbcAuthenticator:

attribute	meaning
pool-name	The database pool. Looks in the application attributes first, then in the global database pools.
password-query	A SQL query to get the user's password. The default query is given below.
cookie-auth-query	A SQL query to authenticate the user by a persistent cookie.
cookie-auth-update	A SQL update to match a persistent cookie to a user.
role-query	A SQL query to determine the user's role. By default, all users are in role "user", but no others.
password-digest	Specifies the digest algorithm and format (Resin 2.0.4)
logout-on-session-timeout	If true, the user will be logged out when the session times out (Resin 2.0.6)	true

<!-- Resin-specific JdbcAuthenticator --> <authenticator id='com.caucho.http.security.JdbcAuthenticator'> <pool-name>test</pool-name> <password-query> SELECT password FROM LOGIN WHERE username=? </password-query> <cookie-auth-query> SELECT username FROM LOGIN WHERE cookie=? </cookie-auth-query> <cookie-auth-update> UPDATE LOGIN SET cookie=? WHERE username=? </cookie-auth-update> <role-query> SELECT role FROM LOGIN WHERE username=? </role-query> </authenticator>

PasswordDigest

Resin 2.0.4 adds the capability to store the digest of a password instead of the password itself. By using the password digest, the application can avoid storing the password in a form that someone can read.

Setting password-digest of any authenticator extending AbstractAuthenticator will create a digest of the password. The password-digest has two parts: the digest algorithm and the encoding format. "MD5-base64" is a typical digest format.

The authenticator will create a digest of the username and password. Since that digest is a byte array, it is then converted to a string.

MD5(username:password)

Using password-digest with XmlAuthenticator

<authenticator> <class-name>com.caucho.http.security.XmlAuthenticator</class-name> <init-param password-digest='MD5-base64'/> <init-param user='harry:Syvian7bcPDKI261QvH9Cw:user'/> </authenticator>

Of course, storing the digest password take a bit more work. When the user registers, the application needs to compute the digest to store it. You can use the PasswordDigest class to do that.

import com.caucho.http.security.PasswordDigest; ... PasswordDigest digest = new PasswordDigest(); digest.setAlgorithm("MD5"); digest.setFormat("base64"); String password = digest.getPasswordDigest("harry", "quidditch");

Authorization (security-constraint)

security-constraint

Selects protected areas of the web site. Sites using authentication as an optional personalization feature will typically not use any security constraints.

Security constraints can also be custom classes.

<security-constraint>
  <web-resource-collection>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <auth-constraint role-name='user'>
</security-constraint>

web-resource-collection

Specifies a collection os areas of the web site.

url-pattern	url patterns describing the resource
method	HTTP methods to be restricted.

auth-constraint

Requires that authenticated users fill the specified role. In Resin's JdbcAuthenticator, normal users are in the "user" role. Think of a role as a group of users.

role-name

Roles which are allowed to access the resource.

Protecting webdav for webdav users

<security-constraint> <auth-constraint role-name='webdav'> <web-resource-collection> <url-pattern>/webdav/*</url-pattern> </web-resource-collection> </security-constraint>

ip-constraint

Requires that the remote address is in an IP network. ip-constraint is very useful for protecting administration resources to an internal network.

<security-constraint>
  <ip-constraint>192.168.17.0/24</ip-constraint>

  <web-resource-collection>
    <url-pattern>/admin/*</url-pattern>
  </web-resource-collection>
</security-constraint>

user-data-constraint

Restricts access to secure transports, i.e. SSL.

transport-guarantee

Required transport properties. NONE, INTEGRAL, and CONFIDENTIAL are allowed values.

<security-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> <web-resource-collection> <url-pattern>/*</url-pattern> </web-resource-collection> </security-constraint>

transport-guarantee

Restricts access to secure transports, i.e. SSL.

constraint

Defines a custom constraint. The custom constraint specifies a <class-name> which extends com.caucho.http.security.AbstractConstraint. Any init-param elements use Bean introspection to initialize the constraint.

... <security-constraint> <constraint> <class-name>qa.CustomSecurity</class-name> <init-param foo='ok'/> </constraint> <web-resource-collection url-pattern='/*'/> </security-constraint> ...

Custom Security Constraints

Any custom security constraint is checked after any authentication (login) but before any filters or servlets are applied. The security constraint will return true if the request is allowed and false if it's forbidden. If the request is forbidden, it's the constraint's responsibility to return an error page.

package qa; import java.io.*; import javax.servlet.*; import javax.servlet.http.*; import com.caucho.http.security.*; public class CustomSecurity extends AbstractConstraint { private String foo = "false"; public void setFoo(String foo) { this.foo = foo; } public boolean isAuthorized(HttpServletRequest request, HttpServletResponse response, ServletContext application) throws ServletException, IOException { if (foo.equals(request.getParameter("test"))) return true; response.sendError(response.SC_FORBIDDEN); return false; } }

Encryption (SSL)

OpenSSL

The easiest way to add SSL support is to use bin/resin with OpenSSL (not available on Windows.) OpenSSL is the same SSL implementation that Apache's mod_ssl uses.

The OpenSSL configuration has two tags <certificate-file> and <certificate-key-file>. These correspond exactly to mod_ssl's SSLCertificateFile and SSLCertificateKeyFile. So you can use the same certificates (and documentation) from mod_ssl for Resin's bin/resin.

The full set of parameters is in the port configuration.

1. Create a private key for the server:

   unix> openssl genrsa -des3 -out gryffindor.key 1024

2. Create a request for the the certificate to be signed:

   unix> openssl req -new -key gryffindor.key -out gryffindor.csr

3. Send the CSR to a certificate signer (CA). You'll use the instructions for Apache because the certificates are identical. Some commercial signers include:
   • Verisign
   • Thawte Consulting
4. You'll receive a gryffindor.crt file.
5. Configure Resin to use the files:

   ... <http port='443'> <ssl/> <certificate-file>/opt/ssl/keys/gryffindor.crt</certificate-file> <certificate-key-file>/opt/ssl/keys/gryffindor.key</certificate-key-file> <key-store-password>password</key-store-password> </http>

Security Manager

In ISP environments, it's important that each user have restricted permissions to use the server. Normally, the web server will be run as a non-root user so the users can't read system files, but that user will still have read access.

Don't use a security manager if you're not in an ISP environment. There's no need for it and the security manager does slow the server down somewhat.

Adding a Java security manager puts each web-app into a "sandbox" where Java limits their abilities.

The security manager is enabled by adding a security-manager tag in the resin.conf.

Sun's documentation is available at http://java.sun.com/j2se/1.4/docs/guide/security/index.html. In particular, the policy permissions and policy file syntax files are useful.

Each web-app automatically has permissions to read, write and delete any file under the web-app's directory, including WEB-INF. It also has read permission for the classpath, including <classpath> from the <host> and <http-server> contexts.

#
# Permissions allowed for everyone.
#
grant {
  permission java.util.ProperyPermission "*", "read";
  permission java.lang.RuntimePermission "accessClassInPackage.*";
  permission java.lang.SocketPermission "mysql.myhost.com:3306" "connect";
  permission java.io.FilePermission "/opt/resin/xsl/*", "read";
};

#
# Give the system and Resin classes all permissions
#
grant codeBase "file:${resin.home}/lib/-" {
	permission java.security.AllPermission;
};

grant codeBase "file:${java.home}/lib/-" {
	permission java.security.AllPermission;
};

grant codeBase "file:${java.home}/jre/lib/-" {
	permission java.security.AllPermission;
};

#
# Give a specific web-app additional permissions.
#
grant codeBase "file:/opt/web/webapps/ejb/WEB-INF/-" {
	permission java.io.FilePermission "/opt/web/doc/*", "read";
};

Copyright © 1998-2002 Caucho Technology, Inc. All rights reserved. Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc.