--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Overview.html Tue Jan 22 18:11:06 2013 -0600
@@ -0,0 +1,770 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+<head>
+ <title>WebCrypto High-level API</title>
+ <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+ <style>
+ table {
+ border-collapse: collapse;
+ border-spacing: 0px;
+ margin-top: +1em;
+ margin-bottom: +1em;
+ border-color: black;
+ font-family: "Courier New", Inconsolata, "Bitstream Charter";
+ font-size: 90%;
+ }
+ th {
+ background-color:DimGray;
+ color:white;
+ font-weight: normal;
+ }
+ .sub-th {
+ background-color: Linen;
+ font-style: italic;
+ }
+ .centered {
+ text-align: center;
+ }
+ .first-column {
+ background-color: Beige;
+ font-weight: bold;
+ }
+ .excluded-first-column {
+ background-color: DarkGray;
+ text-decoration: line-through;
+ }
+ </style>
+
+ <!--
+ === NOTA BENE ===
+ 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>
+ <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>
+ <section id="web-based-messaging">
+ <h3><span class="secno">2.2 </span>Web-based messaging</h3>
+ <p>TBD</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>
+
+ <p>
+ The following conformance classes are defined by this specification:
+ </p>
+ <dl>
+ <dt><dfn id="dfn-conforming-user-agent">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
+ 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
+ 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>
+ </dd>
+ </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>]
+ 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.
+ </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>
+ <p>
+ TBD
+ </p>
+ </section>
+ </section>
+
+ <section class="section" id="dependencies">
+ <!--OddPage--><h2><span class="secno">6. </span>Dependencies</h2>
+ <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>].
+ </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>
+ <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>
+ </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 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>
+
+ <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>
+
+ <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>
+
+ </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">
+
+</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">
+
+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>
+
+<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">
+
+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</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>
+ </section>
+
+ <!--
+ <section class='appendix'>
+ <h2>Acknowledgements</h2>
+ <p>
+ Many thanks to ...
+ </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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/highlevel-api-source.html Tue Jan 22 18:11:06 2013 -0600
@@ -0,0 +1,322 @@
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>WebCrypto High-level API</title>
+ <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
+ <style>
+ table {
+ border-collapse: collapse;
+ border-spacing: 0px;
+ margin-top: +1em;
+ margin-bottom: +1em;
+ border-color: black;
+ font-family: "Courier New", Inconsolata, "Bitstream Charter";
+ font-size: 90%;
+ }
+ th {
+ background-color:DimGray;
+ color:white;
+ font-weight: normal;
+ }
+ .sub-th {
+ background-color: Linen;
+ font-style: italic;
+ }
+ .centered {
+ text-align: center;
+ }
+ .first-column {
+ background-color: Beige;
+ font-weight: bold;
+ }
+ .excluded-first-column {
+ background-color: DarkGray;
+ text-decoration: line-through;
+ }
+ </style>
+
+ <!--
+ === NOTA BENE ===
+ 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,
+ -->
+ <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 Foundation",
+ companyURL: "http://www.mozilla.org/"} ],
+ publishDate: "2013-01-22",
+ // previousPublishDate: "2013-01-22",
+ // edEnd: "",
+ previousMaturity: "ED",
+ edDraftURI: "http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/high-level-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">
+ <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.
+ </p>
+ </section>
+
+ <section>
+ <h2>Use cases</h2>
+ <section>
+ <h3>Security of data at rest</h3>
+ <p>TBD</p>
+ </section>
+ <section>
+ <h3>Web-based messaging</h3>
+ <p>TBD</p>
+ </section>
+ </section>
+
+ <section id="conformance">
+ <p>
+ The following conformance classes are defined by this specification:
+ </p>
+ <dl>
+ <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 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 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>
+ </dd>
+ </dl>
+ <p>
+ User agents that use ECMAScript to implement the APIs defined in this specification
+ 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">
+ <h2>Scope</h2>
+ <p>The considerations in the Scope section of [[!WEBCRYPTO]] apply to this specification as well.
+ </p>
+ </section>
+ <section class="informative">
+ <h2>Privacy considerations</h2>
+ <p>The Privacy considerations of [[!WEBCRYPTO]] apply to this specification.</p>
+ <section>
+ <p>
+ TBD
+ </p>
+ </section>
+ </section>
+
+ <section class="section" id="dependencies">
+ <h3>Dependencies</h3>
+ <p>
+ This specification relies on several other underlying specifications.
+ </p>
+ <dl>
+ <dt>HTML5</dt>
+ <dd>The terms and algorithms
+ <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 [[!WEBIDL]].</dd>
+ <dt>WebWorkers</dt>
+ <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>
+ <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>
+ <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>
+ <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 ArrayBuffer aClearData, 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 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>
+ <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>
+ <h2>Examples</h2>
+ <h3>Keypair handling, generation</h3>
+ <pre class="example sh_html sh_sourceCode">
+var myCurrentKeyPair = null;
+
+function onGetKeypair(aKeypair)
+{
+ localStorage.setItem(aKeypair.id, aKeypair.publicKey);
+}
+
+var cryptoAPI = new window.crypto.highlevel();
+cryptoAPI.onGetKeypair = onGetKeypair;
+
+function onCreateKeypair(aKeypair)
+{
+ localStorage.setItem(aKeypair.id, aKeypair.publicKey);
+ myCurrentKeyPair = aKeypair;
+}
+
+cryptoAPI.onCreateKeypair = onCreateKeypair;
+
+cryptoAPI.createKeypair("RSA1_5");
+</pre>
+ <h3>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>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>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>
+ <p>
+ Many thanks to ...
+ </p>
+ </section>
+ -->
+ </body>
+</html>