Samples

Local Access Authorization

If you want an administration page to be accessible only from a local network, you can use the <resin:Allow> and <resin:IfNetwork> tags together to ensure only local requests are authorized.

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <resin:Allow url-pattern="/admin/*">
    <resin:IfNetwork>
      <resin:value>127.0.0.1</resin:value>
      <resin:value>192.168.0.0/16</resin:value>
    </resin:IfNetwork>
  </resin:Allow>

</web-app>

• <resin:Allow> creates an allow authorization rule. If all the contents match, the pattern is allowed.
• <resin:IfNetwork> matches a set of IP addresses using standard network notation. If any address matches, <resin:IfNetwork> is true.

Because the local access protection only involves authorization, it's a shorter example than cases requiring a login.

Hide URLs from browsing

In cases like WEB-INF, when you want to protect files from any browsing, local or not, you can use a single <resin:Deny> authorization to prevent access.

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <resin:Deny>
     <resin:url-pattern>/hidden/*</resin:url-pattern>
     <resin:url-pattern>*.hidden</resin:url-pattern>
  </resin:Deny>

</web-app>

XML Authentication

If a section of a web-site needs basic password protection, you can use HTTP Basic authentication, an <resin:IfRule> authorization and an XML authenticator as follows.

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">

  <resin:Allow url-pattern="/secure/*">
    <resin:IfUserInRole role="*"/>
  </resin:Allow>

  <resin:FormLogin login-page="/login.jsp"/>

  <resin:XmlAuthenticator>
     <resin:user name="harry" password="uTOZTGaB6pooMDvqvl2Lbg==" group="user"/>
  </resin:XmlAuthenticator>

</web-app>

For security, the password is secured with an MD5 hash, because plaintext passwords aren't very secure at all. The easiest way to generate the hash is with a short PHP script:

<?php

echo base64_encode(md5("harry:resin:quidditch", true)) . "\n";

• <resin:Allow> protects a section of the web-app, i.e. providing an authorization context.
• <url-pattern> matches the URLs to be protected
• <resin:IfUserInRole> protects the web-app through login (as opposed to by IP address or by SSL)
• <resin:FormLogin> specifies the form login method
• <resin:XmlAuthenticator> defines the login users and passwords. The XML authenticator specifies a simple XML file for user definition.

Overview

Management

Authentication

DatabaseAuthenticator

The DatabaseAuthenticator (com.caucho.security.DatabaseAuthenticator) asks a backend database for the password matching the user's name. It uses the DataSource specified by the data-source option. data-source refers to a DataSource configured with database.

The following are the attributes for the DatabaseAuthenticator:

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  ...

  <!-- DatabaseAuthenticator -->
  <resin:DatabaseAuthenticator'>
    <resin:data-source>test</resin:data-source>
    
    <resin:password-query>
      SELECT password FROM LOGIN WHERE username=?
    </resin:password-query>
    
    <resin:cookie-auth-query>
      SELECT username FROM LOGIN WHERE cookie=?
    </resin:cookie-auth-query>
    
    <resin:cookie-auth-update>
      UPDATE LOGIN SET cookie=? WHERE username=?
    </resin:cookie-auth-update>
    
    <resin:role-query>
      SELECT role FROM LOGIN WHERE username=?
    </resin:role-query>
  </resin:DatabaseAuthenticator>

  <resin:BasicLogin/>

  <resin:Allow url-pattern="/users-only/*">
     <resin:IfUserInRole role="user"/>
  </resin:Allow>

  ...

</web-app>

JaasAuthenticator

The JaasAuthenticator (com.caucho.security.JaasAuthenticator) uses a JAAS LoginModule for authentication. The JaasAuthenticator is an adapter that provides the ability to use the large number of JAAS LoginModule's included in the JDK for authentication purposes.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:JaasAuthenticator>
    <resin:login-module>com.sun.security.auth.module.Krb5LoginModule</resin:login-module>
    <resin:init-param>
      <debug>true</debug>
    </resin:init-param>
  </resin:JaasAuthenticator>

</web-app>

import java.util.*;

import javax.security.auth.*;
import javax.security.auth.spi.*;
import javax.security.auth.callback.*;
import javax.security.auth.login.*;

public class TestLoginModule implements javax.security.auth.spi.LoginModule {
  private Subject _subject;
  private CallbackHandler _handler;
  private Map _state;
 
  private String _userName;
  private String _password;

  public void initialize(Subject subject,
                         CallbackHandler handler,
                         Map sharedState,
                         Map options)
   {
     _subject = subject;
     _handler = handler;
     _state = sharedState;

     _userName = (String) _options.get("user");
     _password = (String) _options.get("password");
   }

   public boolean login()
     throws LoginException
   {
     NameCallback name = new NameCallback("");
     PasswordCallback password = new PasswordCallback("", false);
 
     _handler.handle(new Callback[] { name, password });

     if (_userName.equals(name.getName()) && 
         _password.equals(password.getPassword()) {
         _subject.getPrincipals().add(new TestPrincipal(_userName));
       return true;
     }
     else
       return false;
   }

   public boolean abort()
   {
     return true;
   }

   public boolean commit()
   {
     return _subject.getPrincipals().size() > 0;
   }

   public boolean logout()
   {
      return true;
   }
}

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">

  <resin:JaasAuthenticator>
    <resin:login-module>example.TestModule</resin:login-module>
    
    <resin:init-param>
      <user>Harry</user>
      <password>quidditch</password>
    </resin:init-param>
  </resin:JaasAuthenticator>
</web-app>

LdapAuthenticator

The LdapAuthenticator (com.caucho.security.LdapAuthenticator) uses jndi to contact an LDAP (or Active Directory) server for authentication purposes.

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  ...

  <resin:LdapAuthenticator password-digest="none">
    <resin:url>ldap://localhost:389</resin:url>
    <resin:dn-suffix>dc=hogwarts,dc=com</resin:dn-suffix>
  </resin:LdapAuthenticator>

  ...

</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">
	    
  <resin:LdapAuthenticator password-digest="none">
    <resin:jndi-env java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"/>
    <resin:jndi-env java.naming.provider.url="ldap://localhost:389"/>

    <resin:dn-suffix>dc=hogwarts,dc=com</dn-suffix>
  </resin:LdapAuthenticator>

<web-app>  

PropertiesAuthenticator

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <resin:PropertiesAuthenticator password-digest="none">
     harry=quidditch,user,admin
     draco=mudblood,disabled,user
  </resin:PropertiesAuthenticator>

</web-app>

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"

  <resin:PropertiesAuthenticator path="WEB-INF/users.properties"/>

</web-app>

harry=/Tj/54ylCloUeMi2YQIVCQ===,user,admin

XmlAuthenticator

<web-app xmlns="http://caucho.com/ns/resin"
        xmlns:resin="urn:java:com.caucho.resin">

  <resin:XmlAuthenticator password-digest="none">
     <resin:user name="harry" password="quidditch"/>
  </resin:XmlAuthenticator>

</web-app>

<web-app xmlns="http://caucho.com/ns/resin">

  <resin:XmlAuthenticator path="WEB-INF/users.xml"/>

</web-app>

<users>
  <user name="harry password="/Tj/54ylCloUeMi2YQIVCQ===" roles="user,admin"/>
<users>

XmlAuthenticator

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

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

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:XmlAuthenticator password-digest="none">
    <resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/>
    <resin:user name="Draco Malfoy" password="pureblood" group=":user,slytherin"/>
  </resin:XmlAuthenticator>

</web-app>  

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.

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

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

Sites should use password-digest to protect the passwords.

custom Authenticator

<web-app xmlns="http://caucho.com/ns/resin"
        xmlns:foo="urn:java:com.caucho.foo">

  <foo:MyAuthenticator>
    <foo:foo>bar</foo:foo>
  </foo:MyAuthenticator>

</web-app>

package com.foo;

import com.caucho.security.AbstractAuthenticator;
import com.caucho.security.PasswordUser;

public class MyAuthenticator extends AbstractAuthenticator {
  private PasswordUser _user;

  public MyAuthenticator()
  {
    _user = new PasswordUser("harry", "quidditch",
                             new String[] { "user" });
  }

  public PasswordUser getUser(String userName)
  {
    if (userName.equals(_user.getName()))
      return _user;
    else
      return null;
  }
}

Digest passwords

Digest protects passwords

Digest passwords enable an application to avoid storing and even transmitting the password in a form that someone can read.

A digest of a cleartext password is calculated when it is passed through a one-way function that consistently produces another series of characters, digestPassword = digester(username + ":" + realm + ":" cleartextPassword). The function is "one-way" because the digestPassword cannot be used to reverse-engineer the original password.

For example, Resin uses md5 and base64 as the default. You can create the hash with a simple PHP script like:

<?php

echo base64_encode(md5("harry:resin:quidditch")) . "\n";

Digest passwords can be used in two places: storage and transmission. Digest passwords in storage means that the password is stored in a digested form, for example in a database or in a file. Digest passwords in transmission means that the client (usually a web browser) creates the digest and submits the digest password to the web server.

Storing digest passwords is so important for security purposes that the Resin authenticators default to assuming that the passwords are stored in digest form.

The important advantage is that a user's cleartext password is not as easily compromised. Since the password they use (the "cleartext" password) is not stored a malicious user cannot determine the password by gaining access to the database or other backend storage for the passwords.

MD5 digest

Resin's authenticators use "MD5-base64" and a realm "resin" to digest passwords by default. MD5 indicates that the MD5 algorithm is used. base64 is an encoding format to apply to the binary result of MD5.

Some examples are:

In the above example the digest of "harry/quidditch" is different than the digest of "hpotter/quidditch" because even though the password is the same, the username has changed. The digest is calculated with digest(username + ":" + realm + ":" + password), so if the username changes the resulting digest is different.

Calculating a digest

Of course, storing the digest password is a bit more work. When the user registers, the application needs to compute the digest to store it.

<?php

  $username = "harry";
  $password = "quidditch";
  $realm = "resin";

  $digest = base64_encode(md5("$username:$realm:$password", true));
?>  

Unix users can quickly calculate a digest:

echo -n "user:resin:password" | openssl dgst -md5 -binary | uuencode -m -

The class com.caucho.security.PasswordDigest can be used to calculate a digest.

  import com.caucho.security.PasswordDigest;

  ...

  String username = ...;
  String password = ...;
  String realm = "resin";

  PasswordDigest passwordDigest = PasswordDigest();

  String digest = passwordDigest.getPasswordDigest(username, password, realm);

The realm for DatabaseAuthenticator and XmlAuthenticator defaults to "resin"; the realm can be specified during configuration:

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <resin:DatabaseAuthenticator>
    <resin:password-digest-realm>hogwarts</resin:password-digest-realm>
    ...
  </resin:DatabaseAuthenticator>
  
</web-app>  

Using Digest with basic authentication or a form login

When using the form login method or the HTTP basic authentication login method, the password submitted is in cleartext. The Resin authenticator will digest the password before comparing it to the value retrieved from storage. The message is transmitted in cleartext but is stored as a digest. This method provides only half of the protection - the password is not protected in transmission (although if the form submit is being done over an SSL connection it will be secure).

Using HTTP digest authentication

The HTTP protocol includes a method to indicate to the client that it should make a digest using the password. The client submits a digest to Resin instead of submitting a cleartext password. HTTP digest authentication protects the password in transmission.

When using HTTP digest, Resin will respond to the browser and ask it to calculcate a digest. The steps involved are:

• Resin provides the client a realm and some other information
• The client obtains a username and password (usually a dialog box with a web browser)
• The client calculates a digest using the username, realm, pasword, and other information supplied by Resin
• The client submits the digest to Resin
• Resin does the same digest calculation as the client did
• Resin compares the submitted digest and the digest it calculated. If they match, the user has been authenticated

The advantage of this method is that the cleartext password is protected in transmission, it cannot be determined from the digest that is submitted by the client to the server.

HTTP digest authentication is enabled with the auth-method child of the login-config configuration tag.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:DigestLogin/>

</web-app>

Disabling the use of password-digest

Although it is not advised, Resin's authenticators can be configured to use passwords that are not in digest form.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:XmlAuthenticator</type>
    <resin:password-digest>none</resin:password-digest>
    
    <resin:user name="harry" password="quidditch" group="user"/>
  </resin:XmlAuthenticator>
  
</web-app>

Compatibility

Authenticators are not defined by the Servlet Specification, so the ability to use passwords stored as a digest depends upon the implementation of the Authenticator that the application server provides. MD5-base64 is the most common form of digest, because it is the default in HTTP digest authentication.

The use of <auth-method>DIGEST<auth-method> is defined in the Servlet Specification and implemented in most application servers.

Single Signon

Single signon for virtual hosts

The basis for establishing client identity is the JSESSIONID cookie. If single signon is desired for virtual hosts, Resin must be configured to notify the browser of the proper domain name for the cookie so that the same JSESSIONID cookie is submitted by the browser to each virtual host.

The authenticator is placed at the cluster level so that it is common to all virtual hosts. The cookie-domain is placed in a web-app-default at the cluster level so that it is applied as the default for all webapps in all virtual hosts.

<resin xmlns="http://caucho.com/ns/resin"
        xmlns:resin="urn:java:com.caucho.resin">
	
  <cluster id="app-tier>
    <http port="8080"/>

    <resin:XmlAuthenticator">
      <user name="Harry" password="..."/>
    </resin:XmlAuthenticator>

    <web-app-default>
      <session-config>
        <cookie-domain>.hogwarts.com</cookie-domain>
      </session-config>
    </web-app-default>


    <host id="gryffindor.hogwarts.com">
      ...
    </host>

    <host id="slytherin.hogwarts.com">
      ...
    </host>
  </cluster>
</resin>

Because of the way that browsers are restricted by the HTTP specification from submitting cookies to servers, it is not possible to have a single signon for virtual hosts that do not share some portion of their domain name. For example, "gryffindor.com" and "slytherin.com" cannot share a common authentication.

Login

BasicLogin

Configures HTTP basic login, which can be convenient for a quick protection of internal pages or administration when writing a form isn't necessary.

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <resin:BasicLogin/>

  <resin:Allow url-pattern="/foo/*">
     <resin:IfUserInRole role="user"/>
  </resin:Allow>

  <resin:XmlAuthenticator>
     ...
  </resin:XmlAuthenticator>
  
</web-app>  

FormLogin

Configures authentication for forms. The login form has specific parameters that the servlet engine's login form processing understands. If the login succeeds, the user will see the original page. If it fails, she will see the error page.

The form itself must have the action j_security_check. It must also have the parameters j_username and j_password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. j_use_cookie_auth allows Resin to send a persistent cookie to the user to make following login easier.

j_use_cookie_auth gives control to the user whether to generate a persistent cookie. It lets you implement the "remember me" button. By default, the authentication only lasts for a single session.

The following is an example of a servlet-standard login page:

<form action='j_security_check' method='POST'>
<table>
<tr><td>User:<td><input name='j_username'>
<tr><td>Password:<td><input name='j_password'>
<tr><td colspan=2>hint: the password is 'quidditch'
<tr><td><input type=submit>
</table>
</form>

Custom Login

The Login is primarily responsible for extracting the credentials from the request (typically username and password) and passing those to the ServletAuthenticator.

The Servlet API calls the Login in two contexts: directly from ServletRequest.getUserPrincipal(), and during security checking. When called from the Servlet API, the login class can't change the response. In other words, if an application calls getUserPrincipal(), the Login class can't return a forbidden error page. When the servlet engine calls authenticate(), the login class can return an error page (or forward internally.)

Normally, Login implementations will defer the actual authentication to a ServletAuthenticator class. That way, both "basic" and "form" login can use the same JdbcAuthenticator. Some applications, like SSL client certificate login, may want to combine the Login and authentication into one class.

Login instances are configured through bean introspection. Adding a public setFoo(String foo) method will be configured with the following login-config:

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">
          xmlns:foo="urn:java:com.foo">
     
  <foo:CustomLogin>
    <foo:foo>bar</foo:foo>
  </foo:CustomLogin>

  <resin:XmlAuthenticator>
    ...
  </resin:XmlAuthenticator>

</web-app>  

Authorization

resin:Allow

Selects protected areas of the web site. Sites using authentication as an optional personalization feature will typically not use any security constraints. Sites using authentication to limit access to certain sections of the website to certain users will use security constraints.

Security constraints can also be custom classes.

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin">
	 
  <resin:IfAllow url-pattern="/*">
    <resin:IfUserInRole role="*"/>
  </resin:IfAllow>

</web-app>

resin:IfNetwork

Allow or deny requests based on the ip address of the client. ip-constraint is very useful for protecting administration resources to an internal network. It can also be useful for denying service to known problem ip's.

<web-app xmlns="http://caucho.com/ns/resin"
        xmlns:resin="urn:java:com.caucho.resin">
	
  <resin:Allow url-pattern="/admin/*">
    <resin:IfAddress name="192.168.17.0/24"/>
  </resin:Allow>
  
</web-app>

The /24 in the ip 192.168.17.0/24 means that the first 24 bits of the ip are matched - any ip address that begins with 192.168.17. will match. The usage of /bits is optional.

<web-app xmlns="http://caucho.com/ns/resin"
          xmlns:resin="urn:java:com.caucho.resin">

  <resin:Deny>
    <resin:IfNetwork>
       <resin:value>205.11.12.3</resin:value>
       <resin:value>213.43.62.45</resin:value>
       <resin:value>123.4.45.6</resin:value>
       <resin:value>233.15.25.35</resin:value>
       <resin:value>233.14.87.12</resin:value>
    </resin:IfNetwork>
  </resin:Deny>
  
</web-app>

Be careful with deny - some ISP's (like AOL) use proxies and the ip of many different users may appear to be the same ip to your server.

If only deny is used, then all ip's are allowed if they do not match a deny. If only allow is used, then an ip is denied unless it matches an allow. If both are used, then the ip must match both an allow and a deny

resin:IfUserInRole

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

<web-app xmlns="http://caucho.com/ns/resin"
        xmlns:resin="urn:java:com.caucho.resin">
	
  <resin:Allow url-pattern="/webdav/*">
    <resin:IfUserInRole role='webdav'/>
  </resin:Allow>
  
</web-app>

resin:IfSecure

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

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
	 
  <resin:Allow>
    <resin:IfSecure/>
  </resin:Allow>
  
</web-app>

The default behaviour is for Resin to rewrite any url that starts with "http:" by replacing the "http:" part with "https:", and then send redirect to the browser.

If the default rewriting of the host is not appropriate, you can set the secure-host-name for the host:

<resin xmlns="http://caucho.com/ns/resin">
<cluster id="app-tier">
  ...
  
  <host id="...">
    <secure-host-name>https://hogwarts.com</secure-host-name>
    ...
</resin> 

constraint

Any custom class that extends com.caucho.security.RequestPredicate can be used as an <IfXXX> rule. Just create the class and instantiate it directly:

<web-app xmlns="http://caucho.com/ns/resin"
         xmlns:resin="urn:java:com.caucho.resin"
         xmlns:foo="urn:java:com.foo"

 <resin:Allow url-pattern="/safe/*"
    <foo:IfMyTest value="value"/>
 </resin:Allow url-pattern="/safe/*"

</web-app>

package com.foo;

import javax.servlet.http.HttpServletRequest;
import com.caucho.security.ServletRequestPredicate;

public class IfMyTest extends ServletRequestPredicate {
  private String _value;

  public void setValue(String value)
  {
    _value = value;
  }

  public boolean isMatch(HttpServletRequest request)
  {
    return _value.equals(request.getHeader("Foo"));
  }
}

Protecting static files from viewing by anyone

Place files in WEB-INF

Place files in WEB-INF or a subdirectory of WEB-INF. Any files in WEB-INF or it's subdirectories will automatically be protected from viewing.

resin:Deny

Use a security constraint that requires a role that nobody will ever have.

<web-app xmlns="http://caucho.com/ns/resin"
        xmlns:resin="urn:java:com.caucho.resin">
  ...
  <!-- protect all .properties files -->
  <resin:Deny url-pattern="*.properties"/>

  <!-- protect the config/ subdirectory -->
  <resin:Deny url-pattern="/config/*"/>
  ...
</web-app>

What SSL provides

Encryption

SSL provides encryption of the data traffic betweeen a client and a server. When the traffic is encrypted, an interception of that traffic will not reveal the contents because they have been encrypted - it will be unusable nonsense.

SSL uses public key cryptography. Public key cryptography is based upon a pair of keys, the public key and the private key. The public key is used to encrypt the data. Only the corresponding private key can successfully decrypt the data.

For example, when a browser connects to Resin, Resin provides the browser a public key. The browser uses the public key to encrypt the data, and Resin uses the private key to decrypt the data. For this reason, it is important that you never allow anyone access to the private key, if the private key is obtained by someone then they can use it to decrypt the data traffic.

Encryption is arguably the more important of the security meausures that SSL provides.

Server Authentication

SSL also provides the ability for a client to verify the identity of a server. This is used to protect against identity theft, where for example a malicious person imitates your server or redirects client traffic to a different server while pretending to be you.

Server authentication uses the signature aspect of public key cryptography. The private key is used to sign messages, and the public key is used to verify the signature. With SSL, the validity of signatures depends upon signing authorities. Signing authorites (also called certificate authorities) are companies who have generated public keys that are included with browser software. The browser knows it can trust the signing authority, and the signing authority signs your SSL certificate, putting its stamp of approval on the information in your certificate.

For example, after you generate your public and private key, you then generate a signing request and send it to a signing authority. This signing request contains information about your identity, this identity information is confirmed by the signing authority and ultimately displayed to the user of the browser. The signing authority validates the identity information you have provided and uses their private key to sign, and then returns a certificate to you. This certificate contains the identity information and your public key, verified by the signing authority, and is provided to the browser. Since the browser has the public key of the signing authority, it can recognize the signature and know that the identity information has been provided by someone that can be trusted.

OpenSSL

Linking to the OpenSSL Libraries on Unix

On Unix systems, Resin's libexec/libresinssl.so JNI library supports SSL using the OpenSSL libraries. Although the ./configure script will detect many configurations, you can specify the openssl location directly:

resin> ./configure --with-openssl=/usr/local/ssl

Obtaining the OpenSSL Libraries on Windows

On Windows systems, the resinssl.dll includes JNI code to use OpenSSL libraries (it was in resin.dll in versions before 3.0). All you need to do is to obtain an OpenSSL binary distribution and install it.

Resin on Windows 32 is compiled against the Win32 binary, you can obtain an installation package http://www.slproweb.com (Shining Light Productions).

Resin on Windows 64 is compiled against a Win64 binary, you can obtain an installation package Dean Lee: /dev/blog.

Once you have run the installation package, you can copy the necessary dll libraries into $RESIN_HOME:

C:\> cd %RESIN_HOME%
C:\resin-3.0> copy "C:\Program Files\GnuWin32\bin\libssl32.dll" .\libssl32.dll
C:\resin-3.0> copy "C:\Program Files\GnuWin32\bin\libeay32.dll" .\libeay32.dll

Preparing to use OpenSSL for making keys

You can make a keys/ subdirectory of $RESIN_HOME to do your work from and as a place to store your generated keys.

unix> cd $RESIN_HOME
unix> mkdir keys
unix> cd keys

win> cd %RESIN_HOME%
win> mkdir keys
win> cd keys

Using OpenSSL requires a configuration file. Unix users might find the default configuration file in /usr/ssl/openssl.cnf or /usr/share/ssl/openssl.cnf. Windows users may not have received one with their package.

Either way, it can be valuable to make your own openssl.cnf that is used just for generating the keys to use with Resin. You can use the following as a template for a file $RESIN_HOME/keys/openssl.cnf. You may want to fill in the _default values so you don't have to type them in every time.

[ req ]
 default_bits            = 1024
 distinguished_name      = req_distinguished_name

[ req_distinguished_name ]
 C                      = 2 letter Country Code, for example US
 C_default              =
 ST                     = State or Province
 ST_default             =
 L                      = City
 L_default              =
 O                      = Organization Name
 O_default              =
 OU                     = Organizational Unit Name, for example 'Marketing'
 OU_default             =
 CN                     = your domain name, for example www.hogwarts.com
 CN_default             =
 emailAddress           = an email address
 emailAddress_default   =

Creating a private key

Create a private key for the server. You will be asked for a password - don't forget it! You will need this password anytime you want to do anything with this private key. But don't pick something you need to keep secret, you will need to put this password in the Resin configuration file.

unix> openssl genrsa -des3 -out gryffindor.key 1024
win>  "C:\Program Files\GnuWin32\bin\openssl.exe" \
         genrsa -des3 -out gryffindor.key 1024

Creating a certificate

OpenSSL works by having a signed public key that corresponds to your private key. This signed public key is called a certificate. A certificate is what is sent to the browser.

You can create a self-signed certificate, or get a certificate that is signed by a certificate signer (CA).

unix> openssl req -config ./openssl.cnf -new -key gryffindor.key \
        -x509 -out gryffindor.crt
win> "C:\Program Files\GnuWin32\bin\openssl.exe" req -config ./openssl.cnf \
         -new -key gryffindor.key -x509 -out gryffindor.crt

unix> openssl req -new -config ./openssl.cnf -key gryffindor.key \
      -out gryffindor.csr
win> "C:\Program Files\GnuWin32\bin\openssl.exe" req -new \
      -config ./openssl.cnf  -key gryffindor.key -out gryffindor.csr

resin.xml - Configuring Resin to use your private key and certificate

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.

The full set of parameters is in the port configuration.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="http-tier">

  <server id="a" address="192.168.1.12">
    <http port="443">
      <openssl>
        <certificate-file>keys/gryffindor.crt</certificate-file>
        <certificate-key-file>keys/gryffindor.key</certificate-key-file>
        <password>my-password</password>
      </openssl>
   </http>
  </server>

  ...
</resin>  

Testing

Secure? <%= request.isSecure() %>

unix$ openssl s_client -connect www.some.host:443 -prexit

Certificate Chains

A certificate chain is used when the signing authority is not an authority trusted by the browser. In this case, the signing authority uses a certificate which is in turn signed by a trusted authority, giving a chain of [your certificate] <--- signed by ---- [untrusted signer] <---- signed by ---- [trusted signer].

The Resin config parameter certificate-chain-file is used to specify a certificate chain. It is used to reference a file that is a concatenation of:

1. your certificate file
2. the intermediate (untrusted) certificate
3. the root (trusted) certificate.

The certificates must be in that order, and must be in PEM format.

$ cat your_domain.crt ComodoSecurityServicesCA.crt GTECyberTrustRoot.crt > chain.txt

<http port="443">
  <openssl>
    <certificate-key-file>keys/your_domain.key</certificate-key-file>
    <certificate-file>keys/your_domain.crt</certificate-file>        
    <certificate-chain-file>keys/chain.txt</certificate-chain-file>
    <password>test123</password>
  </openssl>
</http>

JSSE

Install JSSE from Sun

This section gives a quick guide to installing a test SSL configuration using Sun's JSSE. It avoids as many complications as possible and uses Sun's keytool to create a server certificate.

Resin's SSL support is provided by Sun's JSSE. Because of export restrictions, patents, etc, you'll need to download the JSSE distribution from Sun or get a commercial JSSE implementation.

More complete JSSE installation instructions for JSSE are at http://java.sun.com/products/jsse/install.html.

1. First download Sun's JSSE.
2. Uncompress and extract the downloaded file.
3. Install the JSSE jar files: jsse.jar, jnet.jar, and jcert.jar. You can either put them into the CLASSPATH or you can put them into $JAVA_HOME/jre/lib/ext. Since you will use "keytool" with the new jars, you need to make them visible to keytool. Just adding them to resin/lib is not enough.
4. Register the JSSE provider (com.sun.net.ssl.internal.ssl.Provider). Modify $JAVA_HOME/jre/lib/security/java.security so it contains something like:

   security.provider.1=sun.security.provider.Sun
   security.provider.2=com.sun.net.ssl.internal.ssl.Provider
   

   Adding the JSSE provider allows "keytool" to create a key using the RSA algorithm.

Create a test server certificate

The server certificate is the core of SSL. It will identify your server and contain the secret key to make encryption work.

• Sun's keytool
• A self-signed certificate using open_ssl
• A test certificate from Thawte
• A production certificate from one of the certificate authorities (Verisign, Thawte, etc)

In this case, we're using Sun's keytool to generate the server certificate. Here's how:

resin1.2.b2> mkdir keys
resin1.2.b2> keytool -genkey -keyalg RSA -keystore keys/server.keystore
Enter keystore password:  changeit
What is your first and last name?
  [Unknown]:  www.caucho.com
What is the name of your organizational unit?
  [Unknown]:  Resin Engineering
What is the name of your organization?
  [Unknown]:  Caucho Technology, Inc.
What is the name of your City or Locality?
  [Unknown]:  San Francisco
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  US
Is <CN=www.caucho.com, OU=Resin Engineering,
  O="Caucho Technology, Inc.", L=San Francisco, ST=California, C=US> correct?
  [no]:  yes

Enter key password for <mykey>
        (RETURN if same as keystore password):  changeit

Currently, the key password and the keystore password must be the same.

resin.xml

The Resin SSL configuration extends the http configuration with a few new elements.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="">

    <server-default>
    
    <http port="8443">
     <jsse-ssl>
       <key-store-type>jks</key-store-type>
       <key-store-file>keys/server.keystore</key-store-file>
       <password>changeit</password>
     </jsse-ssl>
    </http>

    </server-default>
    ...

  </cluster>
</resin>

Testing JSSE

With the above configuration, you can test SSL with https://localhost:8443. A quick test is the following JSP.

Secure? <%= request.isSecure() %>