hixie: Tidy up the database spec. Leave a big scary placeholder for
defining the Web SQL dialect. (whatwg r3655)
http://dev.w3.org/cvsweb/html5/webdatabase/Overview.html?r1=1.18&r2=1.19&f=hhttp://html5.org/tools/web-apps-tracker?from=3654&to=3655
===================================================================
RCS file: /sources/public/html5/webdatabase/Overview.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -d -r1.18 -r1.19
--- Overview.html 18 Aug 2009 05:14:46 -0000 1.18
+++ Overview.html 18 Aug 2009 05:19:17 -0000 1.19
@@ -265,19 +265,20 @@
<li><a href="#executing-sql-statements-0"><span class="secno">4.4.1 </span>Executing SQL statements</a></ol></li>
<li><a href="#database-query-results"><span class="secno">4.5 </span>Database query results</a></li>
<li><a href="#errors-and-exceptions"><span class="secno">4.6 </span>Errors and exceptions</a></ol></li>
- <li><a href="#disk-space"><span class="secno">5 </span>Disk space</a></li>
- <li><a href="#privacy"><span class="secno">6 </span>Privacy</a>
+ <li><a href="#web-sql"><span class="secno">5 </span>Web SQL</a></li>
+ <li><a href="#disk-space"><span class="secno">6 </span>Disk space</a></li>
+ <li><a href="#privacy"><span class="secno">7 </span>Privacy</a>
<ol>
- <li><a href="#user-tracking"><span class="secno">6.1 </span>User tracking</a></li>
- <li><a href="#cookie-resurrection"><span class="secno">6.2 </span>Cookie resurrection</a></li>
- <li><a href="#sensitivity-of-data"><span class="secno">6.3 </span>Sensitivity of data</a></ol></li>
- <li><a href="#security"><span class="secno">7 </span>Security</a>
+ <li><a href="#user-tracking"><span class="secno">7.1 </span>User tracking</a></li>
+ <li><a href="#cookie-resurrection"><span class="secno">7.2 </span>Cookie resurrection</a></li>
+ <li><a href="#sensitivity-of-data"><span class="secno">7.3 </span>Sensitivity of data</a></ol></li>
+ <li><a href="#security"><span class="secno">8 </span>Security</a>
<ol>
- <li><a href="#dns-spoofing-attacks"><span class="secno">7.1 </span>DNS spoofing attacks</a></li>
- <li><a href="#cross-directory-attacks"><span class="secno">7.2 </span>Cross-directory attacks</a></li>
- <li><a href="#implementation-risks"><span class="secno">7.3 </span>Implementation risks</a></li>
- <li><a href="#sql-and-user-agents"><span class="secno">7.4 </span>SQL and user agents</a></li>
- <li><a href="#sql-injection"><span class="secno">7.5 </span>SQL injection</a></ol></li>
+ <li><a href="#dns-spoofing-attacks"><span class="secno">8.1 </span>DNS spoofing attacks</a></li>
+ <li><a href="#cross-directory-attacks"><span class="secno">8.2 </span>Cross-directory attacks</a></li>
+ <li><a href="#implementation-risks"><span class="secno">8.3 </span>Implementation risks</a></li>
+ <li><a href="#sql-and-user-agents"><span class="secno">8.4 </span>SQL and user agents</a></li>
+ <li><a href="#sql-injection"><span class="secno">8.5 </span>SQL injection</a></ol></li>
<li><a class="no-num" href="#references">References</a></ol>
<!--end-toc--><hr><!-- Feature requests for future versions (v2):
* deleting databases
@@ -324,14 +325,10 @@
t.executeSql('SELECT title, author FROM docs WHERE id=?', [id], function (t, data) {
report(data.rows[0].title, data.rows[0].author);
});
-});
-
- <hr><p>Sometimes, there might be an arbitrary number of variables to
+});</pre><hr><p>Sometimes, there might be an arbitrary number of variables to
substitute in. Even in these case, the right solution is to
construct the query using only "?" characters, and then to pass the
- variables in as the second argument:</p>
-
-<pre>function findDocs(db, resultCallback) {
+ variables in as the second argument:<pre>function findDocs(db, resultCallback) {
var q = "";
for each (var i in labels)
q += (q == "" ? "" : ", ") + "?";
@@ -340,54 +337,28 @@
resultCallback(data);
});
});
-}</pre>
-
-
-
-
- <h2 id="conformance-requirements"><span class="secno">2 </span>Conformance requirements</h2>
-
- <p>All diagrams, examples, and notes in this specification are
+}</pre><h2 id="conformance-requirements"><span class="secno">2 </span>Conformance requirements</h2><p>All diagrams, examples, and notes in this specification are
non-normative, as are all sections explicitly marked non-normative.
- Everything else in this specification is normative.</p>
-
- <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
+ Everything else in this specification is normative.<p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
NOT",--> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in the normative parts of this document are to be
interpreted as described in RFC2119. For readability, these words do
- not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
-
- <p>Requirements phrased in the imperative as part of algorithms
+ not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a><p>Requirements phrased in the imperative as part of algorithms
(such as "strip any leading space characters" or "return false and
abort these steps") are to be interpreted with the meaning of the
key word ("must", "should", "may", etc) used in introducing the
- algorithm.</p>
-
- <p>Some conformance requirements are phrased as requirements on
+ algorithm.<p>Some conformance requirements are phrased as requirements on
attributes, methods or objects. Such requirements are to be
- interpreted as requirements on user agents.</p>
-
- <p>Conformance requirements phrased as algorithms or specific steps
+ interpreted as requirements on user agents.<p>Conformance requirements phrased as algorithms or specific steps
may be implemented in any manner, so long as the end result is
equivalent. (In particular, the algorithms defined in this
specification are intended to be easy to follow, and not intended to
- be performant.)</p>
-
- <p>The only conformance class defined by this specification is user
- agents.</p>
-
- <p>User agents may impose implementation-specific limits on
+ be performant.)<p>The only conformance class defined by this specification is user
+ agents.<p>User agents may impose implementation-specific limits on
otherwise unconstrained inputs, e.g. to prevent denial of service
attacks, to guard against running out of memory, or to work around
- platform-specific limitations.</p>
-
-
- <h3 id="dependencies"><span class="secno">2.1 </span>Dependencies</h3>
-
- <p>This specification relies on several other underlying
- specifications.</p>
-
- </pre><dl><dt>HTML5</dt>
+ platform-specific limitations.<h3 id="dependencies"><span class="secno">2.1 </span>Dependencies</h3><p>This specification relies on several other underlying
+ specifications.<dl><dt>HTML5</dt>
<dd>
@@ -564,12 +535,6 @@
<p>The result is <var title="">the statement</var>.</p>
- <p class="XXX">Implementation feedback is requested on what
- to do with arguments that are of types that are not supported by
- the underlying SQL backend. For example, SQLite doesn't support
- booleans, so what should the UA do if passed a boolean? The Gears
- team suggests failing, not silently converting types.</p>
-
</li>
<li><p>If the <code><a href="#database">Database</a></code> object that the
@@ -1115,7 +1080,7 @@
<td>A lock for the transaction could not be obtained in a
reasonable time.
- </table><h2 id="disk-space"><span class="secno">5 </span>Disk space</h2><p>User agents should limit the total amount of space allowed for
+ </table><h2 id="web-sql"><span class="secno">5 </span>Web SQL</h2><p class="XXX">Need to define the SQL dialect.<h2 id="disk-space"><span class="secno">6 </span>Disk space</h2><p>User agents should limit the total amount of space allowed for
databases.
<p>User agents should guard against sites storing data under the
@@ -1128,7 +1093,7 @@
is using.<p>A mostly arbitrary limit of five megabytes per
<span>origin</span> is recommended. Implementation feedback is
welcome and will be used to update this suggestion in the
- future.<h2 id="privacy"><span class="secno">6 </span>Privacy</h2><h3 id="user-tracking"><span class="secno">6.1 </span>User tracking</h3><p>A third-party advertiser (or any entity capable of getting
+ future.<h2 id="privacy"><span class="secno">7 </span>Privacy</h2><h3 id="user-tracking"><span class="secno">7.1 </span>User tracking</h3><p>A third-party advertiser (or any entity capable of getting
content distributed to multiple sites) could use a unique identifier
stored in its
client-side database
@@ -1167,9 +1132,8 @@
<p>However, this also puts the user's data at risk.</p>
- <!-- XXX should there be an explicit way for sites to state when
- data should expire? as in
- localStorage.expireData(365); ? -->
+ <!--v2 consider adding an explicit way for sites to state when
+ data should expire, as in localStorage.expireData(365); -->
</dd>
@@ -1240,23 +1204,23 @@
retroactively). This information can then be shared with other
sites, using using visitors' IP addresses and other user-specific
data (e.g. user-agent headers and configuration settings) to combine
- separate sessions into coherent user profiles.<h3 id="cookie-resurrection"><span class="secno">6.2 </span>Cookie resurrection</h3><p>If the user interface for persistent storage presents data in the
+ separate sessions into coherent user profiles.<h3 id="cookie-resurrection"><span class="secno">7.2 </span>Cookie resurrection</h3><p>If the user interface for persistent storage presents data in the
persistent storage features described in this specification
separately from data in HTTP session cookies, then users are likely
to delete data in one and not the other. This would allow sites to
use the two features as redundant backup for each other, defeating a
- user's attempts to protect his privacy.<h3 id="sensitivity-of-data"><span class="secno">6.3 </span>Sensitivity of data</h3><p>User agents should treat persistently stored data as potentially
+ user's attempts to protect his privacy.<h3 id="sensitivity-of-data"><span class="secno">7.3 </span>Sensitivity of data</h3><p>User agents should treat persistently stored data as potentially
sensitive; it's quite possible for e-mails, calendar appointments,
health records, or other confidential documents to be stored in this
mechanism.<p>To this end, user agents should ensure that when deleting data,
- it is promptly deleted from the underlying storage.<h2 id="security"><span class="secno">7 </span>Security</h2><h3 id="dns-spoofing-attacks"><span class="secno">7.1 </span>DNS spoofing attacks</h3><p>Because of the potential for DNS spoofing attacks, one cannot
+ it is promptly deleted from the underlying storage.<h2 id="security"><span class="secno">8 </span>Security</h2><h3 id="dns-spoofing-attacks"><span class="secno">8.1 </span>DNS spoofing attacks</h3><p>Because of the potential for DNS spoofing attacks, one cannot
guarantee that a host claiming to be in a certain domain really is
from that domain. To mitigate this, pages can use SSL. Pages using
SSL can be sure that only pages using SSL that have certificates
identifying them as being from the same domain can access their
databases.
- <h3 id="cross-directory-attacks"><span class="secno">7.2 </span>Cross-directory attacks</h3><p>Different authors sharing one host name, for example users
+ <h3 id="cross-directory-attacks"><span class="secno">8.2 </span>Cross-directory attacks</h3><p>Different authors sharing one host name, for example users
hosting content on <code>geocities.com</code>, all share one
set of databases.
@@ -1266,7 +1230,7 @@
and overwrite it.<p class="note">Even if a path-restriction feature was made
available, the usual DOM scripting security model would make it
trivial to bypass this protection and access the data from any
- path.<h3 id="implementation-risks"><span class="secno">7.3 </span>Implementation risks</h3><p>The two primary risks when implementing these persistent storage
+ path.<h3 id="implementation-risks"><span class="secno">8.3 </span>Implementation risks</h3><p>The two primary risks when implementing these persistent storage
features are letting hostile sites read information from other
domains, and letting hostile sites write information that is then
read from other domains.<p>Letting third-party sites read data that is not supposed to be
@@ -1280,14 +1244,14 @@
user's wishlist; or a hostile site could set a user's session
identifier to a known ID that the hostile site can then use to track
the user's actions on the victim site.<p>Thus, strictly following the <span>origin</span> model described
- in this specification is important for user security.<h3 id="sql-and-user-agents"><span class="secno">7.4 </span>SQL and user agents</h3><p>User agent implementors are strongly encouraged to audit all
+ in this specification is important for user security.<h3 id="sql-and-user-agents"><span class="secno">8.4 </span>SQL and user agents</h3><p>User agent implementors are strongly encouraged to audit all
their supported SQL statements for security implications. For
example, <code title="">LOAD DATA INFILE</code> is likely to pose
security risks and there is little reason to support it.<p>In general, it is recommended that user agents not support
features that control how databases are stored on disk. For example,
there is little reason to allow Web authors to control the character
encoding used in the disk representation of the data, as all data in
- JavaScript is implicitly UTF-16.<h3 id="sql-injection"><span class="secno">7.5 </span>SQL injection</h3><p>Authors are strongly recommended to make use of the <code title="">?</code> placeholder feature of the <code title="dom-sqltransaction-executeSql"><a href="#dom-sqltransaction-executesql">executeSql()</a></code> method,
+ JavaScript is implicitly UTF-16.<h3 id="sql-injection"><span class="secno">8.5 </span>SQL injection</h3><p>Authors are strongly recommended to make use of the <code title="">?</code> placeholder feature of the <code title="dom-sqltransaction-executeSql"><a href="#dom-sqltransaction-executesql">executeSql()</a></code> method,
and to never construct SQL statements on the fly.<h2 class="no-num" id="references">References</h2><p>All references are normative unless marked "Non-normative".<dl><dt id="refsCOOKIES">[COOKIES]</dt>
<!--
<dd><cite><a href="http://www.ietf.org/rfc/rfc2965.txt">HTTP State Management