001    package hirondelle.web4j.security;
002    
003    /**
004     Characters accepted by the {@link SafeText} class.
005     
006     <P>This interface exists because it is important for a web application 
007     to defend strongly against Cross-Site Scripting (XSS) -- likely the single most  
008     prevalent form of attack on the web.
009     
010     <P>As principal line of defense against XSS, WEB4J provides the {@link SafeText} class, 
011     to be used to model all free form user input. <tt>SafeText</tt> escapes a large number of 
012     special characters. If they are contained in a {@link SafeText} object, any scripts 
013     that depend on one or more of these special characters will very likely be 
014     rendered unexecutable.
015     
016     <P>As a second line of defense, this interface permits you to specify exactly which characters 
017     should be accepted by the {@link SafeText} constructor. This is often called a  
018     'white list' of acceptable characters.
019     
020     <P>The default implementation of this interface 
021     ({@link hirondelle.web4j.security.PermittedCharactersImpl}) 
022     should be useful for a wide number of applications.
023    */
024    public interface PermittedCharacters {
025      
026      /**
027       Return <tt>true</tt> only if the given character is to be permitted by {@link SafeText}.
028       
029       @param aCodePoint character in the text being passed to the {@link SafeText} constructor.
030       The text, in turn, may come from user input, or from the database. For more information on 
031       code points, please see {@link Character}. (Code points are used insteard of char since they are 
032       more general than char.)
033      */
034      public boolean isPermitted(int aCodePoint);
035    
036    }