001    package hirondelle.web4j.security;
003    import hirondelle.web4j.request.RequestParser;
005    /**
006     Determines if a request has an ownership constraint which needs explicit validation for a user id proxy.
008     <P>This interface addresses the issue of 
009     <a href='http://www.owasp.org/index.php/Top_10_2007-A4'>Insecure Direct Object Reference</a>, which 
010     is an important security issue for web applications. The issue centers around proper enforcement of 
011     <b>data ownership constraints</b>. 
013     <P>Please see the <a href='http://www.web4j.com/UserGuide.jsp#DataOwnershipConstraints'>User Guide</a> for 
014     more information on this important topic.
016     <a name='UntrustedProxyForUserId'></a>
017     <h3>Untrusted Proxy For User Id</h3>
018     An untrusted proxy for the user id is defined here as satisfying these two criteria: 
019     <ul>
020       <li>it's "owned" by a specific user (that is, it has an associated data ownership constraint) 
021       <li>it's open to manipulation by the end user (for example, by simply changing a request parameter)
022     </ul>
024     <P>An untrusted identifier typically appears in a link, or in a form's target URL.
025     This interface is for defining which requests use an untrusted identifier, and which need to enforce a data 
026     ownership constraint in a particular way.
028     <P>Note that, as explained in the <a href='http://www.web4j.com/UserGuide.jsp#DataOwnershipConstraints'>User Guide</a>, 
029     not all data ownership constraints involve an untrusted proxy for the user id - only some do. 
031     <P>The {@link hirondelle.web4j.Controller} processes each request using your application's configured 
032     implementation of this interface. Most applications will likely use the default implementation, 
033     {@link hirondelle.web4j.security.UntrustedProxyForUserIdImpl}. 
034     The <tt>Controller</tt> logic is roughly as follows:
035      <PRE>
036    get the configured implementation of UntrustedProxyForUserId
037    if the current request has an untrusted id {
038      cast the Action to {@link hirondelle.web4j.security.FetchIdentifierOwner}
039      fetch the login name of the user who owns the untrusted id
040      compare it to the login name of the current user  
041      proceed with the Action only if there is a match
042    }</PRE>
044    (Reminder: whenever a user logs in, the login name of the current user is always placed into session scope by the Servlet Container.)
046     <P>Implementations of this interface will typically extract two items from the underlying request, to determine if the 
047     request has an untrusted proxy for the user id :
048     <ul>
049       <li>the 'noun' - identifies <i>what data</i> is being operated on 
050       <li>the 'verb' - what is being <i>done</i> to the data (the operation) 
051     </ul>
053     <P>In some cases, only the noun will be important, since <i>all</i> operations on the data can be restricted to the owner. 
054     In other cases, both the noun <i>and</i> the verb will be needed to determine if there is a data ownership constraint.
055    */
056    public interface UntrustedProxyForUserId {
058      /**
059       Returns <tt>true</tt> only if the given request uses an untrusted proxy for the user id.
060      */
061      boolean usesUntrustedIdentifier(RequestParser aRequestParser);
063    }