1
// Copyright 2016 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview Potentially unsafe API for the HTML sanitizer.
17
 *
18
 * The HTML sanitizer enforces a default a safe policy, and also limits how the
19
 * policy can be relaxed, so that developers cannot misconfigure it and
20
 * introduce vulnerabilities.
21
 *
22
 * This file extends the HTML sanitizer's capabilities with potentially unsafe
23
 * configuration options, such as the ability to extend the tag whitelist (e.g.
24
 * to support web components).
25
 *
26
 * @supported IE 10+, Chrome 26+, Firefox 22+, Safari 7.1+, Opera 15+
27
 * @visibility {//closure/goog/html/sanitizer:approved_for_unsafe_config}
28
 */
29

30
goog.provide('goog.html.sanitizer.unsafe');
31

32
goog.require('goog.asserts');
33
goog.require('goog.html.sanitizer.HtmlSanitizer.Builder');
34
goog.require('goog.string');
35
goog.require('goog.string.Const');
36

37

38
/**
39
 * Extends the tag whitelist with the list of tags provided.
40
 *
41
 * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure
42
 * that the new tags do not introduce untrusted code execution or unsanctioned
43
 * network activity.
44
 *
45
 * @param {!goog.string.Const} justification A constant string explaining why
46
 *     the addition of these tags to the whitelist is safe. May include a
47
 *     security review ticket number.
48
 * @param {!goog.html.sanitizer.HtmlSanitizer.Builder} builder The builder
49
 *     whose tag whitelist should be extended.
50
 * @param {!Array<string>} tags A list of additional tags to allow through the
51
 *     sanitizer. Note that if the tag is also present in the blacklist,
52
 *     its addition to the whitelist has no effect. The tag names are
53
 *     case-insensitive.
54
 * @return {!goog.html.sanitizer.HtmlSanitizer.Builder}
55
 */
56
goog.html.sanitizer.unsafe.alsoAllowTags = function(
57
    justification, builder, tags) {
58
  goog.asserts.assertString(
59
      goog.string.Const.unwrap(justification), 'must provide justification');
60
  goog.asserts.assert(
61
      !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)),
62
      'must provide non-empty justification');
63
  return builder.alsoAllowTagsPrivateDoNotAccessOrElse(tags);
64
};
65

66
/**
67
 * Installs custom attribute policies for the attributes provided in the list.
68
 * This can be used either on non-whitelisted attributes, effectively extending
69
 * the attribute whitelist, or on attributes that are whitelisted and already
70
 * have a policy, to override their policies.
71
 *
72
 * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure
73
 * that the new tags do not introduce untrusted code execution or unsanctioned
74
 * network activity.
75
 *
76
 * @param {!goog.string.Const} justification A constant string explaining why
77
 *     the addition of these attributes to the whitelist is safe. May include a
78
 *     security review ticket number.
79
 * @param {!goog.html.sanitizer.HtmlSanitizer.Builder} builder The builder
80
 *     whose attribute whitelist should be extended.
81
 * @param {!Array<(string|!goog.html.sanitizer.HtmlSanitizerAttributePolicy)>}
82
 *     attrs A list of attributes whose policy should be overridden. Attributes
83
 *     can come in of two forms:
84
 *     - string: allow all values and just trim whitespaces for this attribute
85
 *         on all tags.
86
 *     - HtmlSanitizerAttributePolicy: allows specifying a policy for a
87
 *         particular tag. The tagName can be '*', which means all tags. If no
88
 *         policy is passed, the default is allow all values and just trim
89
 *         whitespaces.
90
 *     The tag and attribute names are case-insensitive.
91
 * @return {!goog.html.sanitizer.HtmlSanitizer.Builder}
92
 */
93
goog.html.sanitizer.unsafe.alsoAllowAttributes = function(
94
    justification, builder, attrs) {
95
  goog.asserts.assertString(
96
      goog.string.Const.unwrap(justification), 'must provide justification');
97
  goog.asserts.assert(
98
      !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)),
99
      'must provide non-empty justification');
100
  return builder.alsoAllowAttributesPrivateDoNotAccessOrElse(attrs);
101
};
102

103

104
/**
105
 * Turns off sanitization of TEMPLATE tag descendants. The output is still
106
 * safe to consume as a whole, but clients need to handle the contents of
107
 * TEMPLATE nodes carefully, hence its definition in the unsafe package.
108
 *
109
 * Note that this only applies to descendants of unsanitized template tags, not
110
 * to the tag itself, which must be manually added to the whitelist and removed
111
 * from the blacklist.
112
 *
113
 * IMPORTANT: Uses of this method must be carefully security-reviewed to ensure
114
 * that the new tags do not introduce untrusted code execution or unsanctioned
115
 * network activity.
116
 *
117
 * @param {!goog.string.Const} justification A constant string explaining why
118
 *     the templates should not be sanitized, and why this is safe. May include
119
 *     a security review ticket number.
120
 * @param {!goog.html.sanitizer.HtmlSanitizer.Builder} builder The builder
121
 *     whose template tag descendants should not be sanitized.
122
 * @return {!goog.html.sanitizer.HtmlSanitizer.Builder}
123
 * @throws {Error} Thrown if the browser does not support TEMPLATE tags.
124
 *     In this case, careful post-sanitization handling wouldn't matter.
125
 */
126
goog.html.sanitizer.unsafe.keepUnsanitizedTemplateContents = function(
127
    justification, builder) {
128
  goog.asserts.assertString(
129
      goog.string.Const.unwrap(justification), 'must provide justification');
130
  goog.asserts.assert(
131
      !goog.string.isEmptyOrWhitespace(goog.string.Const.unwrap(justification)),
132
      'must provide non-empty justification');
133
  return builder.keepUnsanitizedTemplateContentsPrivateDoNotAccessOrElse();
134
};
135

136