1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
// Copyright 2013 The Closure Library Authors. All Rights Reserved.
//
// 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.
/**
* @fileoverview Transitional utilities to unsafely trust random strings as
* goog.html types. Intended for temporary use when upgrading a library that
* used to accept plain strings to use safe types, but where it's not
* practical to transitively update callers.
*
* IMPORTANT: No new code should use the conversion functions in this file,
* they are intended for refactoring old code to use goog.html types. New code
* should construct goog.html types via their APIs, template systems or
* sanitizers. If that’s not possible it should use
* goog.html.uncheckedconversions and undergo security review.
*
* The semantics of the conversions in goog.html.legacyconversions are very
* different from the ones provided by goog.html.uncheckedconversions. The
* latter are for use in code where it has been established through manual
* security review that the value produced by a piece of code will always
* satisfy the SafeHtml contract (e.g., the output of a secure HTML sanitizer).
* In uses of goog.html.legacyconversions, this guarantee is not given -- the
* value in question originates in unreviewed legacy code and there is no
* guarantee that it satisfies the SafeHtml contract.
*
* There are only three valid uses of legacyconversions:
*
* 1. Introducing a goog.html version of a function which currently consumes
* string and passes that string to a DOM API which can execute script - and
* hence cause XSS - like innerHTML. For example, Dialog might expose a
* setContent method which takes a string and sets the innerHTML property of
* an element with it. In this case a setSafeHtmlContent function could be
* added, consuming goog.html.SafeHtml instead of string, and using
* goog.dom.safe.setInnerHtml instead of directly setting innerHTML.
* setContent could then internally use legacyconversions to create a SafeHtml
* from string and pass the SafeHtml to setSafeHtmlContent. In this scenario
* remember to document the use of legacyconversions in the modified setContent
* and consider deprecating it as well.
*
* 2. Automated refactoring of application code which handles HTML as string
* but needs to call a function which only takes goog.html types. For example,
* in the Dialog scenario from (1) an alternative option would be to refactor
* setContent to accept goog.html.SafeHtml instead of string and then refactor
* all current callers to use legacyconversions to pass SafeHtml. This is
* generally preferable to (1) because it keeps the library clean of
* legacyconversions, and makes code sites in application code that are
* potentially vulnerable to XSS more apparent.
*
* 3. Old code which needs to call APIs which consume goog.html types and for
* which it is prohibitively expensive to refactor to use goog.html types.
* Generally, this is code where safety from XSS is either hopeless or
* unimportant.
*
* @visibility {//closure/goog/html:approved_for_legacy_conversion}
* @visibility {//closure/goog/bin/sizetests:__pkg__}
*/
goog.provide('goog.html.legacyconversions');
goog.require('goog.html.SafeHtml');
goog.require('goog.html.SafeScript');
goog.require('goog.html.SafeStyle');
goog.require('goog.html.SafeStyleSheet');
goog.require('goog.html.SafeUrl');
goog.require('goog.html.TrustedResourceUrl');
/**
* Performs an "unchecked conversion" from string to SafeHtml for legacy API
* purposes.
*
* Please read fileoverview documentation before using.
*
* @param {string} html A string to be converted to SafeHtml.
* @return {!goog.html.SafeHtml} The value of html, wrapped in a SafeHtml
* object.
*/
goog.html.legacyconversions.safeHtmlFromString = function(html) {
goog.html.legacyconversions.reportCallback_();
return goog.html.SafeHtml.createSafeHtmlSecurityPrivateDoNotAccessOrElse(
html, null /* dir */);
};
/**
* Performs an "unchecked conversion" from string to SafeScript for legacy API
* purposes.
*
* Please read fileoverview documentation before using.
*
* @param {string} script A string to be converted to SafeScript.
* @return {!goog.html.SafeScript} The value of script, wrapped in a SafeScript
* object.
*/
goog.html.legacyconversions.safeScriptFromString = function(script) {
goog.html.legacyconversions.reportCallback_();
return goog.html.SafeScript.createSafeScriptSecurityPrivateDoNotAccessOrElse(
script);
};
/**
* Performs an "unchecked conversion" from string to SafeStyle for legacy API
* purposes.
*
* Please read fileoverview documentation before using.
*
* @param {string} style A string to be converted to SafeStyle.
* @return {!goog.html.SafeStyle} The value of style, wrapped in a SafeStyle
* object.
*/
goog.html.legacyconversions.safeStyleFromString = function(style) {
goog.html.legacyconversions.reportCallback_();
return goog.html.SafeStyle.createSafeStyleSecurityPrivateDoNotAccessOrElse(
style);
};
/**
* Performs an "unchecked conversion" from string to SafeStyleSheet for legacy
* API purposes.
*
* Please read fileoverview documentation before using.
*
* @param {string} styleSheet A string to be converted to SafeStyleSheet.
* @return {!goog.html.SafeStyleSheet} The value of style sheet, wrapped in
* a SafeStyleSheet object.
*/
goog.html.legacyconversions.safeStyleSheetFromString = function(styleSheet) {
goog.html.legacyconversions.reportCallback_();
return goog.html.SafeStyleSheet
.createSafeStyleSheetSecurityPrivateDoNotAccessOrElse(styleSheet);
};
/**
* Performs an "unchecked conversion" from string to SafeUrl for legacy API
* purposes.
*
* Please read fileoverview documentation before using.
*
* @param {string} url A string to be converted to SafeUrl.
* @return {!goog.html.SafeUrl} The value of url, wrapped in a SafeUrl
* object.
*/
goog.html.legacyconversions.safeUrlFromString = function(url) {
goog.html.legacyconversions.reportCallback_();
return goog.html.SafeUrl.createSafeUrlSecurityPrivateDoNotAccessOrElse(url);
};
/**
* Performs an "unchecked conversion" from string to TrustedResourceUrl for
* legacy API purposes.
*
* Please read fileoverview documentation before using.
*
* @param {string} url A string to be converted to TrustedResourceUrl.
* @return {!goog.html.TrustedResourceUrl} The value of url, wrapped in a
* TrustedResourceUrl object.
*/
goog.html.legacyconversions.trustedResourceUrlFromString = function(url) {
goog.html.legacyconversions.reportCallback_();
return goog.html.TrustedResourceUrl
.createTrustedResourceUrlSecurityPrivateDoNotAccessOrElse(url);
};
/**
* @private {function(): undefined}
*/
goog.html.legacyconversions.reportCallback_ = goog.nullFunction;
/**
* Sets a function that will be called every time a legacy conversion is
* performed. The function is called with no parameters but it can use
* goog.debug.getStacktrace to get a stacktrace.
*
* @param {function(): undefined} callback Error callback as defined above.
*/
goog.html.legacyconversions.setReportCallback = function(callback) {
goog.html.legacyconversions.reportCallback_ = callback;
};
|
