/**
* Copyright 2008 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 org.waveprotocol.box.server.rpc.render.common.safehtml;
import java.io.Serializable;
//NOTE: In the near future, the files in this package will be open sourced as
//part of a different project. Do not rely on them staying here.
/**
* 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.
*
* <p>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.
*
* <p>Implementations of this interface must not implement
* {@link com.google.gwt.user.client.rpc.IsSerializable}, since deserialization can result in
* violation of the class invariant.
*/
public interface SafeHtml extends Serializable {
/* Notes regading serialization:
* - It may be reasonable to allow deserialization on the client of objects
* serialized on the server (i.e. RPC responses), based on the assumption that
* server code is trusted and would not provide a malicious serialized form
* (if a MitM were able to modify server responses, the client would be
* fully compromised in any case). However, the GWT RPC framework currently
* does not seem to provide a facility for restricting deserialization on the
* Server only (thought this shouldn't be difficult to implement through a
* custom SerializationPolicy)
*
* - Some implementations of SafeHtml would in principle be able to enforce
* their class invariant on deserialization (e.g., SimpleHtmlSanitizer could apply
* HTML sanitization on deserialization). However, the GWT RPC framework does
* not provide for an equivalent of readResolve() to enforce the class
* invariant on deserialization.
*
*/
/**
* Returns this object's contained HTML as a string. Based on this class' contract, the returned
* string will be safe to use in an HTML context.
*/
String asString();
}