| /* |
| * Copyright 2011 Google Inc. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); you may not |
| * use this file except in compliance with the License. You may obtain a copy of |
| * the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT |
| * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the |
| * License for the specific language governing permissions and limitations under |
| * the License. |
| */ |
| package com.google.gwt.safecss.shared; |
| |
| /** |
| * A builder that facilitates the building up of XSS-safe CSS attribute strings |
| * from {@link SafeStyles}. It is used essentially like a {@link StringBuilder}, |
| * but access {@link SafeStyles} instead of Strings. |
| * |
| * <p> |
| * The accumulated XSS-safe {@link SafeStyles} can be obtained in the form of a |
| * {@link SafeStyles} via the {@link #toSafeStyles()} method. |
| * |
| * <p> |
| * This class is not thread-safe. |
| */ |
| public final class SafeStylesBuilder { |
| |
| private final StringBuilder sb = new StringBuilder(); |
| |
| /** |
| * Constructs an empty {@link SafeStylesBuilder}. |
| */ |
| public SafeStylesBuilder() { |
| } |
| |
| /** |
| * Appends the contents of another {@link SafeStyles} object, without applying |
| * any escaping or sanitization to it. |
| * |
| * @param styles the {@link SafeStyles} to append |
| * @return a reference to this object |
| */ |
| public SafeStylesBuilder append(SafeStyles styles) { |
| sb.append(styles.asString()); |
| return this; |
| } |
| |
| /** |
| * <p> |
| * Appends {@link SafeStyles} constructed from a trusted string, i.e., without |
| * escaping the string. Only minimal checks are performed. The calling code |
| * should be carefully reviewed to ensure the argument meets the |
| * {@link SafeStyles} contract. |
| * |
| * <p> |
| * Generally, {@link SafeStyles} should be of the form |
| * {@code cssPropertyName:value;}, where neither the name nor the value |
| * contain malicious scripts. |
| * |
| * <p> |
| * {@link SafeStyles} may never contain literal angle brackets. Otherwise, it |
| * could be unsafe to place a {@link SafeStyles} into a <style> tag |
| * (where it can't be HTML escaped). For example, if the {@link SafeStyles} |
| * containing " |
| * <code>font: 'foo <style><script>evil</script></code>'" is |
| * used in a style sheet in a <style> tag, this could then break out of |
| * the style context into HTML. |
| * |
| * <p> |
| * The following example values comply with this type's contract: |
| * <ul> |
| * <li><code>width: 1em;</code></li> |
| * <li><code>height:1em;</code></li> |
| * <li><code>width: 1em;height: 1em;</code></li> |
| * <li><code>background:url('http://url');</code></li> |
| * </ul> |
| * In addition, the empty string is safe for use in a CSS attribute. |
| * |
| * <p> |
| * The following example values do <em>not</em> comply with this type's contract: |
| * <ul> |
| * <li><code>background: red</code> (missing a trailing semi-colon)</li> |
| * <li><code>background:</code> (missing a value and a trailing semi-colon)</li> |
| * <li><code>1em</code> (missing an attribute name, which provides context for the value)</li> |
| * </ul> |
| * |
| * @param styles the input String |
| * @return a {@link SafeStyles} instance |
| */ |
| public SafeStylesBuilder appendTrustedString(String styles) { |
| SafeStylesUtils.verifySafeStylesConstraints(styles); |
| sb.append(styles); |
| return this; |
| } |
| |
| /** |
| * Returns the safe CSS properties accumulated in the builder as a |
| * {@link SafeStyles}. |
| * |
| * @return a {@link SafeStyles} instance |
| */ |
| public SafeStyles toSafeStyles() { |
| return new SafeStylesString(sb.toString()); |
| } |
| } |