Skip to content

Issue 705 - Additional Javdoc for DefaultValidator class #706

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 24, 2022
Merged

Issue 705 - Additional Javdoc for DefaultValidator class #706

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc20281
Enhance DefaultValidator class-level javadoc as per issue $705.
kwwall May 22, 2022
5963e1d
Enhance the javadoc for the 2 CTORs.
kwwall May 22, 2022
4172608
Address PR #706 comments by @stevebosman-oc.
kwwall May 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 81 additions & 14 deletions src/main/java/org/owasp/esapi/reference/DefaultValidator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,17 +54,46 @@
import org.owasp.esapi.reference.validation.StringValidationRule;

/**
* Reference implementation of the Validator interface. This implementation
* relies on the ESAPI Encoder, Java Pattern (regex), Date,
* Reference implementation of the {@code Validator} interface. This implementation
* relies on the ESAPI {@code Encoder}, {@link java.util.regex.Pattern},
* {@link java.util.Date},
* and several other classes to provide basic validation functions. This library
* has a heavy emphasis on whitelist validation and canonicalization.
* has a heavy emphasis on allow-list validation and canonicalization.
* <p>
* <b>A Note about Canonicalization</b>:
* The behaviors of objects of this class are largely driven by how the
* associated {@code Encoder} is created and passed to one of this
* class' constructors. Specifically, what {@link org.owasp.esapi.codecs.Codec}
* types are referenced by the {@link org.owasp.esapi.Encoder} instance
* associated with this particular {@code DefaultValidator} instance. In places
* where the default {@code Encoder} instance is used, the behavior is driven
* by three ESAPI properties as defined in the <b>ESAPI.properties</b> file.
* These property names and their default values (as delivered in ESAPI's
* "configuration" jar) are as follows:
* <pre>
* Encoder.AllowMultipleEncoding=false
* Encoder.AllowMixedEncoding=false
* Encoder.DefaultCodecList=HTMLEntityCodec,PercentCodec,JavaScriptCodec
* </pre>
* In places where canonicalization is checked, multiple
* encoding (the first property, which refers to encoding in the <i>same</i> manner
* more than once) or mixed encoding (the second property, which refers to
* encoding using multiple <i>different</i> encoding mechanisms) are generally
* considered attacks unless these respective property values are set to
* "true".
* </p><p>
* Note that changing any of these three properties may affect the behavior as
* documented in this class' methods.
* </p>
*
* @author Jeff Williams (jeff.williams .at. aspectsecurity.com) <a href="http://www.aspectsecurity.com">Aspect Security</a>
* @author Jim Manico ([email protected]) <a href="http://www.manico.net">Manico.net</a>
* @author Matt Seil (mseil .at. acm.org)
*
* @since June 1, 2007
* @see org.owasp.esapi.Validator
* @see org.owasp.esapi.Encoder
* @see org.owasp.esapi.Encoder#canonicalize(String,boolean,boolean)
*/
public class DefaultValidator implements org.owasp.esapi.Validator {
private static Logger logger = ESAPI.log();
Expand Down Expand Up @@ -102,16 +131,22 @@ public static Validator getInstance() {

/**
* Default constructor uses the ESAPI standard encoder for canonicalization.
* This uses an {@code Encoder} created based on the {@code Codec}s
* specified by the value of the {@code Encoder.DefaultCodecList} ESAPI
* property as defined in your <b>ESAPI.properties</b> file.
*/
public DefaultValidator() {
this.encoder = ESAPI.encoder();
}

/**
* Construct a new DefaultValidator that will use the specified
* Encoder for canonicalization.
*
* @param encoder
* {@code Encoder} for canonicalization.
* @param encoder The specially constructed ESAPI {@code Encoder} instance
* that uses a custom list of {@code Codec}s for
* canonicalization purposes. See
* {@link org.owasp.esapi.Encoder#canonicalize(String,boolean,boolean)}
* for an example of how to create a custom {@code Encoder}.
*/
public DefaultValidator( Encoder encoder ) {
this.encoder = encoder;
Expand Down Expand Up @@ -139,7 +174,11 @@ public ValidationRule getRule(String name ) {
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public boolean isValidInput(String context, String input, String type, int maxLength, boolean allowNull) throws IntrusionException {
Expand All @@ -150,7 +189,11 @@ public boolean isValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public boolean isValidInput(String context, String input, String type, int maxLength, boolean allowNull, ValidationErrorList errors) {
Expand All @@ -161,7 +204,11 @@ public boolean isValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
* <p>
* This implementation does not throw {@link IntrusionException}.
*/
Expand All @@ -179,7 +226,11 @@ public boolean isValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public boolean isValidInput(String context, String input, String type, int maxLength, boolean allowNull, boolean canonicalize, ValidationErrorList errors) throws IntrusionException {
Expand All @@ -196,7 +247,11 @@ public boolean isValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public String getValidInput(String context, String input, String type, int maxLength, boolean allowNull) throws ValidationException {
Expand All @@ -207,7 +262,11 @@ public String getValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public String getValidInput(String context, String input, String type, int maxLength, boolean allowNull, boolean canonicalize) throws ValidationException {
Expand All @@ -229,7 +288,11 @@ public String getValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public String getValidInput(String context, String input, String type, int maxLength, boolean allowNull, ValidationErrorList errors) throws IntrusionException {
Expand All @@ -240,7 +303,11 @@ public String getValidInput(String context, String input, String type, int maxLe
* {@inheritDoc}
* <p>
* Double encoding is treated as an attack.
* The default encoder supports HTML encoding, URL encoding, and javascript escaping.
* The canonicalization behavior is controlled by the instance's associated ESAPI
* {@code Encoder} and generally driven through the ESAPI property
* {@code Encoder.DefaultCodecList} specified in the <b>ESAPI.properties</b>
* file. See the class level documentation section "<b>A Note about Canonicalization</b>"
* for additional details.
*/
@Override
public String getValidInput(String context, String input, String type, int maxLength, boolean allowNull, boolean canonicalize, ValidationErrorList errors) throws IntrusionException {
Expand Down