org.gwtproject.safehtml.shared.SafeHtml Maven / Gradle / Ivy
/*
* Copyright © 2019 The GWT Project Authors
*
* 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 org.gwtproject.safehtml.shared;
import java.io.Serializable;
import org.gwtproject.safehtml.shared.annotations.IsSafeHtml;
/**
* An object that implements this interface encapsulates HTML that is guaranteed to be safe to use
* (with respect to potential Cross-Site-Scripting vulnerabilities) in an HTML context.
*
* Note on usage: SafeHtml should be used to ensure user input is not executed in the browser.
* SafeHtml should not be used to sanitize input before sending it to the server: The server cannot
* rely on the type contract of SafeHtml values received from clients, because a malicious client
* could provide maliciously crafted serialized forms of implementations of this type that violate
* the type contract.
*
*
All implementing classes must maintain the class invariant (by design and implementation
* and/or convention of use), that invoking {@link #asString()} on any instance will return a string
* that is safe to assign to the {@code .innerHTML} DOM property in a browser (or to use similarly
* in an "inner HTML" context), in the sense that doing so must not cause execution of script in the
* browser.
*
*
Furthermore, values of this type must be composable, i.e. for any two values {@code A} and
* {@code B} of this type, {@code A.asString() + B.asString()} must itself be a value that satisfies
* the SafeHtml type constraint. This requirement implies that for any value {@code A} of this type,
* if {@code A.asString()} includes HTML markup, the string must end in an "inner HTML" context and
* not inside a tag or attribute. For example, a value of {@code