org.apereo.cas.security

Class RequestParameterPolicyEnforcementFilter

java.lang.Object

org.apereo.cas.security.AbstractSecurityFilter

org.apereo.cas.security.RequestParameterPolicyEnforcementFilter

All Implemented Interfaces:

javax.servlet.Filter

public class RequestParameterPolicyEnforcementFilter
extends AbstractSecurityFilter
implements javax.servlet.Filter

This is a Java Servlet Filter that examines specified Request Parameters as to whether they contain specified characters and as to whether they are multivalued throws an Exception if they do not meet configured rules.

Configuration:

The filter defaults to checking all request parameters for the hash, percent, question mark, and ampersand characters, and enforcing no-multi-valued-ness.

You can turn off multi-value checking by setting the init-param "allowMultiValuedParameters" to "true". Setting it to "false" is a no-op retaining the default configuration. Setting this parameter to any other value fails filter initialization.

You can change the set of request parameters being examined by setting the init-param "parametersToCheck" to a whitespace delimited list of parameters to check. Setting it to the special value "*" retains the default behavior of checking all. Setting it to a blank value fails filter initialization. Setting it to a String containing the asterisk token and any additional token fails filter initialization.

You can change the set of characters looked for by setting the init-param "charactersToForbid" to a whitespace delimited list of characters to forbid. Setting it to the special value "none" disables the illicit character blocking feature of this Filter (for the case where you only want to use the mutli-valued-ness blocking). Setting it to a blank value fails filter initialization. Setting it to a value that fails to parse perfectly (e.g., a value with multi-character Strings between the whitespace delimiters) fails filter initialization. The default set of characters disallowed is percent, hash, question mark, and ampersand.

Setting any other init parameter other than these recognized by this Filter will fail Filter initialization. This is to protect the adopter from typos or misunderstandings in web.xml configuration such that an intended configuration might not have taken effect, since that might have security implications.

Setting the Filter to both allow multi-valued parameters and to disallow no characters would make the Filter a no-op, and so fails Filter initialization since you probably meant the Filter to be doing something.

The intent of this filter is rough, brute force blocking of unexpected characters in specific CAS protocol related request parameters. This is one option as a workaround for patching in place certain Java CAS Client versions that may be vulnerable to certain attacks involving crafted request parameter values that may be mishandled. This is also suitable for patching certain CAS Server versions to make more of an effort to detect and block out-of-spec CAS protocol requests. Aside from the intent to be useful for those cases, there is nothing CAS-specific about this Filter itself. This is a generic Filter for doing some pretty basic generic sanity checking on request parameters. It might come in handy the next time this kind of issue arises.

This Filter is written to have no external .jar dependencies aside from the Servlet API necessary to be a Filter.

This class is declared final because it is not designed for extension.

Since:

cas-security-filter 1.1

Field Summary

Fields

Modifier and Type	Field and Description
static String	ALLOW_MULTI_VALUED_PARAMETERS The name of the optional Filter init-param specifying whether the checked request parameters are allowed to have multiple values.
static String	CHARACTERS_TO_FORBID The name of the optional Filter init-param specifying what characters are forbidden in the checked request parameters.
static String	DEFAULT_CHARACTERS_BLOCKED The set of Characters blocked by default on checked parameters.
static String	ONLY_POST_PARAMETERS The name of the optional Filter init-param specifying what request parameters ought to be send via POST requests only.
static String	PARAMETERS_TO_CHECK The name of the optional Filter init-param specifying what request parameters ought to be checked.

Fields inherited from class org.apereo.cas.security.AbstractSecurityFilter

LOGGER_HANDLER_CLASS_NAME

Constructor Summary

Constructors

Constructor and Description
RequestParameterPolicyEnforcementFilter()

Method Summary

Modifier and Type	Method and Description
void	destroy()
void	doFilter(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain chain)
void	init(javax.servlet.FilterConfig filterConfig)
void	setAllowMultiValueParameters(boolean allowMultiValueParameters)
void	setCharactersToForbid(Set<Character> charactersToForbid)
void	setLoggerHandlerClassName(String loggerHandlerClassName)
void	setOnlyPostParameters(Set<String> onlyPostParameters)
void	setParametersToCheck(Set<String> parametersToCheck)

Methods inherited from class org.apereo.cas.security.AbstractSecurityFilter

getLoggerHandlerClassName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_CHARACTERS_BLOCKED

public static final String DEFAULT_CHARACTERS_BLOCKED

The set of Characters blocked by default on checked parameters. Expressed as a whitespace delimited set of characters.

See Also:

Constant Field Values

PARAMETERS_TO_CHECK

public static final String PARAMETERS_TO_CHECK

The name of the optional Filter init-param specifying what request parameters ought to be checked. The value is a whitespace delimited set of parameters. The exact value '*' has the special meaning of matching all parameters, and is the default behavior.

See Also:

Constant Field Values

CHARACTERS_TO_FORBID

public static final String CHARACTERS_TO_FORBID

The name of the optional Filter init-param specifying what characters are forbidden in the checked request parameters. The value is a whitespace delimited set of such characters.

See Also:

Constant Field Values

ALLOW_MULTI_VALUED_PARAMETERS

public static final String ALLOW_MULTI_VALUED_PARAMETERS

The name of the optional Filter init-param specifying whether the checked request parameters are allowed to have multiple values. Allowable values for this init parameter are `true` and `false`.

See Also:

Constant Field Values

ONLY_POST_PARAMETERS

public static final String ONLY_POST_PARAMETERS

The name of the optional Filter init-param specifying what request parameters ought to be send via POST requests only.

See Also:

Constant Field Values

Constructor Detail

RequestParameterPolicyEnforcementFilter

public RequestParameterPolicyEnforcementFilter()

Method Detail

setParametersToCheck

public void setParametersToCheck(Set<String> parametersToCheck)

setCharactersToForbid

public void setCharactersToForbid(Set<Character> charactersToForbid)

setAllowMultiValueParameters

public void setAllowMultiValueParameters(boolean allowMultiValueParameters)

setOnlyPostParameters

public void setOnlyPostParameters(Set<String> onlyPostParameters)

setLoggerHandlerClassName

public void setLoggerHandlerClassName(String loggerHandlerClassName)

Overrides:

setLoggerHandlerClassName in class AbstractSecurityFilter

init

public void init(javax.servlet.FilterConfig filterConfig)
          throws javax.servlet.ServletException

Specified by:

init in interface javax.servlet.Filter

Throws:

javax.servlet.ServletException

doFilter

public void doFilter(javax.servlet.ServletRequest request,
                     javax.servlet.ServletResponse response,
                     javax.servlet.FilterChain chain)
              throws IOException,
                     javax.servlet.ServletException

Specified by:

doFilter in interface javax.servlet.Filter

Throws:

IOException

javax.servlet.ServletException

destroy

public void destroy()

Specified by:

destroy in interface javax.servlet.Filter