--- a/Overview.html Tue Jan 22 18:11:06 2013 -0600
+++ b/Overview.html Fri Jan 25 10:22:21 2013 -0600
@@ -1,8 +1,8 @@
<!DOCTYPE html>
-<html lang="en" dir="ltr">
-<head>
+<html>
+ <head>
<title>WebCrypto High-level API</title>
- <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+ <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<style>
table {
border-collapse: collapse;
@@ -40,533 +40,72 @@
For the three scripts below, if your spec resides on dev.w3 you can check them
out in the same tree and use relative links so that they'll work offline,
-->
-
-
- <style>/*****************************************************************
- * ReSpec 3 CSS
- * Robin Berjon - http://berjon.com/
- *****************************************************************/
-
-/* --- INLINES --- */
-em.rfc2119 {
- text-transform: lowercase;
- font-variant: small-caps;
- font-style: normal;
- color: #900;
-}
-
-h1 acronym, h2 acronym, h3 acronym, h4 acronym, h5 acronym, h6 acronym, a acronym,
-h1 abbr, h2 abbr, h3 abbr, h4 abbr, h5 abbr, h6 abbr, a abbr {
- border: none;
-}
-
-dfn {
- font-weight: bold;
-}
-
-a.internalDFN {
- color: inherit;
- border-bottom: 1px solid #99c;
- text-decoration: none;
-}
-
-a.externalDFN {
- color: inherit;
- border-bottom: 1px dotted #ccc;
- text-decoration: none;
-}
-
-a.bibref {
- text-decoration: none;
-}
-
-cite .bibref {
- font-style: normal;
-}
-
-code {
- color: #ff4500;
-}
-
-
-/* --- --- */
-ol.algorithm { counter-reset:numsection; list-style-type: none; }
-ol.algorithm li { margin: 0.5em 0; }
-ol.algorithm li:before { font-weight: bold; counter-increment: numsection; content: counters(numsection, ".") ") "; }
-
-/* --- TOC --- */
-.toc a, .tof a {
- text-decoration: none;
-}
-
-a .secno, a .figno {
- color: #000;
-}
-
-ul.tof, ol.tof {
- list-style: none outside none;
-}
-
-.caption {
- margin-top: 0.5em;
- font-style: italic;
-}
-
-/* --- TABLE --- */
-table.simple {
- border-spacing: 0;
- border-collapse: collapse;
- border-bottom: 3px solid #005a9c;
-}
-
-.simple th {
- background: #005a9c;
- color: #fff;
- padding: 3px 5px;
- text-align: left;
-}
-
-.simple th[scope="row"] {
- background: inherit;
- color: inherit;
- border-top: 1px solid #ddd;
-}
-
-.simple td {
- padding: 3px 10px;
- border-top: 1px solid #ddd;
-}
-
-.simple tr:nth-child(even) {
- background: #f0f6ff;
-}
-
-/* --- DL --- */
-.section dd > p:first-child {
- margin-top: 0;
-}
-
-.section dd > p:last-child {
- margin-bottom: 0;
-}
-
-.section dd {
- margin-bottom: 1em;
-}
-
-.section dl.attrs dd, .section dl.eldef dd {
- margin-bottom: 0;
-}
-</style><style>/* --- EXAMPLES --- */
-div.example-title {
- min-width: 7.5em;
- color: #b9ab2d;
-}
-div.example-title span {
- text-transform: uppercase;
-}
-aside.example, div.example, div.illegal-example {
- padding: 0.5em;
- margin: 1em 0;
- position: relative;
- clear: both;
-}
-div.illegal-example { color: red }
-div.illegal-example p { color: black }
-aside.example, div.example {
- padding: .5em;
- border-left-width: .5em;
- border-left-style: solid;
- border-color: #e0cb52;
- background: #fcfaee;
-}
-
-aside.example div.example {
- border-left-width: .1em;
- border-color: #999;
- background: #fff;
-}
-aside.example div.example div.example-title {
- color: #999;
-}
-</style><style>/* HIGHLIGHTS */
-code.prettyprint {
- color: inherit;
-}
-
-/* this from google-code-prettify */
-.pln{color:#000}@media screen{.str{color:#080}.kwd{color:#008}.com{color:#800}.typ{color:#606}.lit{color:#066}.pun,.opn,.clo{color:#660}.tag{color:#008}.atn{color:#606}.atv{color:#080}.dec,.var{color:#606}.fun{color:red}}@media print,projection{.str{color:#060}.kwd{color:#006;font-weight:bold}.com{color:#600;font-style:italic}.typ{color:#404;font-weight:bold}.lit{color:#044}.pun,.opn,.clo{color:#440}.tag{color:#006;font-weight:bold}.atn{color:#404}.atv{color:#060}}ol.linenums{margin-top:0;margin-bottom:0}li.L0,li.L1,li.L2,li.L3,li.L5,li.L6,li.L7,li.L8{list-style-type:none}li.L1,li.L3,li.L5,li.L7,li.L9{background:#eee}
-</style><style>/* --- WEB IDL --- */
-pre.idl {
- border-top: 1px solid #90b8de;
- border-bottom: 1px solid #90b8de;
- padding: 1em;
- line-height: 120%;
-}
-
-pre.idl::before {
- content: "WebIDL";
- display: block;
- width: 150px;
- background: #90b8de;
- color: #fff;
- font-family: initial;
- padding: 3px;
- font-weight: bold;
- margin: -1em 0 1em -1em;
-}
-
-.idlType {
- color: #ff4500;
- font-weight: bold;
- text-decoration: none;
-}
-
-/*.idlModule*/
-/*.idlModuleID*/
-/*.idlInterface*/
-.idlInterfaceID, .idlDictionaryID, .idlCallbackID, .idlEnumID {
- font-weight: bold;
- color: #005a9c;
-}
-
-.idlSuperclass {
- font-style: italic;
- color: #005a9c;
-}
-
-/*.idlAttribute*/
-.idlAttrType, .idlFieldType, .idlMemberType {
- color: #005a9c;
-}
-.idlAttrName, .idlFieldName, .idlMemberName {
- color: #ff4500;
-}
-.idlAttrName a, .idlFieldName a, .idlMemberName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlMethod*/
-.idlMethType, .idlCallbackType {
- color: #005a9c;
-}
-.idlMethName {
- color: #ff4500;
-}
-.idlMethName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlParam*/
-.idlParamType {
- color: #005a9c;
-}
-.idlParamName, .idlDefaultValue {
- font-style: italic;
-}
-
-.extAttr {
- color: #666;
-}
-
-/*.idlConst*/
-.idlConstType {
- color: #005a9c;
-}
-.idlConstName {
- color: #ff4500;
-}
-.idlConstName a {
- color: #ff4500;
- border-bottom: 1px dotted #ff4500;
- text-decoration: none;
-}
-
-/*.idlException*/
-.idlExceptionID {
- font-weight: bold;
- color: #c00;
-}
-
-.idlTypedefID, .idlTypedefType {
- color: #005a9c;
-}
-
-.idlRaises, .idlRaises a.idlType, .idlRaises a.idlType code, .excName a, .excName a code {
- color: #c00;
- font-weight: normal;
-}
-
-.excName a {
- font-family: monospace;
-}
-
-.idlRaises a.idlType, .excName a.idlType {
- border-bottom: 1px dotted #c00;
-}
-
-.excGetSetTrue, .excGetSetFalse, .prmNullTrue, .prmNullFalse, .prmOptTrue, .prmOptFalse {
- width: 45px;
- text-align: center;
-}
-.excGetSetTrue, .prmNullTrue, .prmOptTrue { color: #0c0; }
-.excGetSetFalse, .prmNullFalse, .prmOptFalse { color: #c00; }
-
-.idlImplements a {
- font-weight: bold;
-}
-
-dl.attributes, dl.methods, dl.constants, dl.fields, dl.dictionary-members {
- margin-left: 2em;
-}
-
-.attributes dt, .methods dt, .constants dt, .fields dt, .dictionary-members dt {
- font-weight: normal;
-}
-
-.attributes dt code, .methods dt code, .constants dt code, .fields dt code, .dictionary-members dt code {
- font-weight: bold;
- color: #000;
- font-family: monospace;
-}
-
-.attributes dt code, .fields dt code, .dictionary-members dt code {
- background: #ffffd2;
-}
-
-.attributes dt .idlAttrType code, .fields dt .idlFieldType code, .dictionary-members dt .idlMemberType code {
- color: #005a9c;
- background: transparent;
- font-family: inherit;
- font-weight: normal;
- font-style: italic;
-}
-
-.methods dt code {
- background: #d9e6f8;
-}
-
-.constants dt code {
- background: #ddffd2;
-}
-
-.attributes dd, .methods dd, .constants dd, .fields dd, .dictionary-members dd {
- margin-bottom: 1em;
-}
-
-table.parameters, table.exceptions {
- border-spacing: 0;
- border-collapse: collapse;
- margin: 0.5em 0;
- width: 100%;
-}
-table.parameters { border-bottom: 1px solid #90b8de; }
-table.exceptions { border-bottom: 1px solid #deb890; }
-
-.parameters th, .exceptions th {
- color: #fff;
- padding: 3px 5px;
- text-align: left;
- font-family: initial;
- font-weight: normal;
- text-shadow: #666 1px 1px 0;
-}
-.parameters th { background: #90b8de; }
-.exceptions th { background: #deb890; }
-
-.parameters td, .exceptions td {
- padding: 3px 10px;
- border-top: 1px solid #ddd;
- vertical-align: top;
-}
-
-.parameters tr:first-child td, .exceptions tr:first-child td {
- border-top: none;
-}
-
-.parameters td.prmName, .exceptions td.excName, .exceptions td.excCodeName {
- width: 100px;
-}
-
-.parameters td.prmType {
- width: 120px;
-}
-
-table.exceptions table {
- border-spacing: 0;
- border-collapse: collapse;
- width: 100%;
-}
-</style><link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet"><!--[if lt IE 9]><script src='http://www.w3.org/2008/site/js/html5shiv.js'></script><![endif]--></head>
- <body><div class="head">
- <p>
-
- <a href="http://www.w3.org/"><img src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48" width="72"></a>
-
- </p>
- <h1 class="title" id="title">WebCrypto High-level API</h1>
-
- <h2 id="w3c-working-draft-22-january-2013"><abbr title="World Wide Web Consortium">W3C</abbr> Working Draft 22 January 2013</h2>
- <dl>
-
- <dt>This version:</dt>
- <dd><a href="http://www.w3.org/TR/2013/WD-webcrypto-high-level-api-20130122/">http://www.w3.org/TR/2013/WD-webcrypto-high-level-api-20130122/</a></dd>
- <dt>Latest published version:</dt>
- <dd><a href="http://www.w3.org/TR/webcrypto-high-level-api/">http://www.w3.org/TR/webcrypto-high-level-api/</a></dd>
-
-
- <dt>Latest editor's draft:</dt>
- <dd><a href="http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/high-level-Overview.html">http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/high-level-Overview.html</a></dd>
-
-
-
-
-
- <dt>Previous version:</dt>
- <dd><a href=""></a></dd>
-
-
- <dt>Editor:</dt>
- <dd><span>David Dahl</span>, <a href="http://www.mozilla.org/">Mozilla Foundation</a>, <span class="ed_mailto"><a href="mailto:ddahl@mozilla.com">ddahl@mozilla.com</a></span></dd>
-
-
- </dl>
-
-
-
-
-
- <p class="copyright">
- <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> ©
- 2013
-
- <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>®</sup>
- (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>,
- <a href="http://www.ercim.eu/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>,
- <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved.
- <abbr title="World Wide Web Consortium">W3C</abbr> <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
- <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and
- <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.
- </p>
-
-
- <hr>
-</div>
- <section class="introductory" id="abstract"><h2>Abstract</h2>
+ <script src='http://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
+ <script type="text/javascript" class='remove'>
+ var respecConfig = { specStatus: "WD",
+ shortName: "webcrypto-high-level-api",
+ editors: [{ name: "David Dahl",
+ mailto: "ddahl@mozilla.com",
+ company: "Mozilla Corporation",
+ companyURL: "http://www.mozilla.org/"} ],
+ publishDate: "2013-01-25",
+ previousPublishDate: "2013-01-22",
+ // edEnd: "",
+ previousMaturity: "ED",
+ edDraftURI: "https://dvcs.w3.org/hg/webcrypto-highlevel/raw-file/tip/Overview.html",
+ wg: "Web Cryptography WG",
+ wgURI: "http://www.w3.org/2012/webcrypto/",
+ wgPublicList: "public-webcrypto",
+ wgPatentURI: "http://www.w3.org/2004/01/pp-impl/54174/status",
+ localBiblio : { "WEBCRYPTO" : "Ryan Sleevi, David Dahl. <a href=\"http://www.w3.org/TR/WebCryptoAPI/\"><cite>Web Cryptography API.</cite></a> W3C Working Draft (Work in progress.) URL: <a href=\"http://www.w3.org/TR/WebCryptoAPI/\">http://www.w3.org/TR/WebCryptoAPI/</a> "}
+ };
+ </script>
+ </head>
+ <body>
+ <section id='abstract'>
<p>This specification describes a JavaScript API for public key generation, encryption, decryption, digital signature generation and verification, and hashing.
</p>
- </section><section id="sotd" class="introductory"><h2>Status of This Document</h2>
-
-
-
- <p>
- <em>This section describes the status of this document at the time of its publication. Other
- documents may supersede this document. A list of current <abbr title="World Wide Web Consortium">W3C</abbr> publications and the latest revision
- of this technical report can be found in the <a href="http://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports
- index</a> at http://www.w3.org/TR/.</em>
- </p>
-
- <p>This document is the First Public Working Draft of the WebCrypto High-level API recommendation. It defines an API that provides access to named origin-specific pre-provisioned keys.</p>
-
- <p>
- This document was published by the <a href="http://www.w3.org/2012/webcrypto/">Web Cryptography WG</a> as a Working Draft.
-
- This document is intended to become a <abbr title="World Wide Web Consortium">W3C</abbr> Recommendation.
-
-
- If you wish to make comments regarding this document, please send them to
- <a href="mailto:public-webcrypto@w3.org">public-webcrypto@w3.org</a>
- (<a href="mailto:public-webcrypto-request@w3.org?subject=subscribe">subscribe</a>,
- <a href="http://lists.w3.org/Archives/Public/public-webcrypto/">archives</a>).
-
-
-
-
- All comments are welcome.
-
-
- </p><p>
- Publication as a Working Draft does not imply endorsement by the <abbr title="World Wide Web Consortium">W3C</abbr> Membership.
- This is a draft document and may be updated, replaced or obsoleted by other documents at
- any time. It is inappropriate to cite this document as other than work in progress.
- </p>
-
-
- <p>
-
- This document was produced by a group operating under the
- <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February 2004 <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
-
-
-
-
- <abbr title="World Wide Web Consortium">W3C</abbr> maintains a <a href="http://www.w3.org/2004/01/pp-impl/54174/status" rel="disclosure">public list of any patent disclosures</a>
-
- made in connection with the deliverables of the group; that page also includes instructions for
- disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains
- <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential Claim(s)</a> must disclose the
- information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
- 6 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>.
-
-
- </p>
-
-
-
-
-</section><section id="toc"><h2 class="introductory">Table of Contents</h2><ul class="toc"><li class="tocline"><a class="tocxref" href="#introduction"><span class="secno">1. </span>Introduction</a></li><li class="tocline"><a class="tocxref" href="#use-cases"><span class="secno">2. </span>Use cases</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#security-of-data-at-rest"><span class="secno">2.1 </span>Security of data at rest</a></li><li class="tocline"><a class="tocxref" href="#web-based-messaging"><span class="secno">2.2 </span>Web-based messaging</a></li></ul></li><li class="tocline"><a class="tocxref" href="#conformance"><span class="secno">3. </span>Conformance</a></li><li class="tocline"><a class="tocxref" href="#scope"><span class="secno">4. </span>Scope</a></li><li class="tocline"><a class="tocxref" href="#privacy-considerations"><span class="secno">5. </span>Privacy considerations</a><ul class="toc"></ul></li><li class="tocline"><a class="tocxref" href="#dependencies"><span class="secno">6. </span>Dependencies</a></li><li class="tocline"><a class="tocxref" href="#api-definition"><span class="secno">7. </span>API definition</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#overview"><span class="secno">7.1 </span>Overview</a></li><li class="tocline"><a class="tocxref" href="#extension-of-crypto-interface"><span class="secno">7.2 </span>Extension of Crypto interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes"><span class="secno">7.2.1 </span>Attributes</a></li></ul></li><li class="tocline"><a class="tocxref" href="#highlevel-interface"><span class="secno">7.3 </span>Highlevel interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-1"><span class="secno">7.3.1 </span>Attributes</a></li><li class="tocline"><a class="tocxref" href="#methods"><span class="secno">7.3.2 </span>Methods</a></li></ul></li><li class="tocline"><a class="tocxref" href="#extension-of-workerglobalscope-interface"><span class="secno">7.4 </span>Extension of WorkerGlobalScope interface</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#attributes-2"><span class="secno">7.4.1 </span>Attributes</a></li></ul></li></ul></li><li class="tocline"><a class="tocxref" href="#examples"><span class="secno">8. </span>Examples</a></li><li class="tocline"><a class="tocxref" href="#references"><span class="secno">A. </span>References</a><ul class="toc"><li class="tocline"><a class="tocxref" href="#normative-references"><span class="secno">A.1 </span>Normative references</a></li></ul></li></ul></section>
-
-
-
- <section id="introduction" class="informative">
- <!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This section is non-normative.</em></p>
- <p>
- The Web Cryptography API [<cite><a href="#bib-WEBCRYPTO" class="bibref">WEBCRYPTO</a></cite>] describes a JavaScript API for performing basic cryptographic operations in web applications. The Web Cryoptography API is not a simple API geared towards the average web developer, rather its use requires near-expert knowledge of cryptography. The 'High-level' API described here is designed around fewer use cases and is not concerned with backward-compatibility with existing crypto systems and protocols.
- </p>
</section>
- <section id="use-cases">
- <!--OddPage--><h2><span class="secno">2. </span>Use cases</h2>
- <section id="security-of-data-at-rest">
- <h3><span class="secno">2.1 </span>Security of data at rest</h3>
- <p>TBD</p>
+ <section id="sotd">
+ <p>This document is the First Public Working Draft of the WebCrypto High-level API recommendation. It defines an API that provides access to named origin-specific pre-provisioned keys.</p>
+ </section>
+
+ <section class="informative">
+ <h2>Introduction</h2>
+ <p>
+ The Web Cryptography API [[!WEBCRYPTO]] describes a JavaScript API for performing basic cryptographic operations in web applications. The Web Cryoptography API is not a simple API geared towards the average web developer, rather its use requires near-expert knowledge of cryptography. The 'High-level' API described here is designed around fewer use cases and is not concerned with backward-compatibility with existing crypto systems and protocols. This API leverages the IETF JOSE JWA, JWK and JWE JSON formats for algorithms, public keys and cipher data.
+ </p>
+ </section>
+
+ <section>
+ <h2>Use cases</h2>
+ <section>
+ <h3>Security of data at rest</h3>
+ <p>TODO</p>
</section>
- <section id="web-based-messaging">
- <h3><span class="secno">2.2 </span>Web-based messaging</h3>
- <p>TBD</p>
+ <section>
+ <h3>Web-based messaging</h3>
+ <p>TODO</p>
</section>
</section>
- <section id="conformance"><!--OddPage--><h2><span class="secno">3. </span>Conformance</h2>
-<p>
- As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
- and notes in this specification are non-normative. Everything else in this specification is
- normative.
-</p>
-<p>
- The key words <em title="must" class="rfc2119">must</em>, <em title="must not" class="rfc2119">must not</em>, <em title="required" class="rfc2119">required</em>, <em title="should" class="rfc2119">should</em>, <em title="should not" class="rfc2119">should not</em>, <em title="recommended" class="rfc2119">recommended</em>, <em title="may" class="rfc2119">may</em>,
- and <em title="optional" class="rfc2119">optional</em> in this specification are to be interpreted as described in [<cite><a href="#bib-RFC2119" class="bibref">RFC2119</a></cite>].
-</p>
-
+ <section id="conformance">
<p>
The following conformance classes are defined by this specification:
</p>
<dl>
- <dt><dfn id="dfn-conforming-user-agent">conforming user agent</dfn></dt>
+ <dt><dfn>conforming user agent</dfn></dt>
<dd>
<p>
A user agent is considered to be a conforming user agent
- if it satisfies all of the <em title="must" class="rfc2119">must</em>-, <em title="required" class="rfc2119">required</em>- and <em title="shall" class="rfc2119">shall</em>-level
+ if it satisfies all of the MUST-, REQUIRED- and SHALL-level
criteria in this specification that apply to implementation. This specification
uses both the terms "conforming user agent" and "user agent" to refer to this
product class.
</p>
<p>
- User agents <em title="may" class="rfc2119">may</em> implement algorithms in this
+ User agents MAY implement algorithms in this
specification in any way desired, so long as the end result is indistinguishable
from the result that would be obtained from the specification's algorithms.
</p>
@@ -574,21 +113,21 @@
</dl>
<p>
User agents that use ECMAScript to implement the APIs defined in this specification
- <em title="must" class="rfc2119">must</em> implement them in a manner consistent with the
- ECMAScript Bindings defined in the Web IDL specification [<cite><a href="#bib-WEBIDL" class="bibref">WEBIDL</a></cite>]
+ MUST implement them in a manner consistent with the
+ ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]]
as this specification uses that specification and terminology.
</p>
</section>
<section id="scope" class="informative">
- <!--OddPage--><h2><span class="secno">4. </span>Scope</h2><p><em>This section is non-normative.</em></p>
- <p>The considerations in the Scope section of [<cite><a href="#bib-WEBCRYPTO" class="bibref">WEBCRYPTO</a></cite>] apply to this specification as well.
+ <h2>Scope</h2>
+ <p>The considerations in the Scope section of [[!WEBCRYPTO]] apply to this specification as well.
</p>
</section>
- <section id="privacy-considerations" class="informative">
- <!--OddPage--><h2><span class="secno">5. </span>Privacy considerations</h2><p><em>This section is non-normative.</em></p>
- <p>The Privacy considerations of [<cite><a href="#bib-WEBCRYPTO" class="bibref">WEBCRYPTO</a></cite>] apply to this specification.</p>
+ <section class="informative">
+ <h2>Privacy considerations</h2>
+ <p>The Privacy considerations of [[!WEBCRYPTO]] apply to this specification.</p>
<section>
<p>
TBD
@@ -597,161 +136,231 @@
</section>
<section class="section" id="dependencies">
- <!--OddPage--><h2><span class="secno">6. </span>Dependencies</h2>
+ <h3>Dependencies</h3>
<p>
This specification relies on several other underlying specifications.
</p>
<dl>
<dt>HTML5</dt>
<dd>The terms and algorithms
- <dfn id="dfn-window" title="Window"><code>Window</code></dfn>,
- <dfn id="dfn-function" title="Function"><code>Function</code></dfn>,
- <dfn id="dfn-origin">origin</dfn>, <dfn id="dfn-same-origin">same origin</dfn>, <dfn id="dfn-structured-clone">structured clone</dfn>,
- <dfn id="dfn-structured-clone-algorithm">structured clone algorithm</dfn>, <dfn id="dfn-task">task</dfn>, <dfn id="dfn-task-source">task source</dfn>,
- <dfn id="dfn-queue-a-task" title="queue-a-task">queue a task</dfn>
- and <dfn id="dfn-fire-a-simple-event" title="fire-a-simple-event">fire a simple event</dfn> are defined by the HTML 5
- specification [<cite><a href="#bib-HTML5" class="bibref">HTML5</a></cite>].
+ <dfn title="Window"><code>Window</code></dfn>,
+ <dfn title="Function"><code>Function</code></dfn>,
+ <dfn>origin</dfn>, <dfn>same origin</dfn>, <dfn>structured clone</dfn>,
+ <dfn>structured clone algorithm</dfn>, <dfn>task</dfn>, <dfn>task source</dfn>,
+ <dfn title="queue-a-task">queue a task</dfn>
+ and <dfn title="fire-a-simple-event">fire a simple event</dfn> are defined by the HTML 5
+ specification [[!HTML5]].
</dd>
<dt>WebIDL</dt>
- <dd>Many of the interface definitions and all of the IDL in this spec depends on [<cite><a href="#bib-WEBIDL" class="bibref">WEBIDL</a></cite>].</dd>
+ <dd>Many of the interface definitions and all of the IDL in this spec depends on [[!WEBIDL]].</dd>
<dt>WebWorkers</dt>
- <dd>The term <dfn id="dfn-workerglobalscope" title="WorkerGlobalScope"><a class="externalDFN"><code>WorkerGlobalScope</code></a></dfn> is defined by
- the WebWorkers specification [<cite><a href="#bib-WEBWORKERS" class="bibref">WEBWORKERS</a></cite>].</dd>
+ <dd>The term <dfn title="WorkerGlobalScope"><a class="externalDFN"><code>WorkerGlobalScope</code></a></dfn> is defined by
+ the WebWorkers specification [[!WEBWORKERS]].</dd>
</dl>
</section>
- <section id="api-definition">
- <!--OddPage--><h2><span class="secno">7. </span>API definition</h2>
- <section id="overview" class="informative">
- <h3><span class="secno">7.1 </span>Overview</h3><p><em>This section is non-normative.</em></p>
- <p>This specification defines a new <a><code>highlevel</code></a> attribute on the <a><code>Window.crypto</code></a> and <a class="internalDFN" href="#dfn-workerglobalscope"><code>WorkerGlobalScope</code></a> objects.
- </p></section>
+ <section>
+ <h2>API definition</h2>
+ <section class="informative">
+ <h3>Overview</h3>
+ <p>This specification defines a new <a><code>highlevel</code></a> attribute on the <a><code>Window.crypto</code></a> and <a><code>WorkerGlobalScope</code></a> objects.
+ </section>
- <section id="extension-of-crypto-interface">
- <h3><span class="secno">7.2 </span>Extension of Crypto interface</h3>
- <pre class="idl"><span class="idlInterface" id="idl-def-Crypto">partial interface <span class="idlInterfaceID">Crypto</span> {
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-Highlevel"><code>Highlevel</code></a></span> <span class="idlAttrName"><a href="#widl-Crypto-highlevel">highlevel</a></span>;</span>
-};</span></pre><section id="attributes"><h4><span class="secno">7.2.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-Crypto-highlevel"><code>highlevel</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-Highlevel"><code>Highlevel</code></a></span>, readonly</dt><dd>The object that exposes the high-level API</dd></dl></section>
+ <section>
+ <h3>Extension of Crypto interface</h3>
+ <dl title="partial interface Crypto" class="idl">
+ <dt>readonly attribute Highlevel highlevel</dt>
+ <dd>The object that exposes the high-level API</dd>
+ </dl>
</section>
- <section id="highlevel-interface">
- <h3><span class="secno">7.3 </span>Highlevel interface</h3>
- <pre class="idl"><span class="idlInterface" id="idl-def-Highlevel">interface <span class="idlInterfaceID">Highlevel</span> {
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-getPublicKey-void-DOMString-aJWKID">getPublicKey</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aJWKID</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onGetKeypair">onGetKeypair</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-createKeyPair-void-DOMString-aJoseAlgID">createKeyPair</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aJoseAlgID</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onCreateKeypair">onCreateKeypair</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-encryptAndSign-void-ArrayBuffer-aClearData-DOMString-aRecipientJWK-DOMString-aSenderJWKID">encryptAndSign</a></span> (<span class="idlParam"><span class="idlParamType"><a>ArrayBuffer</a></span> <span class="idlParamName">aClearData</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aRecipientJWK</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aSenderJWKID</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onEncryptComplete">onEncryptComplete</a></span>;</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onEncryptError">onEncryptError</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-verifyAndDecrypt-void-DOMString-aReceivedJWE-DOMString-aSenderJWK-DOMString-aRecipientJWKID">verifyAndDecrypt</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aReceivedJWE</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aSenderJWK</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aRecipientJWKID</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onDecryptComplete">onDecryptComplete</a></span>;</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onDecryptError">onDecryptError</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-sign-void-aDOMString-aClearData-DOMString-aJWKID">sign</a></span> (<span class="idlParam"><span class="idlParamType"><a>aDOMString</a></span> <span class="idlParamName">aClearData</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aJWKID</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onSignComplete">onSignComplete</a></span>;</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onSignError">onSignError</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-verify-void-DOMString-aJWS-DOMString-aDataToVerify-DOMString-aJWK">verify</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aJWS</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aDataToVerify</span></span>, <span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aJWK</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onVerifyComplete">onVerifyComplete</a></span>;</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onVerifyError">onVerifyError</a></span>;</span>
-<span class="idlMethod"> <span class="idlMethType"><a>void</a></span> <span class="idlMethName"><a href="#widl-Highlevel-hash-void-DOMString-aData">hash</a></span> (<span class="idlParam"><span class="idlParamType"><a>DOMString</a></span> <span class="idlParamName">aData</span></span>);</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onHashComplete">onHashComplete</a></span>;</span>
-<span class="idlAttribute"> [<span class="extAttr">TreatNonCallableAsNull</span>]
- attribute <span class="idlAttrType"><a>Function</a>?</span> <span class="idlAttrName"><a href="#widl-Highlevel-onHashError">onHashError</a></span>;</span>
-};</span></pre><section id="attributes-1"><h4><span class="secno">7.3.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-Highlevel-onCreateKeypair"><code>onCreateKeypair</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onCreateKeypair event handler</dd><dt id="widl-Highlevel-onDecryptComplete"><code>onDecryptComplete</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onDecryptComplete event handler</dd><dt id="widl-Highlevel-onDecryptError"><code>onDecryptError</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onDecryptError event handler</dd><dt id="widl-Highlevel-onEncryptComplete"><code>onEncryptComplete</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onEncryptComplete event handler</dd><dt id="widl-Highlevel-onEncryptError"><code>onEncryptError</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onEncryptError event handler</dd><dt id="widl-Highlevel-onGetKeypair"><code>onGetKeypair</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onGetKeypair event handler</dd><dt id="widl-Highlevel-onHashComplete"><code>onHashComplete</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onHashComplete event handler</dd><dt id="widl-Highlevel-onHashError"><code>onHashError</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onHashError event handler</dd><dt id="widl-Highlevel-onSignComplete"><code>onSignComplete</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onSignComplete event handler</dd><dt id="widl-Highlevel-onSignError"><code>onSignError</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onSignError event handler</dd><dt id="widl-Highlevel-onVerifyComplete"><code>onVerifyComplete</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onVerifyComplete event handler</dd><dt id="widl-Highlevel-onVerifyError"><code>onVerifyError</code> of type <span class="idlAttrType"><a>Function</a></span>, nullable</dt><dd>onVerifyError event handler</dd></dl></section><section id="methods"><h4><span class="secno">7.3.2 </span>Methods</h4><dl class="methods"><dt id="widl-Highlevel-createKeyPair-void-DOMString-aJoseAlgID"><code>createKeyPair</code></dt><dd>Generate a public keypair<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aJoseAlgID</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Highlevel-encryptAndSign-void-ArrayBuffer-aClearData-DOMString-aRecipientJWK-DOMString-aSenderJWKID"><code>encryptAndSign</code></dt><dd>Perform encryption, signing the encrypted data<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aClearData</td><td class="prmType"><code><a>ArrayBuffer</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aRecipientJWK</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aSenderJWKID</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Highlevel-getPublicKey-void-DOMString-aJWKID"><code>getPublicKey</code></dt><dd>Get public key by an ID if it exists<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aJWKID</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Highlevel-hash-void-DOMString-aData"><code>hash</code></dt><dd>Create a cryptographic hash<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aData</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Highlevel-sign-void-aDOMString-aClearData-DOMString-aJWKID"><code>sign</code></dt><dd>Create a digital signature<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aClearData</td><td class="prmType"><code><a>aDOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aJWKID</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Highlevel-verify-void-DOMString-aJWS-DOMString-aDataToVerify-DOMString-aJWK"><code>verify</code></dt><dd>Verify a digital signature<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aJWS</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aDataToVerify</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aJWK</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd><dt id="widl-Highlevel-verifyAndDecrypt-void-DOMString-aReceivedJWE-DOMString-aSenderJWK-DOMString-aRecipientJWKID"><code>verifyAndDecrypt</code></dt><dd>Verify signature and decrypttion method<table class="parameters"><tr><th>Parameter</th><th>Type</th><th>Nullable</th><th>Optional</th><th>Description</th></tr><tr><td class="prmName">aReceivedJWE</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aSenderJWK</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr><tr><td class="prmName">aRecipientJWKID</td><td class="prmType"><code><a>DOMString</a></code></td><td class="prmNullFalse">✘</td><td class="prmOptFalse">✘</td><td class="prmDesc"></td></tr></table><div><em>Return type: </em><code><a>void</a></code></div></dd></dl></section>
+ <section>
+ <h3>Highlevel interface</h3>
+ <dl title="interface Highlevel" class="idl">
+ <dt>void getPublicKey (in DOMString aJWKID)</dt>
+ <dd>Get public key by an ID if it exists</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onGetKeypair</dt>
+ <dd>onGetKeypair event handler</dd>
+ <dt>void createKeyPair (in DOMString aJoseAlgID)</dt>
+ <dd>Generate a public keypair</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onCreateKeypair</dt>
+ <dd>onCreateKeypair event handler</dd>
+
+ <dt>void encryptAndSign (in DOMSring aPlainText, in DOMString aRecipientJWK, in DOMString aSenderJWKID)</dt>
+ <dd>Perform encryption, signing the encrypted data</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onEncryptComplete</dt>
+ <dd>onEncryptComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onEncryptError</dt>
+ <dd>onEncryptError event handler</dd>
+
+ <dt>void verifyAndDecrypt (in DOMString aReceivedJWE, in DOMString aSenderJWK, in DOMString aRecipientJWKID)</dt>
+ <dd>Verify signature and decrypttion method</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onDecryptComplete</dt>
+ <dd>onDecryptComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onDecryptError</dt>
+ <dd>onDecryptError event handler</dd>
+
+ <dt>void protect (in DOMString aPlainText, in DOMString aJWAlgID)</dt>
+ <dd>Symmetric encryption of a string (a key is generated on each use)</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onProtectComplete</dt>
+ <dd>onProtectComplete event handler, ciphertext and keyID are passed to this function</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onProtectError</dt>
+ <dd>onProtectError event handler</dd>
+
+ <dt>void unprotect (in DOMString aKeyID, in DOMString aPlainText)</dt>
+ <dd>Symmetric decryption of a string</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onUnprotectComplete</dt>
+ <dd>onUnprotectComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onUnprotectError</dt>
+ <dd>onUnprotectError event handler</dd>
+
+ <dt>void sign(in aDOMString aClearData, in DOMString aJWKID)</dt>
+ <dd>Create a digital signature</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onSignComplete</dt>
+ <dd>onSignComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onSignError</dt>
+ <dd>onSignError event handler</dd>
+
+ <dt>void verify (in DOMString aJWS, in DOMString aDataToVerify, in DOMString aJWK)</dt>
+ <dd>Verify a digital signature</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onVerifyComplete</dt>
+ <dd>onVerifyComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onVerifyError</dt>
+ <dd>onVerifyError event handler</dd>
+
+ <dt>void hash(in DOMString aData)</dt>
+ <dd>Create a cryptographic hash</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onHashComplete</dt>
+ <dd>onHashComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onHashError</dt>
+ <dd>onHashError event handler</dd>
+ </dl>
</section>
- <section id="extension-of-workerglobalscope-interface">
- <h3><span class="secno">7.4 </span>Extension of WorkerGlobalScope interface</h3>
- <pre class="idl"><span class="idlInterface" id="idl-def-WorkerGlobalScope">partial interface <span class="idlInterfaceID">WorkerGlobalScope</span> {
-<span class="idlAttribute"> readonly attribute <span class="idlAttrType"><a class="idlType" href="#idl-def-Highlevel"><code>Highlevel</code></a></span> <span class="idlAttrName"><a href="#widl-WorkerGlobalScope-highlevel">highlevel</a></span>;</span>
-};</span></pre><section id="attributes-2"><h4><span class="secno">7.4.1 </span>Attributes</h4><dl class="attributes"><dt id="widl-WorkerGlobalScope-highlevel"><code>highlevel</code> of type <span class="idlAttrType"><a class="idlType" href="#idl-def-Highlevel"><code>Highlevel</code></a></span>, readonly</dt><dd>The object that exposes the high-level API</dd></dl></section>
+ <section>
+ <h3>Extension of WorkerGlobalScope interface</h3>
+ <dl title="partial interface WorkerGlobalScope" class="idl">
+ <dt>readonly attribute Highlevel highlevel</dt>
+ <dd>The object that exposes the high-level API</dd>
+ </dl>
</section>
</section>
- <section id="examples">
- <!--OddPage--><h2><span class="secno">8. </span>Examples</h2>
- <h2 id="keypair-handling-generation">Keypair handling, generation</h2>
- <div class="example"><div class="example-title"><span>Example 1</span></div><pre class="example sh_sourceCode highlight prettyprint"><span class="kwd">var</span><span class="pln"> myCurrentKeyPair </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">null</span><span class="pun">;</span><span class="pln">
-
-</span><span class="kwd">function</span><span class="pln"> onGetKeypair</span><span class="pun">(</span><span class="pln">aKeypair</span><span class="pun">)</span><span class="pln">
-</span><span class="pun">{</span><span class="pln">
- localStorage</span><span class="pun">.</span><span class="pln">setItem</span><span class="pun">(</span><span class="pln">aKeypair</span><span class="pun">.</span><span class="pln">id</span><span class="pun">,</span><span class="pln"> aKeypair</span><span class="pun">.</span><span class="pln">publicKey</span><span class="pun">);</span><span class="pln">
-</span><span class="pun">}</span><span class="pln">
-
-</span><span class="kwd">var</span><span class="pln"> cryptoAPI </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">new</span><span class="pln"> window</span><span class="pun">.</span><span class="pln">crypto</span><span class="pun">.</span><span class="pln">highlevel</span><span class="pun">();</span><span class="pln">
-cryptoAPI</span><span class="pun">.</span><span class="pln">onGetKeypair </span><span class="pun">=</span><span class="pln"> onGetKeypair</span><span class="pun">;</span><span class="pln">
-
-</span><span class="kwd">function</span><span class="pln"> onCreateKeypair</span><span class="pun">(</span><span class="pln">aKeypair</span><span class="pun">)</span><span class="pln">
-</span><span class="pun">{</span><span class="pln">
- localStorage</span><span class="pun">.</span><span class="pln">setItem</span><span class="pun">(</span><span class="pln">aKeypair</span><span class="pun">.</span><span class="pln">id</span><span class="pun">,</span><span class="pln"> aKeypair</span><span class="pun">.</span><span class="pln">publicKey</span><span class="pun">);</span><span class="pln">
- myCurrentKeyPair </span><span class="pun">=</span><span class="pln"> aKeypair</span><span class="pun">;</span><span class="pln">
-</span><span class="pun">}</span><span class="pln">
-
-cryptoAPI</span><span class="pun">.</span><span class="pln">onCreateKeypair </span><span class="pun">=</span><span class="pln"> onCreateKeypair</span><span class="pun">;</span><span class="pln">
-
-cryptoAPI</span><span class="pun">.</span><span class="pln">createKeypair</span><span class="pun">(</span><span class="str">"RSA1_5"</span><span class="pun">);</span></pre></div>
- <h2 id="encryption">Encryption</h2>
-<div class="example"><div class="example-title"><span>Example 2</span></div><pre class="example sh_sourceCode highlight prettyprint"><span class="kwd">var</span><span class="pln"> plainText </span><span class="pun">=</span><span class="pln"> </span><span class="str">"The rain in Spain falls mainly on the plain."</span><span class="pun">;</span><span class="pln">
-
-</span><span class="kwd">function</span><span class="pln"> onEncryptComplete</span><span class="pun">(</span><span class="pln">aJWE</span><span class="pun">,</span><span class="pln"> aPublicKey</span><span class="pun">){</span><span class="pln">
- </span><span class="com">// send cipher data to the server for storage, etc...</span><span class="pln">
-</span><span class="pun">}</span><span class="pln">
-cryptoAPI</span><span class="pun">.</span><span class="pln">onEncryptComplete </span><span class="pun">=</span><span class="pln"> onEncryptComplete</span><span class="pun">;</span><span class="pln">
-cryptoAPI</span><span class="pun">.</span><span class="pln">encryptAndSign</span><span class="pun">(</span><span class="pln">plainText</span><span class="pun">,</span><span class="pln"> RECIPIENT_JWK</span><span class="pun">,</span><span class="pln"> SENDER_JWK_ID</span><span class="pun">);</span></pre></div>
-
-<h3 id="decryption">Decryption</h3>
-<div class="example"><div class="example-title"><span>Example 3</span></div><pre class="example sh_sourceCode highlight prettyprint"><span class="kwd">function</span><span class="pln"> onDecryptComplete</span><span class="pun">(</span><span class="pln">aPlainText</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// read and save plain text</span><span class="pln">
-</span><span class="pun">}</span><span class="pln">
+ <section>
+ <h2>Examples</h2>
+ <h3>Keypair handling, generation</h3>
+ <pre class="example sh_html sh_sourceCode">
+var myCurrentKeyPair = null;
-</span><span class="kwd">function</span><span class="pln"> onDecryptError</span><span class="pun">(</span><span class="pln">aException</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// examine exception raised, re-throw or throw a new error</span><span class="pln">
-</span><span class="pun">}</span><span class="pln">
-cryptoAPI</span><span class="pun">.</span><span class="pln">onDecryptError </span><span class="pun">=</span><span class="pln"> onDecryptError</span><span class="pun">;</span><span class="pln">
-
-</span><span class="com">// we have recvd a new cipher message...</span><span class="pln">
-</span><span class="com">// set the event handler</span><span class="pln">
-cryptoAPI</span><span class="pun">.</span><span class="pln">onDecryptComplete </span><span class="pun">=</span><span class="pln"> onDecryptComplete</span><span class="pun">;</span><span class="pln">
-</span><span class="com">// verfiy and decrypt - if verification or decryption fails, onDecryptError is fired</span><span class="pln">
-cryptoAPI</span><span class="pun">.</span><span class="pln">verifyAndDecrypt</span><span class="pun">(</span><span class="pln">RECEIVED_JWE</span><span class="pun">,</span><span class="pln"> SENDER_JWK</span><span class="pun">,</span><span class="pln"> RECIPIENT_JWK_ID</span><span class="pun">);</span></pre></div>
-
-<h3 id="signature-creation">Signature creation</h3>
-<div class="example"><div class="example-title"><span>Example 4</span></div><pre class="example sh_sourceCode highlight prettyprint"><span class="kwd">var</span><span class="pln"> dataToSign </span><span class="pun">=</span><span class="pln"> </span><span class="str">"This is some data to sign"</span><span class="pun">;</span><span class="pln">
-
-cryptoAPI</span><span class="pun">.</span><span class="pln">onSignComplete </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">(</span><span class="pln">aJWS</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// send the signature to the server, etc.</span><span class="pln">
-</span><span class="pun">};</span><span class="pln">
+function onGetKeypair(aKeypair)
+{
+ localStorage.setItem(aKeypair.id, aKeypair.publicKey);
+}
-cryptoAPI</span><span class="pun">.</span><span class="pln">onSignError </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">(</span><span class="pln">aError</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// console.log(), etc.</span><span class="pln">
-</span><span class="pun">};</span><span class="pln">
-
-cryptoAPI</span><span class="pun">.</span><span class="pln">sign</span><span class="pun">(</span><span class="pln">dataToSign</span><span class="pun">,</span><span class="pln"> JWK_ID</span><span class="pun">);</span></pre></div>
+var cryptoAPI = new window.crypto.highlevel();
+cryptoAPI.onGetKeypair = onGetKeypair;
-<h3 id="signature-verification">Signature Verification</h3>
-<div class="example"><div class="example-title"><span>Example 5</span></div><pre class="example sh_sourceCode highlight prettyprint"><span class="pln">cryptoAPI</span><span class="pun">.</span><span class="pln">onVerifyComplete </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">(</span><span class="pln">aVerified</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// aVerified is a boolean</span><span class="pln">
-</span><span class="pun">};</span><span class="pln">
+function onCreateKeypair(aKeypair)
+{
+ localStorage.setItem(aKeypair.id, aKeypair.publicKey);
+ myCurrentKeyPair = aKeypair;
+}
-cryptoAPI</span><span class="pun">.</span><span class="pln">onVerifyError </span><span class="pun">=</span><span class="pln"> </span><span class="kwd">function</span><span class="pln"> </span><span class="pun">(</span><span class="pln">aError</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln">
- </span><span class="com">// console.log(), etc.</span><span class="pln">
-</span><span class="pun">};</span><span class="pln">
+cryptoAPI.onCreateKeypair = onCreateKeypair;
-cryptoAPI</span><span class="pun">.</span><span class="pln">verify</span><span class="pun">(</span><span class="pln">RECEIVED_JWS</span><span class="pun">,</span><span class="pln"> SIGNER_JWK</span><span class="pun">);</span><span class="pln"> </span></pre></div>
+cryptoAPI.createKeypair("RSA1_5");
+</pre>
+ <h3>Public Key Encryption</h3>
+<pre class="example sh_html sh_sourceCode">
+var plainText = "The rain in Spain falls mainly on the plain.";
+
+function onEncryptComplete(aJWE, aPublicKey){
+ // send cipher data to the server for storage, etc...
+}
+cryptoAPI.onEncryptComplete = onEncryptComplete;
+cryptoAPI.encryptAndSign(plainText, RECIPIENT_JWK, SENDER_JWK_ID);
+</pre>
+
+<h3>Public Key Decryption</h3>
+<pre class="example sh_html sh_sourceCode">
+function onDecryptComplete(aPlainText) {
+ // read and save plain text
+}
+
+function onDecryptError(aException) {
+ // examine exception raised, re-throw or throw a new error
+}
+cryptoAPI.onDecryptError = onDecryptError;
+
+// we have recvd a new cipher message...
+// set the event handler
+cryptoAPI.onDecryptComplete = onDecryptComplete;
+// verfiy and decrypt - if verification or decryption fails, onDecryptError is fired
+cryptoAPI.verifyAndDecrypt(RECEIVED_JWE, SENDER_JWK, RECIPIENT_JWK_ID);
+</pre>
+
+<h3>Symmetric Encryption</h3>
+<pre class="example sh_html sh_sourceCode">
+function onProtectComplete(aCipherText, aKeyID) {
+ // cipher text and the key ID are provided to this event handler
+}
+
+function onProtectError(aException) {
+ // examine exception or error message
+}
+cryptoAPI.onProtectError = onProtectError;
+
+cryptoAPI.onProtectComplete = onProtectComplete;
+//
+cryptoAPI.protect("s3kr3t m355ag3", "A256GCM");
+</pre>
+
+<h3>Symmetric Decryption</h3>
+<pre class="example sh_html sh_sourceCode">
+function onUnprotectComplete(aPlainText) {
+ savePlainTextToLocalStorage(aPlainText);
+}
+
+function onUnprotectError(aException) {
+ // examine exception or error message
+}
+cryptoAPI.onUnprotectError = onUnprotectError;
+
+cryptoAPI.onUnprotectComplete = onUnprotectComplete;
+
+cryptoAPI.unprotect(keyID, cipherString);
+</pre>
+
+<h3>Signature creation</h3>
+<pre class="example sh_html sh_sourceCode">
+var dataToSign = "This is some data to sign";
+
+cryptoAPI.onSignComplete = function (aJWS) {
+ // send the signature to the server, etc.
+};
+
+cryptoAPI.onSignError = function (aError) {
+ // console.log(), etc.
+};
+
+cryptoAPI.sign(dataToSign, JWK_ID);
+</pre>
+
+<h3>Signature Verification</h3>
+<pre class="example sh_html sh_sourceCode">
+cryptoAPI.onVerifyComplete = function (aVerified) {
+ // aVerified is a boolean
+};
+
+cryptoAPI.onVerifyError = function (aError) {
+ // console.log(), etc.
+};
+
+cryptoAPI.verify(RECEIVED_JWS, SIGNER_JWK);
+</pre>
</section>
-
+ </section>
<!--
<section class='appendix'>
<h2>Acknowledgements</h2>
@@ -760,11 +369,5 @@
</p>
</section>
-->
-
-
-<section class="appendix" id="references"><!--OddPage--><h2><span class="secno">A. </span>References</h2><section id="normative-references"><h3><span class="secno">A.1 </span>Normative references</h3><dl class="bibliography"><dt id="bib-HTML5">[HTML5]</dt><dd>Robin Berjon; et al. <a href="http://www.w3.org/TR/html5/"><cite>HTML5.</cite></a> 17 December 2012. W3C Candidate Recommendation. (Work in progress.) URL: <a href="http://www.w3.org/TR/html5/">http://www.w3.org/TR/html5/</a>
-</dd><dt id="bib-RFC2119">[RFC2119]</dt><dd>S. Bradner. <a href="http://www.ietf.org/rfc/rfc2119.txt"><cite>Key words for use in RFCs to Indicate Requirement Levels.</cite></a> March 1997. Internet RFC 2119. URL: <a href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>
-</dd><dt id="bib-WEBCRYPTO">[WEBCRYPTO]</dt><dd>Ryan Sleevi, David Dahl. <a href="http://www.w3.org/TR/WebCryptoAPI/"><cite>Web Cryptography API.</cite></a> W3C Working Draft (Work in progress.) URL: <a href="http://www.w3.org/TR/WebCryptoAPI/">http://www.w3.org/TR/WebCryptoAPI/</a>
-</dd><dt id="bib-WEBIDL">[WEBIDL]</dt><dd>Cameron McCormack. <a href="http://www.w3.org/TR/2011/WD-WebIDL-20110927/"><cite>Web IDL.</cite></a> 27 September 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-WebIDL-20110927/">http://www.w3.org/TR/2011/WD-WebIDL-20110927/</a>
-</dd><dt id="bib-WEBWORKERS">[WEBWORKERS]</dt><dd>Ian Hickson. <a href="http://www.w3.org/TR/2011/WD-workers-20110901/"><cite>Web Workers.</cite></a> 1 September 2011. W3C Working Draft. (Work in progress.) URL: <a href="http://www.w3.org/TR/2011/WD-workers-20110901/">http://www.w3.org/TR/2011/WD-workers-20110901/</a>
-</dd></dl></section></section></body></html>
+ </body>
+</html>
--- a/highlevel-api-source.html Tue Jan 22 18:11:06 2013 -0600
+++ b/highlevel-api-source.html Fri Jan 25 10:22:21 2013 -0600
@@ -46,13 +46,13 @@
shortName: "webcrypto-high-level-api",
editors: [{ name: "David Dahl",
mailto: "ddahl@mozilla.com",
- company: "Mozilla Foundation",
+ company: "Mozilla Corporation",
companyURL: "http://www.mozilla.org/"} ],
- publishDate: "2013-01-22",
- // previousPublishDate: "2013-01-22",
+ publishDate: "2013-01-25",
+ previousPublishDate: "2013-01-22",
// edEnd: "",
previousMaturity: "ED",
- edDraftURI: "http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/high-level-Overview.html",
+ edDraftURI: "https://dvcs.w3.org/hg/webcrypto-highlevel/raw-file/tip/Overview.html",
wg: "Web Cryptography WG",
wgURI: "http://www.w3.org/2012/webcrypto/",
wgPublicList: "public-webcrypto",
@@ -74,7 +74,7 @@
<section class="informative">
<h2>Introduction</h2>
<p>
- The Web Cryptography API [[!WEBCRYPTO]] describes a JavaScript API for performing basic cryptographic operations in web applications. The Web Cryoptography API is not a simple API geared towards the average web developer, rather its use requires near-expert knowledge of cryptography. The 'High-level' API described here is designed around fewer use cases and is not concerned with backward-compatibility with existing crypto systems and protocols.
+ The Web Cryptography API [[!WEBCRYPTO]] describes a JavaScript API for performing basic cryptographic operations in web applications. The Web Cryoptography API is not a simple API geared towards the average web developer, rather its use requires near-expert knowledge of cryptography. The 'High-level' API described here is designed around fewer use cases and is not concerned with backward-compatibility with existing crypto systems and protocols. This API leverages the IETF JOSE JWA, JWK and JWE JSON formats for algorithms, public keys and cipher data.
</p>
</section>
@@ -82,11 +82,11 @@
<h2>Use cases</h2>
<section>
<h3>Security of data at rest</h3>
- <p>TBD</p>
+ <p>TODO</p>
</section>
<section>
<h3>Web-based messaging</h3>
- <p>TBD</p>
+ <p>TODO</p>
</section>
</section>
@@ -185,30 +185,49 @@
<dd>Generate a public keypair</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onCreateKeypair</dt>
<dd>onCreateKeypair event handler</dd>
- <dt>void encryptAndSign (in ArrayBuffer aClearData, in DOMString aRecipientJWK, in DOMString aSenderJWKID)</dt>
+
+ <dt>void encryptAndSign (in DOMSring aPlainText, in DOMString aRecipientJWK, in DOMString aSenderJWKID)</dt>
<dd>Perform encryption, signing the encrypted data</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onEncryptComplete</dt>
<dd>onEncryptComplete event handler</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onEncryptError</dt>
<dd>onEncryptError event handler</dd>
+
<dt>void verifyAndDecrypt (in DOMString aReceivedJWE, in DOMString aSenderJWK, in DOMString aRecipientJWKID)</dt>
<dd>Verify signature and decrypttion method</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onDecryptComplete</dt>
<dd>onDecryptComplete event handler</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onDecryptError</dt>
<dd>onDecryptError event handler</dd>
+
+ <dt>void protect (in DOMString aPlainText, in DOMString aJWAlgID)</dt>
+ <dd>Symmetric encryption of a string (a key is generated on each use)</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onProtectComplete</dt>
+ <dd>onProtectComplete event handler, ciphertext and keyID are passed to this function</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onProtectError</dt>
+ <dd>onProtectError event handler</dd>
+
+ <dt>void unprotect (in DOMString aKeyID, in DOMString aPlainText)</dt>
+ <dd>Symmetric decryption of a string</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onUnprotectComplete</dt>
+ <dd>onUnprotectComplete event handler</dd>
+ <dt>[TreatNonCallableAsNull] attribute Function? onUnprotectError</dt>
+ <dd>onUnprotectError event handler</dd>
+
<dt>void sign(in aDOMString aClearData, in DOMString aJWKID)</dt>
<dd>Create a digital signature</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onSignComplete</dt>
<dd>onSignComplete event handler</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onSignError</dt>
<dd>onSignError event handler</dd>
+
<dt>void verify (in DOMString aJWS, in DOMString aDataToVerify, in DOMString aJWK)</dt>
<dd>Verify a digital signature</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onVerifyComplete</dt>
<dd>onVerifyComplete event handler</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onVerifyError</dt>
<dd>onVerifyError event handler</dd>
+
<dt>void hash(in DOMString aData)</dt>
<dd>Create a cryptographic hash</dd>
<dt>[TreatNonCallableAsNull] attribute Function? onHashComplete</dt>
@@ -252,7 +271,7 @@
cryptoAPI.createKeypair("RSA1_5");
</pre>
- <h3>Encryption</h3>
+ <h3>Public Key Encryption</h3>
<pre class="example sh_html sh_sourceCode">
var plainText = "The rain in Spain falls mainly on the plain.";
@@ -263,7 +282,7 @@
cryptoAPI.encryptAndSign(plainText, RECIPIENT_JWK, SENDER_JWK_ID);
</pre>
-<h3>Decryption</h3>
+<h3>Public Key Decryption</h3>
<pre class="example sh_html sh_sourceCode">
function onDecryptComplete(aPlainText) {
// read and save plain text
@@ -281,6 +300,38 @@
cryptoAPI.verifyAndDecrypt(RECEIVED_JWE, SENDER_JWK, RECIPIENT_JWK_ID);
</pre>
+<h3>Symmetric Encryption</h3>
+<pre class="example sh_html sh_sourceCode">
+function onProtectComplete(aCipherText, aKeyID) {
+ // cipher text and the key ID are provided to this event handler
+}
+
+function onProtectError(aException) {
+ // examine exception or error message
+}
+cryptoAPI.onProtectError = onProtectError;
+
+cryptoAPI.onProtectComplete = onProtectComplete;
+//
+cryptoAPI.protect("s3kr3t m355ag3", "A256GCM");
+</pre>
+
+<h3>Symmetric Decryption</h3>
+<pre class="example sh_html sh_sourceCode">
+function onUnprotectComplete(aPlainText) {
+ savePlainTextToLocalStorage(aPlainText);
+}
+
+function onUnprotectError(aException) {
+ // examine exception or error message
+}
+cryptoAPI.onUnprotectError = onUnprotectError;
+
+cryptoAPI.onUnprotectComplete = onUnprotectComplete;
+
+cryptoAPI.unprotect(keyID, cipherString);
+</pre>
+
<h3>Signature creation</h3>
<pre class="example sh_html sh_sourceCode">
var dataToSign = "This is some data to sign";