001    package hirondelle.web4j.security;
002    
003    import hirondelle.web4j.request.RequestParser;
004    
005    /**
006     Determines if a request has an ownership constraint which needs explicit validation for a user id proxy.
007     
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>. 
012     
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.
015      
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>
023     
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.
027     
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. 
030     
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>
043    
044    (Reminder: whenever a user logs in, the login name of the current user is always placed into session scope by the Servlet Container.)
045     
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>
052     
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 {
057      
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);
062    
063    }