AttributePolicy.java revision 6d8c2e9241d042a3e0bff40dac4c388966ad060c 
1// Copyright (c) 2011, Mike Samuel
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions
6// are met:
7//
8// Redistributions of source code must retain the above copyright
9// notice, this list of conditions and the following disclaimer.
10// Redistributions in binary form must reproduce the above copyright
11// notice, this list of conditions and the following disclaimer in the
12// documentation and/or other materials provided with the distribution.
13// Neither the name of the OWASP nor the names of its contributors may
14// be used to endorse or promote products derived from this software
15// without specific prior written permission.
16// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
19// FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
20// COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
21// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
22// BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23// LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
24// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
26// ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27// POSSIBILITY OF SUCH DAMAGE.
28
29package org.owasp.html;
30
31import javax.annotation.Nullable;
32import javax.annotation.concurrent.Immutable;
33
34/**
35 * A policy that can be applied to an HTML attribute to decide whether or not to
36 * allow it in the output, possibly after transforming its value.
37 *
38 * @author Mike Samuel <mikesamuel@gmail.com>
39 * @see HtmlPolicyBuilder#allowAttributesGlobally(AttributePolicy, String...)
40 */
41@TCB public interface AttributePolicy {
42
43  /**
44   * @param elementName the lower-case element name.
45   * @param attributeName the lower-case attribute name.
46   * @param value the attribute value without quotes and with HTML entities
47   *     decoded.
48   *
49   * @return {@code null} to disallow the attribute or the adjusted value if
50   *     allowed.
51   */
52  public @Nullable String apply(
53      String elementName, String attributeName, String value);
54
55
56  /** Utilities for working with attribute policies. */
57  public static final class Util {
58
59    /**
60     * An attribute policy equivalent to applying all the given policies in
61     * order, failing early if any of them fails.
62     */
63    public static final AttributePolicy join(AttributePolicy... policies) {
64
65      class PolicyJoiner {
66        AttributePolicy last = null;
67        AttributePolicy out = null;
68
69        void join(AttributePolicy p) {
70          if (REJECT_ALL_ATTRIBUTE_POLICY.equals(p)) {
71            out = p;
72          } else if (!REJECT_ALL_ATTRIBUTE_POLICY.equals(out)) {
73            if (p instanceof JoinedAttributePolicy) {
74              JoinedAttributePolicy jap = (JoinedAttributePolicy) p;
75              join(jap.first);
76              join(jap.second);
77            } else if (p != last) {
78              last = p;
79              if (out == null || IDENTITY_ATTRIBUTE_POLICY.equals(out)) {
80                out = p;
81              } else if (!IDENTITY_ATTRIBUTE_POLICY.equals(p)) {
82                out = new JoinedAttributePolicy(out, p);
83              }
84            }
85          }
86        }
87      }
88
89      PolicyJoiner pu = new PolicyJoiner();
90      for (AttributePolicy policy : policies) {
91        if (policy == null) { continue; }
92        pu.join(policy);
93      }
94      return pu.out != null ? pu.out : IDENTITY_ATTRIBUTE_POLICY;
95    }
96  }
97
98
99  public static final AttributePolicy IDENTITY_ATTRIBUTE_POLICY
100      = new AttributePolicy() {
101        public String apply(
102            String elementName, String attributeName, String value) {
103          return value;
104        }
105      };
106
107  public static final AttributePolicy REJECT_ALL_ATTRIBUTE_POLICY
108      = new AttributePolicy() {
109        public @Nullable String apply(
110            String elementName, String attributeName, String value) {
111          return null;
112        }
113      };
114
115}
116
117@Immutable
118final class JoinedAttributePolicy implements AttributePolicy {
119  final AttributePolicy first, second;
120
121  JoinedAttributePolicy(AttributePolicy first, AttributePolicy second) {
122    this.first = first;
123    this.second = second;
124  }
125
126  public @Nullable String apply(
127      String elementName, String attributeName, String value) {
128    value = first.apply(elementName, attributeName, value);
129    return value != null
130        ? second.apply(elementName, attributeName, value) : null;
131  }
132}
133