resin-security.xtp

RESIN 3.2 最新源码

digestPassword cannot be used to reverse-engineer the original password.</p>

<p>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.  
</p>

<p>Storing digest passwords is so important for security purposes that the
Resin <a href="authentication.xtp">authenticators</a> default to assuming
that the passwords are stored in digest form.</p>

<p>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.</p>

</s2>

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


<p>Some examples are:</p>
<deftable>
<tr><th>Username</th><th>Realm</th><th>Password</th><th>digest
</th></tr><tr><td>root</td><td>resin</td><td>changeme</td><td>j/qGVP4C0T7UixSpKJpTdw==
</td></tr><tr><td>harry</td><td>resin</td><td>quidditch</td><td>uTOZTGaB6pooMDvqvl2Lbg==
</td></tr><tr><td>hpotter</td><td>resin</td><td>quidditch</td><td>x8i6aM+zOwDqqKPRO/vkxg==
</td></tr><tr><td>filch</td><td>resin</td><td>mrsnorris</td><td>KmZIq2RKXAHV4BaoNHfupQ==
</td></tr><tr><td>pince</td><td>resin</td><td>quietplease</td><td>Txpd1jQc/xwhISIqodEjfw==
</td></tr><tr><td>snape</td><td>resin</td><td>potion</td><td>I7HdZr7CTM6hZLlSd2o+CA==
</td></tr><tr><td>mcgonagall</td><td>resin</td><td>quidditch</td><td>4slsTREVeTo0sv5hGkZWag==
</td></tr><tr><td>dmalfoy</td><td>resin</td><td>pureblood</td><td>yI2uN1l97Rv5E6mdRnDFwQ==
</td></tr><tr><td>lmalfoy</td><td>resin</td><td>myself</td><td>sj/yhtU1h4LZPw7/Uy9IVA==
</td></tr></deftable>

<p>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 
<code>digest(username + ":" + realm + ":" + password)</code>, so if the username
changes the resulting digest is different.</p>

</s2>

<s2 title="Calculating a digest">

<p>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.</p>

<!-- a form for calculating an MD5 digest -->
<!--
<jsp:scriptlet>

String digest_user = request.getParameter("digest_user");
String digest_realm = request.getParameter("digest_realm");
String digest_password = request.getParameter("digest_password");
String digest_result = null;

if (digest_realm == null || digest_realm.length() == 0)
  digest_realm = "resin";
pageContext.setAttribute("digest_realm",digest_realm);

if (digest_user != null &amp;&amp; digest_password != null)
{
  String digest_concat = digest_user + ":" + digest_realm + ":" + digest_password;

  com.caucho.http.security.PasswordDigest digest_digest = new com.caucho.http.security.PasswordDigest();

  digest_digest.setRealm(digest_realm);
  digest_result = digest_digest.getPasswordDigest(digest_user, digest_password);

  pageContext.setAttribute("digest_user",digest_user);
  pageContext.setAttribute("digest_password",digest_password);
  pageContext.setAttribute("digest_concat",digest_concat);
  pageContext.setAttribute("digest_result",digest_result);
}

String digest_requestURI = request.getRequestURI();
digest_requestURI = digest_requestURI + "#Calculating-a-digest";

pageContext.setAttribute("digest_requestURI",digest_requestURI);

</jsp:scriptlet>

<form action="${digest_requestURI}">
<jsp:scriptlet>if (digest_result == null || digest_result.length() == 0) {</jsp:scriptlet>
<p>The following form can be used to calculate an MD5-base64 digest:</p>
<jsp:scriptlet>} else {</jsp:scriptlet>
<p>The digest of <var>${digest_concat}</var> is <code><b>${digest_result}</b></code></p>
<jsp:scriptlet>}</jsp:scriptlet>

  <table>
  <tr><td><b>user id:</b>
  </td><td><input name="digest_user" size="50" value="${digest_user}"/>

  </td></tr><tr><td><b>password:</b>
  </td><td><input name="digest_password" size="50" value="${digest_password}"/>

  </td></tr><tr><td><b>realm:</b>
  </td><td><input name="digest_realm" size="50" value="${digest_realm}"/>
  </td></tr><tr><td><input type="submit"/>
  </td></tr></table>
