org.apache.struts2.interceptor

## Class CookieInterceptor

- java.lang.Object
- - com.opensymphony.xwork2.interceptor.AbstractInterceptor
  - - org.apache.struts2.interceptor.CookieInterceptor

- All Implemented Interfaces:
    Interceptor, Serializable

      public class CookieInterceptor
      extends AbstractInterceptor

  The aim of this interceptor is to set values in the stack/action based on cookie name/value of interest.

  If an asterisk is present in cookiesName parameter, it will be assume that all cookies name are to be injected into struts' action, even though cookiesName is comma-separated by other values, e.g. (cookie1,*,cookie2).

  If cookiesName is left empty it will assume that no cookie will be injected into Struts' action.

  If an asterisk is present in cookiesValue parameter, it will assume that all cookies name irrespective of its value will be injected into Struts' action so long as the cookie name matches those specified in cookiesName parameter.

  If cookiesValue is left empty it will assume that all cookie that match the cookieName parameter will be injected into Struts' action.

  The action could implement `CookiesAware` in order to have a `Map` of filtered cookies set into it.

  - cookiesName (mandatory) - Name of cookies to be injected into the action. If more than one cookie name is desired it could be comma-separated. If all cookies name is desired, it could simply be *, an asterik. When many cookies name are comma-separated either of the cookie that match the name in the comma-separated list will be qualified.
  - cookiesValue (mandatory) - Value of cookies that if its name matches cookieName attribute and its value matched this, will be injected into Struts' action. If more than one cookie name is desired it could be comma-separated. If left empty, it will assume any value would be ok. If more than one value is specified (comma-separated) it will assume a match if either value is matched.
  - acceptCookieNames (optional) - Pattern used to check if name of cookie matches the provided patter, to
  - populateCookieValueIntoStack - this method will decide if this cookie value is qualified to be populated into the value stack (hence into the action itself)
  - injectIntoCookiesAwareAction - this method will inject selected cookies (as a java.util.Map) into action that implements `CookiesAware`.

       <!--
         This example will inject cookies named either 'cookie1' or 'cookie2' whose
         value could be either 'cookie1value' or 'cookie2value' into Struts' action.
       -->
       <action ... >
          <interceptor-ref name="cookie">
              <param name="cookiesName">cookie1, cookie2</param>
              <param name="cookiesValue">cookie1value, cookie2value</param>
          </interceptor-ref>
          ....
       </action>

       <!--
            This example will inject cookies named either 'cookie1' or 'cookie2'
           regardless of their value into Struts' action.
       -->
       <action ... >
         <interceptor-ref name="cookie">
            <param name="cookiesName">cookie1, cookie2</param>
            <param name="cookiesValue">*</param>
         <interceptor-ref>
         ...
       </action>

       <!--
            This example will inject cookies named either 'cookie1' with value
            'cookie1value' or 'cookie2' with value 'cookie2value' into Struts'
            action.
       -->
       <action ... >
         <interceptor-ref name="cookie">
            <param name="cookiesName">cookie1</param>
            <param name="cookiesValue">cookie1value</param>
         </interceptor-ref>
         <interceptor-ref name="cookie">
            <param name="cookiesName"<cookie2</param>
           <param name="cookiesValue">cookie2value</param>
         </interceptor-ref>
         ....
       </action>

       <!--
          This example will inject any cookies regardless of its value into
          Struts' action.
        -->
       <action ... >
         <interceptor-ref name="cookie">
            <param name="cookiesName">*</param>
            <param name="cookiesValue">*</param>
         </interceptor-ref>
          ...
       </action>

  See Also:
    `CookiesAware`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CookieInterceptor()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `injectIntoCookiesAwareAction(Object action, Map<String,String> cookiesMap)` Hook that set the `cookiesMap` into action that implements `CookiesAware`.
    `String` | `intercept(ActionInvocation invocation)` Override to handle interception
    `protected boolean` | `isAcceptableName(String name)` Checks if name of Cookie doesn't contain vulnerable code
    `protected boolean` | `isAccepted(String name)` Checks if name/value of Cookie is acceptable
    `protected boolean` | `isExcluded(String name)` Checks if name/value of Cookie is excluded
    `protected void` | `populateCookieValueIntoStack(String cookieName, String cookieValue, Map<String,String> cookiesMap, ValueStack stack)` Hook that populate cookie value into value stack (hence the action) if the criteria is satisfied (if the cookie value matches with those configured).
    `void` | `setAcceptCookieNames(String commaDelimitedPattern)` Set the `acceptCookieNames` pattern of allowed names of cookies to protect against remote command execution vulnerability.
    `void` | `setAcceptedPatternsChecker(AcceptedPatternsChecker acceptedPatternsChecker)`
    `void` | `setCookiesName(String cookiesName)`
    `void` | `setCookiesValue(String cookiesValue)`
    `void` | `setExcludedPatternsChecker(ExcludedPatternsChecker excludedPatternsChecker)`

    - ### Methods inherited from class com.opensymphony.xwork2.interceptor.AbstractInterceptor

      `destroy, init`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### CookieInterceptor

          public CookieInterceptor()

  - ### Method Detail

    - #### setExcludedPatternsChecker

          public void setExcludedPatternsChecker(ExcludedPatternsChecker excludedPatternsChecker)

    - #### setAcceptedPatternsChecker

          public void setAcceptedPatternsChecker(AcceptedPatternsChecker acceptedPatternsChecker)

    - #### setCookiesName

          public void setCookiesName(String cookiesName)

      Parameters:
        `cookiesName` - the `cookiesName` which if matched will allow the cookie to be injected into action, could be comma-separated string.

    - #### setCookiesValue

          public void setCookiesValue(String cookiesValue)

      Parameters:
        `cookiesValue` - the `cookiesValue` which if matched (together with matching cookiesName) will caused the cookie to be injected into action, could be comma-separated string.

    - #### setAcceptCookieNames

          public void setAcceptCookieNames(String commaDelimitedPattern)

      Set the `acceptCookieNames` pattern of allowed names of cookies to protect against remote command execution vulnerability.
      Parameters:
        `commaDelimitedPattern` - is used to check cookie name against, can set of comma delimited patterns

    - #### intercept

          public String intercept(ActionInvocation invocation)
                           throws Exception

      Description copied from class: `AbstractInterceptor`
      Override to handle interception
      Specified by:
        `intercept` in interface `Interceptor`
      Specified by:
        `intercept` in class `AbstractInterceptor`
      Parameters:
        `invocation` - the action invocation
      Returns:
        the return code, either returned from `ActionInvocation.invoke()`, or from the interceptor itself.
      Throws:
        `Exception` - any system-level error, as defined in `Action.execute()`.

    - #### isAcceptableName

          protected boolean isAcceptableName(String name)

      Checks if name of Cookie doesn't contain vulnerable code
      Parameters:
        `name` - of Cookie
      Returns:
        true|false

    - #### isAccepted

          protected boolean isAccepted(String name)

      Checks if name/value of Cookie is acceptable
      Parameters:
        `name` - of Cookie
      Returns:
        true|false

    - #### isExcluded

          protected boolean isExcluded(String name)

      Checks if name/value of Cookie is excluded
      Parameters:
        `name` - of Cookie
      Returns:
        true|false

    - #### populateCookieValueIntoStack

          protected void populateCookieValueIntoStack(String cookieName,
                                                      String cookieValue,
                                                      Map<String,String> cookiesMap,
                                                      ValueStack stack)

      Hook that populate cookie value into value stack (hence the action) if the criteria is satisfied (if the cookie value matches with those configured).
      Parameters:
        `cookieName` - cookie name
        `cookieValue` - cookie value
        `cookiesMap` - map of cookies
        `stack` - value stack

    - #### injectIntoCookiesAwareAction

          protected void injectIntoCookiesAwareAction(Object action,
                                                      Map<String,String> cookiesMap)

      Hook that set the `cookiesMap` into action that implements `CookiesAware`.
      Parameters:
        `action` - action object
        `cookiesMap` - map of cookies

Copyright © 2000–2023 Apache Software Foundation. All rights reserved.