</form>
-->

<p>Unix users can quickly calculate a digest:</p>
<example>
echo -n "user:resin:password" | openssl dgst -md5 -binary | uuencode -m -
</example>

<p>The class <a href="javadoc|com.caucho.http.security.PasswordDigest|"/> can
be used to calculate a digest.</p>

<example title="Calculating a digest - Java example">
  import com.caucho.server.security.PasswordDigest;

  ...

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

  PasswordDigest passwordDigest = PasswordDigest();

  String digest = passwordDigest.getPasswordDigest(username, password, realm);
</example>

<example title="Calculating a digest - PHP example">
  $username = ...;
  $password = ...;
  $realm = "resin";

  $passwordDigest = new Java("com.caucho.server.security.PasswordDigest");

  $digest = $passwordDigest-&gt;getPasswordDigest($username, $password, $realm);
</example>

<p>
The realm for JdbcAuthenticator and XmlAuthenticator defaults to "resin";
the realm can be specified during configuration:
</p>

<example title="Specifying a realm">

&lt;authenticator type='com.caucho.server.security.JdbcAuthenticator'&gt;
  &lt;init&gt;
    &lt;password-digest-realm&gt;hogwarts&lt;/password-digest-realm&gt;

    ...
</example>

</s2>

<s2 title="Using Digest with basic authentication or a form login">

<p>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 <a href="ssl.xtp">SSL</a> connection it will be secure).</p>

</s2>


<s2 title="Using HTTP digest authentication">

<p>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.</p>

<p>When using HTTP digest, Resin will respond to the browser and ask it to
calculcate a digest. The steps involved are:</p>
<ul>
<li>Resin provides the client a realm and some other information 
</li><li>The client obtains a username and password (usually a dialog box with a web browser)
</li><li>The client calculates a digest using the username, realm, pasword, and other information supplied by Resin
</li><li>The client submits the digest to Resin
</li><li>Resin does the same digest calculation as the client did
</li><li>Resin compares the submitted digest and the digest it calculated.  If they match, the user has been authenticated
</li>
</ul>

<p>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.</p>

<p>HTTP digest authentication is enabled with the <a config-tag="auth-method"/> child of the <a config-tag="login-config"/> configuration tag.</p>

<example title="Using HTTP digest authentication">
&lt;login-config&gt;
  &lt;auth-method&gt;DIGEST&lt;/auth-method&gt;
&lt;/login-config&gt;
</example>

</s2>

<s2 title="Disabling the use of password-digest">

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

<example title="Disabling the use of password-digest">
&lt;authenticator&gt;
  &lt;type&gt;com.caucho.server.security.XmlAuthenticator&lt;/type&gt;
  &lt;init&gt;
     &lt;password-digest&gt;none&lt;/password-digest&gt;
     &lt;user&gt;harry:quidditch:user&lt;/user&gt;
  &lt;/init&gt;
&lt;/authenticator&gt;
</example>

</s2>

<s2 title="Compatibility">

<p>Authenticators are not defined by the 
<a href="http://www.jcp.org/en/jsr/detail?id=154">Servlet Specification</a>, 
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 <a href="#Using-HTTP-digest-authentication">HTTP digest
authentication</a>.</p>

<p>The use of <code>&lt;auth-method&gt;DIGEST&lt;auth-method&gt;</code> is
defined in the Servlet Specification and implemented in most
application servers.</p>

</s2>
</s1>

<s1 title="Single Signon" version="Resin 3.0.0">

<p>"Single signon" refers to allowing for a single login for more
than one context, for example, logging in to all web-apps in a server at once.
You can implement single signon by configuring the authenticator in
the proper environment: web-app, host, or server.  The login will last for
all the web-apps in that environment.</p>

<p>The authenticator is a resource which is shared across its <a href="env-tags.xtp">environment</a>.
For example, to configure the XML authenticator
for all web-apps in foo.com, you might configure as follows:</p>

<example title="Single Signon for foo.com">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="app-tier&gt;
    &lt;http port="8080"/&gt;

    &lt;host id="foo.com"&gt;
      &lt;root-directory&gt;/opt/foo.com&lt;/root-directory&gt;

      &lt;authenticator type="com.caucho.server.security.XmlAuthenticator"&gt;
        &lt;init&gt;
          &lt;!-- password: quidditch --&gt;
          &lt;user&gt;harry:uTOZTGaB6pooMDvqvl2LBu:user,gryffindor&lt;/user&gt;
          &lt;!-- password: pureblood --&gt;
          &lt;user&gt;dmalfoy:yI2uN1l97Rv5E6mdRnDFDB:user,slytherin&lt;/user&gt;
        &lt;/init&gt;
      &lt;/authenticator&gt;

      &lt;web-app-deploy path="webapps"/&gt;
    &lt;/host&gt;
  &lt;/cluster&gt;
&lt;/resin&gt;
</example>

<p>Any .war in the webapps directory will share the same signon for the
host.  You will still need to implement a
<a href="webapp-tags.xtp#login-config">login-config</a> for each web-app.</p>

<p>
The value of <a config-tag="reuse-session-id">reuse-session-id</a> must be <code>true</code>
for single signon.
</p>


<s2 title="Single signon for virtual hosts">
<p>
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.
</p>

<p>
The <a href="#authenticator">authenticator</a> is placed at the cluster level
so that it is common to all virtual hosts.  The
<a href="webapp-tags.xtp#session-config">cookie-domain</a> is
placed in a <a href="webapp-tags.xtp#web-app-default">web-app-default</a> at
the cluster level so that it is applied as the default for all webapps in all
virtual hosts.
</p>

<example title="Single Signon for gryffindor.hogwarts.com and slytherin.hogwarts.com">
&lt;resin xmlns="http://caucho.com/ns/resin"&gt;
  &lt;cluster id="app-tier&gt;
    &lt;http port="8080"/&gt;

    &lt;authenticator type="com.caucho.server.security.XmlAuthenticator"&gt;
      ...
    &lt;/authenticator&gt;

    &lt;web-app-default&gt;
      &lt;session-config&gt;
        &lt;enable-url-rewriting&gt;false&lt;/enable-url-rewriting&gt;
        &lt;cookie-domain&gt;.hogwarts.com&lt;/cookie-domain&gt;
      &lt;/session-config&gt;
    &lt;/web-app-default&gt;


    &lt;host id="gryffindor.hogwarts.com"&gt;
      ...
    &lt;/host&gt;

    &lt;host id="slytherin.hogwarts.com"&gt;
      ...
    &lt;/host&gt;
  &lt;/server&gt;
&lt;/resin&gt;
</example>

<p>
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.
</p>
</s2>

</s1>

<s1 title="Custom Login">
<p>The Login is primarily responsible for extracting the credentials
from the request (typically username and password) and passing those
to the ServletAuthenticator.</p>

<p>The Servlet API calls the Login in two contexts: directly from
<code>ServletRequest.getUserPrincipal()</code>, 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.)</p>

<p>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.</p>

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

<example>
&lt;login-config type="test.CustomLogin"&gt;
  &lt;init&gt;
    &lt;foo&gt;bar&lt;/bar&gt;
  &lt;/init&gt;
&lt;/login-config&gt;
</example>

</s1>

<s1 title="Security Constraints">

<s2 title="security-constraint" type="defun">
<parents>web-app</parents>

<p>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.</p>

<p>Security constraints can also be custom classes.</p>