spec/Overview.html
author David Dahl <ddahl@mozilla.com>
Tue, 21 May 2013 13:01:23 -0500
changeset 45 45c433f19151
parent 44 26752f7ea5ff
child 46 9a993888347c
permissions -rw-r--r--
[mq]: ed-note-getRandom
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     1
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     2
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     3
<!--
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     4
  Overview.html
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     5
  Web IDL
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     6
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     7
  Note: This file is generated from Overview.xml.  Run "make" to regenerate it.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     8
  -->
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     9
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    10
<html xmlns="http://www.w3.org/1999/xhtml">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    11
  <head>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    12
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    13
    <title>Web Cryptography API</title>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    14
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    15
    <link rel="stylesheet" href="webcrypto.css" type="text/css" />
12
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    16
    <style type="text/css">
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    17
      .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    18
      .XXX &gt; :first-child { margin-top: 0; }
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    19
      p .XXX { line-height: 3em; }
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    20
    </style>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    21
    <script src="section-links.js" type="application/ecmascript"></script>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    22
    <script src="dfn.js" type="application/ecmascript"></script>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    23
    <!--[if IE]>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    24
        <style type='text/css'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    25
        .ignore {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    26
        -ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=50)";
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    27
        filter: alpha(opacity=50);
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    28
        }
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    29
        </style>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    30
        <![endif]-->
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    31
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    32
    
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    33
  <link rel="stylesheet" href="//www.w3.org/StyleSheets/TR/W3C-ED" type="text/css" /></head>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    34
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    35
  <body>
45
45c433f19151 [mq]: ed-note-getRandom
David Dahl <ddahl@mozilla.com>
parents: 44
diff changeset
    36
    <div class="head"><div><a href="http://www.w3.org/"><img src="//www.w3.org/Icons/w3c_home" width="72" height="48" alt="W3C" /></a></div><h1>Web Cryptography API</h1><h2>W3C Editor’s Draft <em>21 May 2013</em></h2><dl><dt>Latest Editor’s Draft:</dt><dd><a href="http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html">http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html</a></dd><dt>Latest Published Version:</dt><dd><a href="http://www.w3.org/TR/WebCryptoAPI/">http://www.w3.org/TR/WebCryptoAPI/</a></dd><dt>Previous Version(s):</dt><dd><a href="https://dvcs.w3.org/hg/webcrypto-api/raw-file/0fe9b34c13fb/spec/Overview.html">https://dvcs.w3.org/hg/webcrypto-api/raw-file/0fe9b34c13fb/spec/Overview.html</a></dd><dt>Editors:</dt><dd><a href="http://ddahl.com/">David Dahl</a>, Mozilla Corporation &lt;ddahl@mozilla.com&gt;</dd><dd><a href="http://www.google.com/">Ryan Sleevi</a>, Google, Inc. &lt;sleevi@google.com&gt;</dd><dt>Participate:</dt><dd><p>Send feedback to <a href="mailto:public-webcrypto@w3.org?subject=%5BWebCryptoAPI%5D">public-webcrypto@w3.org</a> (<a href="http://lists.w3.org/Archives/Public/public-webcrypto/">archives</a>), or <a href="https://www.w3.org/Bugs/Public/enter_bug.cgi?product=Web%20Cryptography&amp;component=Web%20Cryptography%20API%20Document">file a bug</a> 
2
d73cb1b6596e Update URLs for ED vs WD
Ryan Sleevi <sleevi@google.com>
parents: 1
diff changeset
    37
    (see <a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=Web%20Cryptography&amp;component=Web%20Cryptography%20API%20Document&amp;resolution=---">existing bugs</a>).</p></dd></dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> &copy; view <a href="http://www.w3.org/"><abbr title="World Wide Web Consortium">W3C</abbr></a><sup>&reg;</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><abbr title="European Research Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <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></div><hr />
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    38
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    39
    <div class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    40
      <h2>Abstract</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    41
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    42
This specification describes a JavaScript API for performing basic
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    43
cryptographic operations in web applications, such as hashing,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    44
signature generation and verification, and encryption and decryption.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    45
Additionally, it describes an API for applications to generate and/or
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
    46
manage the keying material necessary to perform these operations. 
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
    47
Uses for this API range from user or service authentication, document
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
    48
or code signing, and the confidentiality and integrity of
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
    49
communications.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    50
      </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    51
  
45
45c433f19151 [mq]: ed-note-getRandom
David Dahl <ddahl@mozilla.com>
parents: 44
diff changeset
    52
      <div class="ednote"><div class="ednoteHeader">Editorial note</div><p>There are 17 further editorial notes in the document.</p></div>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    53
    </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    54
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    55
    <div class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    56
      <h2>Status of this Document</h2>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    57
      <p><em>
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    58
        This section describes the status of this document at the time of
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    59
        its publication.  Other documents may supersede this document. A list
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    60
        of current W3C publications and the latest revision of this technical
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    61
        report can be found in the <a href="http://www.w3.org/TR/">W3C technical
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    62
          reports index</a> at http://www.w3.org/TR/.
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    63
      </em></p><p>
45
45c433f19151 [mq]: ed-note-getRandom
David Dahl <ddahl@mozilla.com>
parents: 44
diff changeset
    64
        This document is the 21 May 2013 <b>Editor’s Draft</b> of the
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    65
        <cite>Web Cryptography API</cite> specification.
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    66
      
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    67
      Please send comments about this document to
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    68
      <a href="mailto:public-webcrypto-comments@w3.org">public-webcrypto-comments@w3.org</a>
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    69
      (<a href="http://lists.w3.org/Archives/Public/public-webcrypto-comments/">archived</a>).
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    70
    </p>
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    71
9
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    72
      <p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    73
        This document is produced by the <a href="http://www.w3.org/2012/webcrypto">Web Cryptography
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    74
        <acronym title="Working Group">WG</acronym></a> of the <acronym title="World Wide Web Consortium">W3C</acronym>.
12
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    75
      </p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    76
12
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    77
      <p class="XXX">
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    78
        Implementors should be aware that this specification is not stable.
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    79
        <strong>Implementors who are not taking part in the discussions are likely to find the
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    80
        specification changing out from under them in incompatible ways.</strong> Vendors interested
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    81
        in implementing this specification before it eventually reaches the Candidate Recommendation
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    82
        stage should join the mailing lists that follow and take part in the discussions.
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    83
      </p>
1565cb97f12d Indicate that the spec is a WIP and unstable. Text and styling adopted from Web Storage.
Ryan Sleevi <sleevi@google.com>
parents: 11
diff changeset
    84
      <p>
9
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    85
        The Web Cryptography Working Group invites discussion and feedback on this draft document by
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    86
        web developers, companies, standardization bodies or forums interested in deployment of secure
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    87
        services with web applications. Specifically, Web Cryptography Working Group is looking for
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    88
        feedback on:
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    89
      </p>
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    90
      <ul>
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    91
        <li>developer convenience for managing keys and algorithms;</li>
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    92
        <li>comments on open issues the WG is currently dealing with, highlighted in this working draft;</li>
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    93
        <li>potential missing functionalities to deploy secure web applications.</li>
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
    94
      </ul>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    95
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    96
        Previous discussion of this specification has taken place on three other
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    97
        mailing lists: <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    98
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    99
        (<a href="http://lists.whatwg.org/htdig.cgi/whatwg-whatwg.org/2011-May/031741.html">archive</a>)
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   100
        , <a href="mailto:public-websecurity@w3.org">public-websecurity@w3.org</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   101
        (<a href="http://lists.w3.org/Archives/Public/public-web-security/2011Jun/0000.html">archive</a>), and 
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   102
        <a href="mailto:public-identity@w3.org">public-identity@w3.org</a> (<a href="http://www.w3.org/Search/Mail/Public/search?type-index=public-identity&amp;index-type=t&amp;keywords=DOMCrypt&amp;search=Search">archive</a>).
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   103
        Ongoing discussion will be on the <a href="mailto:public-webcrypto@w3.org">public-webcrypto@w3.org</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   104
        mailing list.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   105
      </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   106
      
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   107
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   108
        Web content and browser developers are encouraged to review this draft. Please send comments to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   109
        <a href="mailto:public-webcrypto-comments@w3.org">public-webcrypto-comments@w3.org</a>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   110
        the <acronym title="World Wide Web Consortium">W3C</acronym>'s public email list for issues related
9
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
   111
        to Web Cryptography.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   112
        <a href="http://lists.w3.org/Archives/Public/public-webcrypto-comments/">Archives</a> of the public list and
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   113
        <a href="http://lists.w3.org/Archives/Public/public-webcrypto/">archives</a> of the member's-only list
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   114
        are available.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   115
      </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   116
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   117
        Changes made to this document can be found in the
9
4c6e6e5e4454 Cleanup: Fix some whitespace, version control URL, and remove old acronym mapping of crypto -> cryptography
Ryan Sleevi <sleevi@google.com>
parents: 8
diff changeset
   118
        <a href="https://dvcs.w3.org/hg/webcrypto-api/file/tip/spec/">W3C public Mercurial server</a>.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   119
      </p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   120
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   121
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   122
          Publication as an Editor’s Draft does not imply endorsement by the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   123
          W3C Membership.  This is a draft document and may be updated, replaced
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   124
          or obsoleted by other documents at any time. It is inappropriate to cite
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   125
          this document as other than work in progress.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   126
        </p><p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   127
      This document was produced by a group operating under the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   128
      <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   129
        2004 W3C Patent Policy</a>. W3C maintains a
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   130
      <a href="http://www.w3.org/2004/01/pp-impl/54174/status">public list of
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   131
        any patent disclosures</a> made in connection with the deliverables of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   132
      the group; that page also includes instructions for disclosing a patent.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   133
      An individual who has actual knowledge of a patent which the individual
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   134
      believes contains
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   135
      <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   136
        Claim(s)</a> must disclose the information in accordance with
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   137
      <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   138
        6 of the W3C Patent Policy</a>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   139
    </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   140
    </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   141
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   142
    <div id="toc">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   143
      <h2>Table of Contents</h2>
42
243df88d617e ACTION-90: Add basic definition for wrapKey() and unwrapKey(), along with a sketch of the proposed algorithm
Ryan Sleevi <sleevi@google.com>
parents: 40
diff changeset
   144
      <div class="toc"><ul><li><a href="#introduction">1. Introduction</a></li><li><a href="#use-cases">2. Use Cases</a><ul><li><a href="#multifactor-authentication">2.1. Multi-factor Authentication</a></li><li><a href="#protected-document">2.2. Protected Document Exchange</a></li><li><a href="#cloud-storage">2.3. Cloud Storage</a></li><li><a href="#document-signing">2.4. Document Signing</a></li><li><a href="#data-integrity-protection">2.5. Data Integrity Protection</a></li><li><a href="#secure-messaging">2.6. Secure Messaging</a></li><li><a href="#jose">2.7. Javascript Object Signing and Encryption (JOSE)</a></li></ul></li><li><a href="#conformance">3. Conformance</a></li><li><a href="#scope">4. Scope</a><ul><li><a href="#scope-abstraction">4.1. Level of abstraction</a></li><li><a href="#scope-algorithms">4.2. Cryptographic algorithms</a></li><li><a href="#scope-operations">4.3. Operations</a></li><li><a href="#scope-out-of-scope">4.4. Out of scope</a></li></ul></li><li><a href="#security">5. Security considerations</a><ul><li><a href="#security-implementers">5.1. Security considerations for implementers</a></li><li><a href="#security-developers">5.2. Security considerations for developers</a></li></ul></li><li><a href="#privacy">6. Privacy considerations</a></li><li><a href="#dependencies">7. Dependencies</a></li><li><a href="#terminology">8. Terminology</a></li><li><a href="#RandomSource-interface">9. RandomSource interface</a><ul><li><a href="#RandomSource-description">9.1. Description</a></li><li><a href="#RandomSource-interface-methods">9.2. Methods and Parameters</a><ul><li><a href="#RandomSource-method-getRandomValues">9.2.1. The getRandomValues method</a></li></ul></li></ul></li><li><a href="#algorithm-dictionary">10. Algorithm dictionary</a><ul><li><a href="#algorithm-dictionary-members">10.1. Algorithm Dictionary Members</a></li></ul></li><li><a href="#key-interface">11. Key interface</a><ul><li><a href="#key-interface-description">11.1. Description</a></li><li><a href="#key-interface-members">11.2. Key interface members</a></li><li><a href="#key-interface-clone">11.3. Structured clone algorithm</a></li></ul></li><li><a href="#cryptooperation-interface">12. CryptoOperation interface</a><ul><li><a href="#CryptoOperation-processing-model">12.1. Processing Model</a></li><li><a href="#cryptooperation-events">12.2. Event Handler Attributes</a></li><li><a href="#CryptoOperation-attributes">12.3. Attributes</a></li><li><a href="#CryptoOperation-methods">12.4. Methods</a><ul><li><a href="#CryptoOperation-method-process">12.4.1. process(ArrayBufferView data)</a></li><li><a href="#CryptoOperation-method-finish">12.4.2. The finish() method</a></li><li><a href="#CryptoOperation-method-abort">12.4.3. The abort() method</a></li></ul></li></ul></li><li><a href="#KeyOperation-interface">13. KeyOperation interface</a></li><li><a href="#crypto-interface">14. Crypto interface</a></li><li><a href="#subtlecrypto-interface">15. SubtleCrypto interface</a><ul><li><a href="#subtlecrypto-interface-description">15.1. Description</a></li><li><a href="#subtlecrypto-interface-methods">15.2. Methods and Parameters</a><ul><li><a href="#SubtleCrypto-method-encrypt">15.2.1. The encrypt method</a></li><li><a href="#SubtleCrypto-method-decrypt">15.2.2. The decrypt method</a></li><li><a href="#SubtleCrypto-method-sign">15.2.3. The sign method</a></li><li><a href="#SubtleCrypto-method-verify">15.2.4. The verify method</a></li><li><a href="#SubtleCrypto-method-digest">15.2.5. The digest method</a></li><li><a href="#SubtleCrypto-method-generateKey">15.2.6. The generateKey method</a></li><li><a href="#SubtleCrypto-method-deriveKey">15.2.7. The deriveKey method</a></li><li><a href="#SubtleCrypto-method-importKey">15.2.8. The importKey method</a></li><li><a href="#SubtleCrypto-method-exportKey">15.2.9. The exportKey method</a></li><li><a href="#SubtleCrypto-method-wrapKey">15.2.10. The wrapKey method</a></li><li><a href="#SubtleCrypto-method-unwrapKey">15.2.11. The unwrapKey method</a></li></ul></li></ul></li><li><a href="#WorkerCrypto-interface">16. WorkerCrypto interface</a><ul><li><a href="#WorkerCrypto-description">16.1. Description</a></li></ul></li><li><a href="#big-integer">17. BigInteger</a></li><li><a href="#keypair">18. KeyPair</a></li><li><a href="#algorithms">19. Algorithms</a><ul><li><a href="#recommended-algorithms">19.1. Recommended algorithms</a></li><li><a href="#defining-an-algorithm">19.2. Defining an algorithm</a><ul><li><a href="#recognized-algorithm-name">19.2.1. Recognized algorithm name</a></li><li><a href="#supported-operations">19.2.2. Supported operations</a></li><li><a href="#algorithm-specific-params">19.2.3. Algorithm-specific parameters</a></li><li><a href="#algorithm-result">19.2.4. Algorithm results</a></li><li><a href="#algorithm-alias">19.2.5. Algorithm aliases</a></li></ul></li><li><a href="#rsaes-pkcs1">19.3. RSAES-PKCS1-v1_5</a><ul><li><a href="#rsaes-pkcs1-description">19.3.1. Description</a></li><li><a href="#rsaes-pkcs1-registration">19.3.2. Registration</a></li><li><a href="#RsaKeyGenParams-dictionary">19.3.3. RsaKeyGenParams dictionary</a></li><li><a href="#rsaes-pkcs1-operations">19.3.4. Operations</a></li></ul></li><li><a href="#rsassa-pkcs1">19.4. RSASSA-PKCS1-v1_5</a><ul><li><a href="#rsassa-pkcs1-description">19.4.1. Description</a></li><li><a href="#rsassa-pkcs1-registration">19.4.2. Registration</a></li><li><a href="#RsaSsaParams-dictionary">19.4.3. RsaSsaParams dictionary</a></li><li><a href="#rsassa-pkcs1-operations">19.4.4. Operations</a></li></ul></li><li><a href="#rsa-pss">19.5. RSA-PSS</a><ul><li><a href="#rsa-pss-description">19.5.1. Description</a></li><li><a href="#rsa-pss-registration">19.5.2. Registration</a></li><li><a href="#rsa-pss-params">19.5.3. RsaPssParams dictionary</a></li><li><a href="#rsa-pss-operations">19.5.4. Operations</a></li></ul></li><li><a href="#rsa-oaep">19.6. RSA-OAEP</a><ul><li><a href="#rsa-oaep-description">19.6.1. Description</a></li><li><a href="#rsa-oaep-registration">19.6.2. Registration</a></li><li><a href="#rsa-oaep-params">19.6.3. RsaOaepParams dictionary</a></li><li><a href="#rsa-oaep-operations">19.6.4. Operations</a></li></ul></li><li><a href="#ecdsa">19.7. ECDSA</a><ul><li><a href="#ecdsa-description">19.7.1. Description</a></li><li><a href="#ecdsa-registration">19.7.2. Registration</a></li><li><a href="#EcdsaParams-dictionary">19.7.3. EcdsaParams dictionary</a></li><li><a href="#EcKeyGenParams-dictionary">19.7.4. EcKeyGenParams dictionary</a></li><li><a href="#ecdsa-operations">19.7.5. Operations</a></li></ul></li><li><a href="#ecdh">19.8. ECDH</a><ul><li><a href="#ecdh-description">19.8.1. Description</a></li><li><a href="#ecdh-registration">19.8.2. Registration</a></li><li><a href="#dh-EcdhKeyDeriveParams">19.8.3. EcdhKeyDeriveParams dictionary</a></li><li><a href="#ecdh-operations">19.8.4. Operations</a></li></ul></li><li><a href="#aes-ctr">19.9. AES-CTR</a><ul><li><a href="#aes-ctr-description">19.9.1. Description</a></li><li><a href="#aes-ctr-registration">19.9.2. Registration</a></li><li><a href="#aes-ctr-params">19.9.3. AesCtrParams dictionary</a></li><li><a href="#aes-keygen-params">19.9.4. AesKeyGenParams dictionary</a></li><li><a href="#aes-ctr-operations">19.9.5. Operations</a></li></ul></li><li><a href="#aes-cbc">19.10. AES-CBC</a><ul><li><a href="#aes-cbc-description">19.10.1. Description</a></li><li><a href="#aes-cbc-registration">19.10.2. Registration</a></li><li><a href="#aes-cbc-params">19.10.3. AesCbcParams dictionary</a></li><li><a href="#aes-cbc-operations">19.10.4. Operations</a></li></ul></li><li><a href="#aes-cmac">19.11. AES-CMAC</a><ul><li><a href="#aes-cmac-description">19.11.1. Description</a></li><li><a href="#aes-cmac-registration">19.11.2. Registration</a></li><li><a href="#aes-cmac-operations">19.11.3. Operations</a></li></ul></li><li><a href="#aes-gcm">19.12. AES-GCM</a><ul><li><a href="#aes-gcm-description">19.12.1. Description</a></li><li><a href="#aes-gcm-registration">19.12.2. Registration</a></li><li><a href="#aes-gcm-params">19.12.3. AesGcmParams dictionary</a></li><li><a href="#aes-gcm-operations">19.12.4. Operations</a></li></ul></li><li><a href="#aes-cfb">19.13. AES-CFB</a><ul><li><a href="#aes-cfb-description">19.13.1. Description</a></li><li><a href="#aes-cfb-registration">19.13.2. Registration</a></li><li><a href="#aes-cfb-params">19.13.3. AesCfbParams dictionary</a></li><li><a href="#aes-cfb-operations">19.13.4. Operations</a></li></ul></li><li><a href="#hmac">19.14. HMAC</a><ul><li><a href="#hmac-description">19.14.1. Description</a></li><li><a href="#hmac-registration">19.14.2. Registration</a></li><li><a href="#hmac-params">19.14.3. HmacParams dictionary</a></li><li><a href="#hmac-operations">19.14.4. Operations</a></li></ul></li><li><a href="#dh">19.15. Diffie-Hellman</a><ul><li><a href="#dh-description">19.15.1. Description</a></li><li><a href="#dh-registration">19.15.2. Registration</a></li><li><a href="#dh-DhKeyGenParams">19.15.3. DhKeyGenParams dictionary</a></li><li><a href="#dh-DhKeyDeriveParams">19.15.4. DhKeyDeriveParams dictionary</a></li><li><a href="#dh-operations">19.15.5. Operations</a></li></ul></li><li><a href="#sha">19.16. SHA</a><ul><li><a href="#sha-description">19.16.1. Description</a></li><li><a href="#sha-registration">19.16.2. Registration</a></li><li><a href="#sha-operations">19.16.3. Operations</a></li></ul></li><li><a href="#concatkdf">19.17. Concat KDF</a><ul><li><a href="#concatkdf-description">19.17.1. Description</a></li><li><a href="#concatkdf-registration">19.17.2. Registration</a></li><li><a href="#concat-params">19.17.3. ConcatParams dictionary</a></li><li><a href="#concat-operations">19.17.4. Operations</a></li></ul></li><li><a href="#hkdf-ctr">19.18. HKDF-CTR</a><ul><li><a href="#hkdf-ctr-description">19.18.1. Description</a></li><li><a href="#hkdf-ctr-registration">19.18.2. Registration</a></li><li><a href="#hkdf-ctr-params">19.18.3. HkdfCtrParams dictionary</a></li><li><a href="#hkdf2-ctr-operations">19.18.4. Operations</a></li></ul></li><li><a href="#pbkdf2">19.19. PBKDF2</a><ul><li><a href="#pbkdf2-description">19.19.1. Description</a></li><li><a href="#pbkdf2-registration">19.19.2. Registration</a></li><li><a href="#pbkdf2-params">19.19.3. Pbkdf2Params dictionary</a></li><li><a href="#pbkdf2-operations">19.19.4. Operations</a></li></ul></li></ul></li><li><a href="#algorithm-normalizing-rules">20. Algorithm normalizing rules</a></li><li><a href="#examples-section">21. JavaScript Example Code</a><ul><li><a href="#examples-signing">21.1. Generate a signing key pair, sign some data</a></li><li><a href="#examples-symmetric-encryption">21.2. Symmetric Encryption</a></li></ul></li><li><a href="#acknowledgements-section">22. Acknowledgements</a></li><li><a href="#references">23. References</a><ul><li><a href="#normative-references">23.1. Normative References</a></li><li><a href="#informative-references">23.2. Informative References</a></li></ul></li></ul></div>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   145
    </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   146
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   147
    <div id="sections">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   148
      <div id="introduction" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   149
        <h2>1. Introduction</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   150
        <p class="norm">This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   151
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   152
          The Web Cryptography API defines a low-level interface to interacting with cryptographic
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   153
          key material that is managed or exposed by user agents. The API itself is agnostic of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   154
          the underlying implementation of key storage, but provides a common set of interfaces
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   155
          that allow rich web applications to perform operations such as signature generation and
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   156
          verification, hashing and verification, encryption and decryption, without requiring
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   157
          access to the raw keying material.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   158
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   159
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   160
          Cryptographic transformations are exposed via the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   161
          <a href="#dfn-CryptoOperation">CryptoOperation</a> interface, which defines a common set
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   162
          of methods and events for dealing with initialization, processing data, and completing
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   163
          the operation to yield the final output. In addition to operations such as signature
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   164
          generation and verification, hashing and verification, and encryption and decryption,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   165
          the API provides interfaces for key generation, key derivation, key import and export,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   166
          and key discovery.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   167
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   168
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   169
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   170
      <div id="use-cases" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   171
        <h2>2. Use Cases</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   172
        <p class="norm">This section is non-normative</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   173
        <div id="multifactor-authentication" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   174
          <h3>2.1. Multi-factor Authentication</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   175
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   176
            A web application may wish to extend or replace existing username/password based
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   177
            authentication schemes with authentication methods based on proving that the user has
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   178
            access to some secret keying material. Rather than using transport-layer authentication,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   179
            such as TLS client certificates, the web application may wish to provide a rich user
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   180
            experience by providing authentication within the application itself.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   181
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   182
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   183
            Using the Web Cryptography API, such an application could locate suitable client keys,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   184
            which may have been previously generated via the user agent or pre-provisioned
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   185
            out-of-band by the web application. It could then perform cryptographic operations such
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   186
            as decrypting an authentication challenge followed by signing an authentication response.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   187
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   188
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   189
            Further, the authentication data could be further enhanced by binding the authentication
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   190
            to the TLS session that the client is authenticating over, by deriving a key based on
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   191
            properties of the underlying transport.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   192
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   193
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   194
            If a user did not already have a key associated with their account, the web application
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   195
            could direct the user agent to either generate a new key or to re-use an existing key of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   196
            the user's choosing. 
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   197
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   198
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   199
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   200
        <div id="protected-document" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   201
          <h3>2.2. Protected Document Exchange</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   202
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   203
            When exchanging documents that may contain sensitive or personal information, a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   204
            web application may wish to ensure that only certain users can view the documents, even
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   205
            after they have been securely received, such as over TLS. One way that a web application
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   206
            can do so is by encrypting the documents with a secret key, and then wrapping that key
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   207
            with the public keys associated with authorized users.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   208
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   209
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   210
            When a user agent navigates to such a web application, the application may send the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   211
            encrypted form of the document. The user agent is then instructed to unwrap the encryption
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   212
            key, using the user's private key, and from there, decrypt and display the document.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   213
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   214
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   215
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   216
        <div id="cloud-storage" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   217
          <h3>2.3. Cloud Storage</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   218
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   219
            When storing data with remote service providers, users may wish to protect the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   220
            confidentiality of their documents and data prior to uploading them. The Web
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   221
            Cryptography API allows an application to have a user select a private or secret key,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   222
            to either derive encryption keys from the selected key or to directly encrypt documents
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   223
            using this key, and then to upload the transformed/encrypted data to the service provider
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   224
            using existing APIs.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   225
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   226
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   227
            This use case is similar to the <a href="#protected-document">Protected Document
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   228
            Exchange</a> use case because Cloud Storage can be considered as a user exchanging
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   229
            protected data with himself in the future.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   230
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   231
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   232
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   233
        <div id="document-signing" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   234
          <h3>2.4. Document Signing</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   235
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   236
            A web application may wish to accept electronic signatures on documents, in lieu of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   237
            requiring physical signatures. An authorized signature may use a key that was
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   238
            pre-provisioned out-of-band by the web application, or it may be using a key that the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   239
            client generated specifically for the web application.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   240
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   241
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   242
            The web application must be able to locate any appropriate keys for signatures, then
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   243
            direct the user to perform a signing operation over some data, as proof that they accept
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   244
            the document.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   245
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   246
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   247
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   248
        <div id="data-integrity-protection" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   249
          <h3>2.5. Data Integrity Protection</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   250
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   251
            When caching data locally, an application may wish to ensure that this data cannot be
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   252
            modified in an offline attack. In such a case, the server may sign the data that it
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   253
            intends the client to cache, with a private key held by the server. The web application
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   254
            that subsequently uses this cached data may contain a public key that enables it to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   255
            validate that the cache contents have not been modified by anyone else.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   256
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   257
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   258
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   259
        <div id="secure-messaging" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   260
          <h3>2.6. Secure Messaging</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   261
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   262
            In addition to a number of web applications already offering chat based services, the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   263
            rise of WebSockets and RTCWEB allows a great degree of flexibility in inter-user-agent
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   264
            messaging. While TLS/DTLS may be used to protect messages to web applications, users
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   265
            may wish to directly secure messages using schemes such as off-the-record (OTR) messaging.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   266
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   267
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   268
            The Web Cryptography API enables OTR, by allowing key agreement to be performed so that
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   269
            the two parties can negotiate shared encryption keys and message authentication code (MAC)
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   270
            keys, to allow encryption and decryption of messages, and to prevent tampering of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   271
            messages through the MACs.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   272
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   273
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   274
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   275
        <div id="jose" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   276
          <h3>2.7. Javascript Object Signing and Encryption (JOSE)</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   277
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   278
            A web application wishes to make use of the structures and format of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   279
            messages defined by the IETF Javascript Object Signing and Encryption
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   280
            (JOSE) Working Group. The web application wishes to manipulate public
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   281
            keys encoded in the JSON key format (JWK), messages that have been
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   282
            integrity protected using digital signatures or MACs (JWS), or that
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   283
            have been encrypted (JWE).
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   284
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   285
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   286
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   287
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   288
      
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   289
      <div id="conformance" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   290
        <h2>3. Conformance</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   291
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   292
          As well as sections marked as non-normative, all authoring guidelines, diagrams,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   293
          examples, and notes in this specification are non-normative. Everything else in
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   294
          this specification is normative.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   295
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   296
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   297
          The keywords <span class="RFC2119">MUST</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   298
          <span class="RFC2119">MUST NOT</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   299
          <span class="RFC2119">REQUIRED</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   300
          <span class="RFC2119">SHALL</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   301
          <span class="RFC2119">SHALL NOT</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   302
          <span class="RFC2119">RECOMMENDED</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   303
          <span class="RFC2119">MAY</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   304
          <span class="RFC2119">OPTIONAL</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   305
          in this specification are to be interpreted as described in 
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   306
          <cite><a href="http://www.ietf.org/rfc/rfc2119">Key words for use in RFCs to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   307
          Indicate Requirement Levels</a></cite> [<a href="#RFC2119">RFC2119</a>].
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   308
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   309
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   310
          The following conformance classes are defined by this specification:
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   311
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   312
        <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   313
          <dt><dfn id="dfn-conforming-implementation">conforming user agent</dfn></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   314
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   315
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   316
              A user agent is considered to be a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   317
              <a class="dfnref" href="#dfn-conforming-implementation">conforming user agent</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   318
              if it satisfies all of the <span class="RFC2119">MUST</span>-,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   319
              <span class="RFC2119">REQUIRED</span>- and <span class="RFC2119">SHALL</span>-level
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   320
              criteria in this specification that apply to implementations. This specification
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   321
              uses both the terms "conforming user agent" and "user agent" to refer to this
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   322
              product class.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   323
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   324
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   325
              User agents <span class="RFC2119">MAY</span> implement algorithms in this
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   326
              specification in any way desired, so long as the end result is indistinguishable
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   327
              from the result that would be obtained from the specification's algorithms.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   328
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   329
          </dd>         
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   330
        </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   331
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   332
          User agents that use ECMAScript to implement the APIs defined in this specification
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   333
          <span class="RFC2119">MUST</span> implement them in a manner consistent with the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   334
          ECMAScript Bindings defined in the Web IDL specification [<a href="#WebIDL">WEBIDL</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   335
          as this specification uses that specification and terminology.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   336
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   337
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   338
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   339
      <div id="scope" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   340
        <h2>4. Scope</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   341
        <p class="norm">This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   342
        <div class="section" id="scope-abstraction">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   343
          <h3>4.1. Level of abstraction</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   344
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   345
            The specification attempts to focus on the common functionality and features between
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   346
            various platform-specific or standardized cryptographic APIs, and avoid features and
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   347
            functionality that are specific to one or two implementations. As such this API allows key
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   348
            generation, management, and exchange with a level of abstraction that avoids developers
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   349
            needing to care about the implementation of the underlying key storage. The API is focused
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   350
            specifically around Key objects, as an abstraction for the underlying raw cryptographic
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   351
            keying material. The intent behind this is to allow an API that is generic enough to allow
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   352
            conforming user agents to expose keys that are stored and managed directly by the user agent,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   353
            that may be stored or managed using isolated storage APIs such as per-user key stores provided
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   354
            by some operating systems, or within key storage devices such as secure elements, while allowing
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   355
            rich web applications to manipulate the keys and without requiring the web application be
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   356
            aware of the nature of the underlying key storage.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   357
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   358
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   359
        <div class="section" id="scope-algorithms">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   360
          <h3>4.2. Cryptographic algorithms</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   361
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   362
            Because the underlying cryptographic implementations will vary between conforming user agents,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   363
            and may be subject to local policy, including but not limited to concerns such as government
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   364
            or industry regulation, security best practices, intellectual property concerns, and
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   365
            constrained operational environments, this specification does not dictate a mandatory set of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   366
            algorithms that <span class="RFC2119">MUST</span> be implemented. Instead, it defines a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   367
            common set of bindings that can be used in an algorithm-independent manner, a common
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   368
            framework for discovering if a user agent or key handle supports the underlying algorithm,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   369
            and a set of conformance requirements for the behaviours of individual algorithms, if
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   370
            implemented.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   371
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   372
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   373
        <div class="section" id="scope-operations">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   374
          <h3>4.3. Operations</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   375
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   376
            Although the API does not expose the notion of cryptographic providers or modules, each
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   377
            key is internally bound to a cryptographic provider or module, so web applications can
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   378
            rest assured that the right cryptographic provider or module will be used to perform
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   379
            cryptographic operations involving that key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   380
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   381
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   382
        <div class="section" id="scope-out-of-scope">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   383
          <h3>4.4. Out of scope</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   384
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   385
            This API, while allowing applications to generate, retrieve, and manipulate keying material,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   386
            does not specifically address the provisioning of keys in particular types of key
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   387
            storage, such as secure elements or smart cards. This is due to such provisioning operations
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   388
            often being burdened with vendor-specific details that make defining a vendor-agnostic
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   389
            interface an unsuitably unbounded task. Additionally, this API does not deal with or address
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   390
            the discovery of cryptographic modules, as such concepts are dependent upon the underlying
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   391
            user agent and are not concepts that are portable between common operating systems,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   392
            cryptographic libraries, and implementations.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   393
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   394
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   395
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   396
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   397
      <div id="security" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   398
        <h2>5. Security considerations</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   399
        <p class="norm">This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   400
        <div id="security-implementers" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   401
          <h2>5.1. Security considerations for implementers</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   402
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   403
            User agents should take care before exposing keys that were not explicitly generated
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   404
            via the API in this specification or exposing keys that were generated in the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   405
            context of other origins. Two applications with access to the same key handle may be
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   406
            able to spoof messages to each other, as both valid and hostile messages will appear
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   407
            to be valid for the given key. Because of this, user agents are recommended to obtain
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   408
            express permission from the user before re-using keys, unless there is a prearranged
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   409
            trust relationship.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   410
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   411
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   412
            User agents should be aware of the security considerations of each algorithm
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   413
            implemented and exposed to applications. For a number of algorithms, their
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   414
            cryptographic strength is relative to the amount of work necessary to compute the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   415
            result, whether this be through the generation of significantly large prime numbers or
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   416
            through the repeatedly iterating through the same algorithm to reduce its
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   417
            susceptibility to brute force. Implementations should therefore take measures to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   418
            ensure against misuse. Such measures may include requiring express user permission to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   419
            compute some expensive operations, rate limiting the number of times the application
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   420
            may call certain APIs/algorithms, and defining implementation-specific upper limits
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   421
            for inputs such as key sizes or iteration counts, as appropriate for the device on
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   422
            which the implementation executes.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   423
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   424
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   425
            In some cases, the same underlying cryptographic key material may be re-usable for
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   426
            multiple algorithms. One such example is an RSA key, which may be used for both
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   427
            signing and encryption, or with RSA-PKCS1v1.5 and RSA-PSS. In some cases, the re-use
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   428
            of this key material may undermine the security properties of the key and allow
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   429
            applications to recover the raw material.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   430
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   431
          <div class="ednote"><div class="ednoteHeader">Editorial note</div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   432
            <ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   433
              <li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   434
                <a href="https://www.w3.org/2012/webcrypto/track/issues/33">ISSUE-33</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   435
                One proposed technical solution for user agents is to implement "key tainting", in
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   436
                which it records how a particular key has been used (eg: algorithms, parameters), and
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   437
                prevents it from being re-used in a manner that is unsafe or contrary to the security -
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   438
                such as preventing a PKCS1-v1.5 key from being used with RSA-PSS, or preventing an
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   439
                RSA-OAEP w/ MGF1-SHA1 from being used with RSA-OAEP w/ MGF1-SHA256. Questions exist
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   440
                about whether this should be encouraged or permitted, and the interoperability concerns
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   441
                it might cause.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   442
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   443
            </ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   444
          </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   445
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   446
        <div id="security-developers" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   447
          <h2>5.2. Security considerations for developers</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   448
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   449
            While this API provides important functionality for the development of secure
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   450
            applications, it does not try to address all of the issues that may arise from the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   451
            web security model. As such, application developers must take care to ensure against
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   452
            common attacks such as script injection by making use of appropriate security
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   453
            functionality such as Content Security Policy and the use of TLS.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   454
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   455
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   456
            This API includes a variety of cryptographic operations, some of which may have known
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   457
            security issues when used inappropriately. Application developers should take care to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   458
            review the appropriate cryptographic literature before making use of certain algorithms,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   459
            and should avoid attempting to develop new cryptographic protocols whenever possible.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   460
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   461
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   462
            While the API in this specification provides a means to protect keys from future access
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   463
            by web applications, it makes no statements as to how the actual keying material will
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   464
            be stored by an implementation. As such, although a key may be inaccessible to web
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   465
            content, it should not be presumed that it is inaccessible to end-users. For example, a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   466
            conforming user agent may choose to implement key storage by storing key material in
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   467
            plain text on device storage. Although the user agent prevents access to the raw keying
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   468
            material to web applications, any user with access to device storage may be able to recover
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   469
            the key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   470
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   471
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   472
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   473
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   474
      <div id="privacy" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   475
        <h2>6. Privacy considerations</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   476
        <p class="norm">This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   477
        <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   478
          <dt>Fingerprinting</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   479
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   480
            Malicious applications may be able to fingerprint users or user agents by detecting or
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   481
            enumerating the list of algorithms that are supported. This is especially true if an
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   482
            implementation exposes details about users' smart cards or secure element storage, as the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   483
            combination of algorithms supported by such devices may be used to fingerprint devices
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   484
            more accurately than just the particular user agent.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   485
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   486
          <dt>Tracking</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   487
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   488
            If user agents permit keys to be re-used between origins, without performing any
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   489
            secondary operations such as key derivation that includes the origin, then it may be
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   490
            possible for two origins to collude and track a unique user by recording their ability
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   491
            to access a common key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   492
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   493
          <dt>Super-cookies</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   494
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   495
            With the exception of ephemeral keys, its often desirable for applications to strongly
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   496
            associate users with keys. These associations may be used to enhance the security of
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   497
            authenticating to the application, such as using a key stored in a secure element as a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   498
            second factor, or may be used by users to assert some identity, such as an e-mail
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   499
            signing identity. As such, these keys often live longer than their counterparts such
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   500
            as usernames and passwords, and it may be undesirable or prohibitive for users to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   501
            revoke these keys.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   502
            Because of this, keys may exist longer than the lifetime of the browsing context
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   503
            [<a href="#HTML">HTML</a>] and beyond the lifetime of items such as cookies, thus
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   504
            presenting a risk that a user may be tracked even after clearing such data. This is
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   505
            especially true for keys that were pre-provisioned for particular origins and for which
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   506
            no user interaction was provided.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   507
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   508
        </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   509
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   510
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   511
      <div id="dependencies" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   512
        <h3>7. Dependencies</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   513
        <p>This specification relies on underlying specifications.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   514
        <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   515
          <dt>DOM</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   516
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   517
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   518
              A <a href="#dfn-conforming-implementation">conforming user agent</a> MUST support at
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   519
              least the subset of the functionality defined in DOM4 that this specification relies
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   520
              upon; in particular, it MUST support <code>EventTarget</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   521
              [<a href="#DOM4">DOM4</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   522
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   523
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   524
          <dt>HTML</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   525
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   526
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   527
              A <a href="#dfn-conforming-implementation">conforming user agent</a> MUST support at
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   528
              least the subset of the functionality defined in HTML that this specification relies
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   529
              upon; in particular, it MUST support <a href="#event-loops">event loops</a> and
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   530
              <a href="#event-handler-idl-attributes">event handler IDL attributes</a>.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   531
              [<a href="#HTML">HTML</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   532
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   533
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   534
          <dt>Web IDL</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   535
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   536
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   537
              A <a href="#dfn-conforming-implementation">conforming user agent</a> MUST be a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   538
              conforming implementation of the IDL fragments in this specification, as described in
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   539
              the Web IDL specification. [<a href="#WebIDL">WebIDL</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   540
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   541
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   542
          <dt>Typed Arrays</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   543
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   544
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   545
              A <a href="#dfn-conforming-implementation">conforming user agent</a> MUST support the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   546
              Typed Arrays specification [<a href="#TypedArrays">TypedArrays</a>].
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   547
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   548
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   549
        </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   550
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   551
   
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   552
      <div id="terminology" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   553
        <h2>8. Terminology</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   554
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   555
          The terms and algorithms
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   556
          <dfn id="document">document</dfn>,
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   557
          <dfn id="event-handler-idl-attributes">event handler IDL attributes</dfn>,
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   558
          <dfn id="event-handler-event-type">event handler event type</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   559
          <dfn id="origin">origin</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   560
          <dfn id="same-origin">same origin</dfn>,
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   561
          <dfn id="df-URL">URL</dfn>,
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   562
          <dfn id="event-loops">event loops</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   563
          <dfn id="dfn-task">task</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   564
          <dfn id="task-source">task source</dfn>,
20
2f4f03785843 Remove the subclasses of KeyOperation, treating all key-based operations as a
Ryan Sleevi <sleevi@google.com>
parents: 19
diff changeset
   565
          <dfn id="queue-a-task">queue a task</dfn>,
2f4f03785843 Remove the subclasses of KeyOperation, treating all key-based operations as a
Ryan Sleevi <sleevi@google.com>
parents: 19
diff changeset
   566
          <dfn id="fire-a-simple-event">fire a simple event</dfn>, and
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   567
          <dfn id="structured-clone">structured clone</dfn>,
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   568
          are defined by the HTML specification [<a href="#HTML">HTML</a>].
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   569
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   570
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   571
          When this specification says to <dfn id="terminate-the-algorithm">terminate the algorithm</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   572
          the user agent must terminate the algorithm after finishing the step it is on. The algorithm
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   573
          referred to is the set of specification-defined processing steps, rather than the underlying
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   574
          cryptographic algorithm that may be in the midst of processing.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   575
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   576
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   577
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   578
      <div id="RandomSource-interface" class="section">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   579
        <h2>9. RandomSource interface</h2>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   580
        <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   581
[NoInterfaceObject]
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   582
interface <dfn id="dfn-RandomSource">RandomSource</dfn> {
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   583
  ArrayBufferView <a href="#dfn-RandomSource-method-getRandomValues">getRandomValues</a>(ArrayBufferView array);
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   584
};
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   585
        </code></pre></div></div>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   586
        <div id="RandomSource-description" class="section">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   587
          <h3>9.1. Description</h3>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   588
          <p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   589
            The <a href="#dfn-RandomSource">RandomSource</a> interface represents an interface to a
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   590
            cryptographically strong pseudo-random number generator seeded with truly random values.
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   591
          </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   592
          <p class="implementation-note">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   593
            Implementation note: Implementations should generate cryptographically random values using
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   594
            well-established cryptographic pseudo-random number generators seeded with high-quality
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   595
            entropy, such as from an operating-system entropy source (e.g., "/dev/urandom"). This
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   596
            specification provides no lower-bound on the information theoretic entropy present in
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   597
            cryptographically random values, but implementations should make a best effort to provide
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   598
            as much entropy as practicable.
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   599
          </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   600
          <p class="implementation-note">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   601
            Implementation note: This interface defines a synchronous method for obtaining cryptographically
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   602
            random values. While some devices and implementations may support truly random cryptographic
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   603
            number generators or provide interfaces that block when there is insufficient entropy,
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   604
            implementations are encouraged not to use these sources when implementing getRandomValues,
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   605
            both for performance and to avoid depleting the system of entropy. Instead, these sources
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   606
            should be used to seed a cryptographic pseudo-random number generator that can then return
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   607
            suitable values efficiently.
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   608
          </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   609
        </div>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   610
        <div id="RandomSource-interface-methods" class="section">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   611
          <h3>9.2. Methods and Parameters</h3>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   612
          <div id="RandomSource-method-getRandomValues" class="section">
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   613
            <h4>9.2.1. The getRandomValues method</h4>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   614
            <p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   615
              The <dfn id="dfn-RandomSource-method-getRandomValues"><code>getRandomValues</code></dfn>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   616
              method generates cryptographically random values. It must act as follows:
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   617
            </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   618
            <ol>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   619
              <li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   620
                <p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   621
                  If <var>array</var> is not of an integer type (i.e., Int8Array, Uint8Array,
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   622
                  Int16Array, Uint16Array, Int32Array, or Uint32Array), throw a
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   623
                  <code>TypeMismatchError</code> and
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   624
                  <a href="#terminate-the-algorithm">terminate the algorithm</a>.
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   625
                </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   626
              </li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   627
              <li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   628
                <p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   629
                  If the <code>byteLength</code> of <var>array</var> is greater than 65536, throw a
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   630
                  <code>QuotaExceededError</code> and
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   631
                  <a href="#terminate-the-algorithm">terminate the algorithm</a>.
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   632
                </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   633
              </li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   634
              <li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   635
                <p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   636
                  Overwrite all elements of <var>array</var> with cryptographically random values of
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   637
                  the appropriate type.
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   638
                </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   639
              </li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   640
              <li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   641
                <p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   642
                  Return <var>array</var>.
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   643
                </p>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   644
              </li>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   645
            </ol>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   646
            <div class="note"><div class="noteHeader">Note</div>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   647
              <p>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   648
                Do not generate keys using the <code>getRandomValues</code> method. Use the
42
243df88d617e ACTION-90: Add basic definition for wrapKey() and unwrapKey(), along with a sketch of the proposed algorithm
Ryan Sleevi <sleevi@google.com>
parents: 40
diff changeset
   649
                <a href="#dfn-SubtleCrypto-method-generateKey"><code>generateKey</code></a> method instead.
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   650
              </p>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   651
            </div>
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   652
          </div>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   653
        </div>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   654
      </div>
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   655
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   656
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   657
      <div id="algorithm-dictionary" class="section">
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   658
        <h2>10. Algorithm dictionary</h2>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   659
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   660
          The Algorithm object is a dictionary object [<cite><a href="#WebIDL">WebIDL</a></cite>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   661
          which is used to specify an algorithm and any additional parameters required to fully
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   662
          specify the desired operation.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   663
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   664
        <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   665
<span class="comment">// TBD: <a href="http://www.w3.org/2012/webcrypto/track/issues/28">ISSUE-28</a></span>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   666
typedef (<a href="#dfn-Algorithm">Algorithm</a> or DOMString) <dfn id="dfn-AlgorithmIdentifier">AlgorithmIdentifier</dfn>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   667
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   668
dictionary <dfn id="dfn-Algorithm">Algorithm</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   669
  DOMString <a href="#dfn-Algorithm-name">name</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   670
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   671
        </code></pre></div></div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   672
        <div id="algorithm-dictionary-members" class="section">
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   673
          <h3>10.1. <a href="#dfn-Algorithm">Algorithm</a> Dictionary Members</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   674
          <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   675
            <dt id="dfn-Algorithm-name">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   676
              <code>name</code>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   677
            </dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   678
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   679
              The name of the <a href="#algorithms">registered algorithm</a> to use.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   680
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   681
          </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   682
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   683
      </div>
6
9baa26b28e78 ISSUE-17 and ISSUE-25: Remove the KeyAttributes object
Ryan Sleevi <sleevi@google.com>
parents: 5
diff changeset
   684
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   685
      <div id="key-interface" class="section">
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   686
        <h2>11. Key interface</h2>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   687
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   688
          The Key object represents an opaque reference to keying material that is managed by the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   689
          user agent.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   690
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   691
        <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   692
enum <dfn id="dfn-KeyType">KeyType</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   693
  "secret",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   694
  "public",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   695
  "private"
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   696
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   697
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   698
enum <dfn id="dfn-KeyUsage">KeyUsage</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   699
  "encrypt",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   700
  "decrypt",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   701
  "sign",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   702
  "verify",
42
243df88d617e ACTION-90: Add basic definition for wrapKey() and unwrapKey(), along with a sketch of the proposed algorithm
Ryan Sleevi <sleevi@google.com>
parents: 40
diff changeset
   703
  "derive",
243df88d617e ACTION-90: Add basic definition for wrapKey() and unwrapKey(), along with a sketch of the proposed algorithm
Ryan Sleevi <sleevi@google.com>
parents: 40
diff changeset
   704
  "wrap",
243df88d617e ACTION-90: Add basic definition for wrapKey() and unwrapKey(), along with a sketch of the proposed algorithm
Ryan Sleevi <sleevi@google.com>
parents: 40
diff changeset
   705
  "unwrap"
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   706
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   707
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   708
interface <dfn id="dfn-Key">Key</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   709
  readonly attribute KeyType <a href="#dfn-Key-type">type</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   710
  readonly attribute bool <a href="#dfn-Key-extractable">extractable</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   711
  readonly attribute <a href="#dfn-Algorithm">Algorithm</a> <a href="#dfn-Key-algorithm">algorithm</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   712
  readonly attribute <a href="#dfn-KeyUsage">KeyUsage</a>[] <a href="#dfn-Key-keyUsage">keyUsage</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   713
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   714
        </code></pre></div></div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   715
        <div id="key-interface-description" class="section">
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   716
          <h3>11.1. Description</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   717
          <span class="normative">This section is non-normative</span>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   718
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   719
            This specification provides a uniform interface for many different kinds of keying material
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   720
            managed by the user agent. This may include keys that have been generated by the user agent,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   721
            derived from other keys by the user agent, imported to the user agent through user actions
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   722
            or using this API, pre-provisioned within software or hardware to which the user agent has
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   723
            access or made available to the user agent in other ways. The term key refers broadly to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   724
            any keying material including actual keys for cryptographic operations and secret
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   725
            values obtained within key derivation or exchange operations.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   726
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   727
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   728
            The Key object is not required to directly interface with the underlying key storage
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   729
            mechanism, and may instead simply be a reference for the user agent to understand how
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   730
            to obtain the keying material when needed, eg. when performing a
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   731
            <a href="#dfn-CryptoOperation">CryptoOperation</a>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   732
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   733
        </div>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   734
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   735
        <div id="key-interface-members" class="section">
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   736
          <h3>11.2. Key interface members</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   737
          <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   738
            <dt id="dfn-Key-type"><code>type</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   739
            <dd>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   740
              The type of the underlying key. Opaque keying material, including that used for
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   741
              symmetric algorithms, is represented by <code>"secret"</code>, while keys used as
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   742
              part of asymmetric algorithms composed of public/private keypairs will be either
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   743
              <code>"public"</code> or <code>"private"</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   744
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   745
            <dt id="dfn-Key-extractable"><code>extractable</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   746
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   747
              Whether or not the raw keying material may be exported by the application.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   748
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   749
            <dt id="dfn-Key-algorithm"><code>algorithm</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   750
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   751
              The <a href="#dfn-Algorithm"><code>Algorithm</code></a> used to generate the key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   752
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   753
            <dt id="dfn-Key-keyUsage"><code>keyUsage</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   754
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   755
              An <code>Array</code> of <a href="#dfn-KeyUsage"><code>KeyUsages</code></a> that
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   756
              indicate what <a href="#dfn-CryptoOperation">CryptoOperations</a> may be used with this
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   757
              key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   758
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   759
          </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   760
        </div>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   761
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   762
        <div id="key-interface-clone" class="section">
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   763
          <h3>11.3. Structured clone algorithm</h3>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   764
          <p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   765
            When a user agent is required to obtain a <a href="#structured-clone">structured clone</a>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   766
            of a <a href="#dfn-Key">Key</a> object, it must run the following steps.
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   767
          </p>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   768
          <ol>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   769
            <li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   770
              Let <var>input</var> and <var>memory</var> be the corresponding inputs defined
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   771
              by the <a href="#structured-clone">internal structured cloning algorithm</a>,
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   772
              where <var>input</var> represents a <a href="#dfn-Key">Key</a> object to be cloned.
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   773
            </li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   774
            <li>Let <var>output</var> be a newly constructed <a href="#dfn-Key">Key</a> object.</li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   775
            <li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   776
              Let the following attributes of <var>output</var> be equal to the value obtained by
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   777
              invoking the internal structured clone algorithm recursively, using the corresponding
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   778
              attribute on <var>input</var> as the new "<var>input</var>" argument and <var>memory</var>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   779
              as the new "<var>memory</var>" argument:
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   780
              <ul>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   781
                <li><a href="#dfn-Key-type">type</a></li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   782
                <li><a href="#dfn-Key-extractable">extractable</a></li>
20
2f4f03785843 Remove the subclasses of KeyOperation, treating all key-based operations as a
Ryan Sleevi <sleevi@google.com>
parents: 19
diff changeset
   783
                <li><a href="#dfn-Key-algorithm">Algorithm</a></li>
2f4f03785843 Remove the subclasses of KeyOperation, treating all key-based operations as a
Ryan Sleevi <sleevi@google.com>
parents: 19
diff changeset
   784
                <li><a href="#dfn-Key-keyUsage">KeyUsage</a></li>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   785
              </ul>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   786
            </li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   787
            <li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   788
              Let <var>output</var> refer to the same underlying cryptographic material and
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   789
              cryptographic material key storage of <var>input</var>.
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   790
            </li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   791
          </ol>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   792
          <div class="note"><div class="noteHeader">Note</div>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   793
            <strong>Implementation Note:</strong> When performing the structured clone algorithm for
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   794
            a <code>Key</code> object, it is important that the underlying cryptographic key material
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   795
            not be exposed to a JavaScript implementation. Such a situation may arise if an implementation
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   796
            fails to implement the structured clone algorithm correctly, such as by allowing a <code>Key</code> object
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   797
            to be serialized as part of a structured clone implementation, but then deserializing it as
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   798
            a <code>DOMString</code>, rather than as a <code>Key</code> object.
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   799
          </div>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   800
        </div>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   801
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   802
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   803
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   804
      <div id="cryptooperation-interface" class="section">
3
9bf98c13a88b Move getRandomValues into a RandomSource interface, and have both Crypto and WorkerCrypto implement the interface.
Ryan Sleevi <sleevi@google.com>
parents: 2
diff changeset
   805
        <h2>12. CryptoOperation interface</h2>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   806
        <div class="block"><div class="blockTitleDiv"><span class="blockTitle">IDL</span></div><div class="blockContent"><pre class="code"><code class="idl-code">
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   807
interface <dfn id="dfn-CryptoOperation">CryptoOperation</dfn> : EventTarget {
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   808
  void <a href="#dfn-CryptoOperation-method-process">process</a>(ArrayBufferView buffer);
16
b25fc49200d6 Rename processData() to process() and complete() -> finish()
Ryan Sleevi <sleevi@google.com>
parents: 15
diff changeset
   809
  void <a href="#dfn-CryptoOperation-method-finish">finish</a>();
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   810
  void <a href="#dfn-CryptoOperation-method-abort">abort</a>();
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   811
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   812
  readonly attribute <a href="#dfn-Key">Key</a>? <a href="#dfn-CryptoOperation-key">key</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   813
  readonly attribute <a href="#dfn-Algorithm">Algorithm</a> <a href="#dfn-CryptoOperation-algorithm">algorithm</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   814
  readonly attribute any <a href="#dfn-CryptoOperation-result">result</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   815
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   816
  [TreatNonCallableasNull] attribute Function? <a href="#dfn-CryptoOperation-onabort">onabort</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   817
  [TreatNonCallableAsNull] attribute Function? <a href="#dfn-CryptoOperation-onerror">onerror</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   818
  [TreatNonCallableAsNull] attribute Function? <a href="#dfn-CryptoOperation-onprogress">onprogress</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   819
  [TreatNonCallableAsNull] attribute Function? <a href="#dfn-CryptoOperation-oncomplete">oncomplete</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   820
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   821
        </code></pre></div></div>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   822
        <div id="CryptoOperation-processing-model" class="section">
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   823
          <h3>12.1. Processing Model</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   824
          <p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   825
            Every <code>CryptoOperation</code> object must have a <dfn id="dfn-CryptoOperation-list-of-pending-data">list
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   826
            of pending data</dfn>. Each item in the list represents data that should be transformed by the
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   827
            cryptographic operation. The list functions as a queue that observes first-in, first-out ordering. That is,
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   828
            the order in which items are added shall reflect the order in which items are removed.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   829
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   830
          <p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   831
            When a CryptoOperation is said to <dfn id="dfn-CryptoOperation-process-data">process data</dfn>, the user
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   832
            agent must execute the following steps:
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   833
          </p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   834
          <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   835
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   836
              <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   837
                If there are no items in the <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   838
                data</a>, the algorithm is complete.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   839
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   840
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   841
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   842
              <dl class="switch">
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   843
                <dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   844
                  If the underlying cryptographic implementation does not support multi-part cryptographic operations for
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   845
                  the current <a href="#dfn-CryptoOperation-algorithm">algorithm</a>, perform the following steps:
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   846
                </dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   847
                <dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   848
                  <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   849
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   850
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   851
                        Let <var>bytes</var> be an empty sequence of bytes.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   852
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   853
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   854
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   855
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   856
                        For each item in the <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>:
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   857
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   858
                      <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   859
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   860
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   861
                            Let <var>item</var> be the oldest remaining item in the
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   862
                            <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   863
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   864
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   865
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   866
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   867
                            Remove <var>item</var> from the <a href="#dfn-CryptoOperation-list-of-pending-data">list of
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   868
                            pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   869
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   870
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   871
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   872
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   873
                            Convert <var>item</var> to a sequence of <code>byteLength</code> bytes from the underlying
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   874
                            <code>ArrayBuffer</code>, starting at the <code>byteOffset</code> of the <code>ArrayBufferView</code>,
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   875
                            and append those bytes to <var>bytes</var>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   876
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   877
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   878
                      </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   879
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   880
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   881
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   882
                        Perform the underlying cryptographic algorithm, using <var>bytes</var> as the input data.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   883
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   884
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   885
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   886
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   887
                        If the cryptographic operation fails, proceed to the error steps below:
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   888
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   889
                      <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   890
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   891
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   892
                            Update the internal state to <code>"error"</code>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   893
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   894
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   895
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   896
                          <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   897
                            <a href="#queue-a-task">Queue a task</a> to
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   898
                            <a href="#fire-a-simple-event">fire a simple event</a> named
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   899
                            <a href="#dfn-CryptoOperation-onerror"><code>onerror</code></a> at the
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   900
                            <a href="#dfn-CryptoOperation"><code>CryptoOperation</code></a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   901
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   902
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   903
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   904
                          <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   905
                            <a href="#terminate-the-algorithm">Terminate the algorithm</a>.
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   906
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   907
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   908
                      </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   909
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   910
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   911
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   912
                        Let <var>output</var> be the result of the underlying cryptographic algorithm.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   913
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   914
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   915
                  </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   916
                </dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   917
                <dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   918
                  Otherwise, if the underlying cryptographic implementation supports multi-part cryptographic operations
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   919
                  for the current <a href="#dfn-CryptoOperation-algorithm">algorithm</a>, perform the following
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   920
                  algorithm:
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   921
                </dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   922
                <dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   923
                  <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   924
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   925
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   926
                        Let <var>bytes</var> be an empty sequence of bytes.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   927
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   928
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   929
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   930
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   931
                        Let <var>item</var> be the oldest remaining item in the
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   932
                        <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   933
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   934
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   935
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   936
                      <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   937
                        Remove <var>item</var> from the <a href="#dfn-CryptoOperation-list-of-pending-data">list of
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   938
                        pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   939
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   940
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   941
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   942
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   943
                        Convert <var>item</var> to a sequence of <code>byteLength</code> bytes from the underlying
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   944
                        <code>ArrayBuffer</code>, starting at the <code>byteOffset</code> of the <code>ArrayBufferView</code>,
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   945
                        and append those bytes to <var>bytes</var>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   946
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   947
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   948
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   949
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   950
                        A <a href="#dfn-conforming-implementation">conforming user agent</a> <span class="RFC2119">MAY</span>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   951
                        repeat the preceeding steps as many times as desired, for as long as items remain in the
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   952
                        <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>, provided that the
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   953
                        output of the underlying cryptographic algorithm is indistinguishable from when only a single item is
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   954
                        processed at a time.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   955
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   956
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   957
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   958
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   959
                        Perform the underlying cryptographic algorithm, using <var>bytes</var> as the input data.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   960
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   961
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   962
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   963
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   964
                        If the cryptographic operation fails, proceed to the error steps below:
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   965
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   966
                      <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   967
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   968
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   969
                            Clear the <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   970
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   971
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   972
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   973
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   974
                            Update the internal state to <code>"error"</code>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   975
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   976
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   977
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   978
                          <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   979
                            <a href="#queue-a-task">Queue a task</a> to
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   980
                            <a href="#fire-a-simple-event">fire a simple event</a> named
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   981
                            <a href="#dfn-CryptoOperation-onerror"><code>onerror</code></a> at the
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   982
                            <a href="#dfn-CryptoOperation"><code>CryptoOperation</code></a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   983
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   984
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   985
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   986
                          <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
   987
                            <a href="#terminate-the-algorithm">Terminate the algorithm</a>.
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   988
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   989
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   990
                      </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   991
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   992
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   993
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   994
                        Let <var>output</var> be the result of the underlying cryptographic algorithm.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   995
                      </p>
18
ddc3bad3f496 Rename the methods from the createVerb-er factory style to simply "verb".
Ryan Sleevi <sleevi@google.com>
parents: 17
diff changeset
   996
                    </li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   997
                  </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   998
                </dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   999
              </dl>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1000
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1001
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1002
              <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1003
                Update <a href="#dfn-CryptoOperation-result"><code>result</code></a> with the algorithm-specific
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1004
                result using <var>output</var>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1005
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1006
              <div class="ednote"><div class="ednoteHeader">Editorial note</div>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1007
                <ul>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1008
                  <li>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1009
                    <p>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1010
                      <a href="http://www.w3.org/2012/webcrypto/track/issues/18">ISSUE-18</a>:
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1011
                      The wording here is presently ambiguous. It is modeled after the File API [<a href="#FileAPI">FileAPI</a>],
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1012
                      which has <code>result</code> accumulating the output as it becomes available. Because of this behaviour,
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1013
                      the entire cryptographic output is stored in <code>result</code> at the end of the operation.
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1014
                    </p>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1015
                    <p>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1016
                      In order to reduce the need to keep the entire cryptographic output in <code>result</code>, it has also been
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1017
                      requested to have an interface to support streaming/progressive output, in which only as much cryptographic
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1018
                      output as desired/requested is made available. How such functionality would be implemented, if at all,
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1019
                      remains to be determined.
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1020
                    </p>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1021
                  </li>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1022
                </ul>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1023
              </div>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1024
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1025
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1026
              <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1027
                <a href="#queue-a-task">Queue a task</a> to
20
2f4f03785843 Remove the subclasses of KeyOperation, treating all key-based operations as a
Ryan Sleevi <sleevi@google.com>
parents: 19
diff changeset
  1028
                <a href="#fire-a-simple-event">fire a simple event</a> named
2f4f03785843 Remove the subclasses of KeyOperation, treating all key-based operations as a
Ryan Sleevi <sleevi@google.com>
parents: 19
diff changeset
  1029
                <a href="#dfn-CryptoOperation-onprogress"><code>onprogress</code></a>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1030
                at the <a href="#dfn-CryptoOperation"><code>CryptoOperation</code></a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1031
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1032
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1033
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1034
              <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1035
                If the underlying cryptographic implementation supports multi-part cryptographic operations for the
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1036
                current <a href="#dfn-CryptoOperation-algorithm">algorithm</a>, repeat these steps for each item remaining
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1037
                in the <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1038
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1039
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1040
          </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1041
          <div class="ednote"><div class="ednoteHeader">Editorial note</div>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1042
            <ul>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1043
              <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1044
                <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1045
                  The above algorithm is meant to describe a possible way of supporting multi-part input (sometimes called "streaming"
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1046
                  or "progressive" input, but not to be confused with the Streams API [<a href="#StreamsAPI">StreamsAPI</a>]). The downside to the
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1047
                  above algorithm is that it does not describe a good interface for supporting algorithms that may support
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1048
                  multiple multi-part inputs.
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1049
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1050
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1051
                  An example of such an algorithm would be AES-GCM, which has two sources of input - the encrypted-and-authenticated
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1052
                  data ("ciphertext") and the authenticated data ("additional authenticated data"). A truly multi-part implementation
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1053
                  would allow both the plaintext/ciphertext and the authenticated data to be supplied independently, and in parts,
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1054
                  until <code>finish()</code> was called.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1055
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1056
                <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1057
                  However, at present, several major cryptographic APIs (CDSA, CNG, PKCS#11) do not support such uses, and so for now, the
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1058
                  details for handling multiple multi-part inputs have been omitted.
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1059
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1060
              </li>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1061
              <li>
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1062
                The above algorithm does not fully describe how to handle <a href="#dfn-CryptoOperation-method-abort"><code>abort</code></a>ing an in-progress operation.
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1063
              </li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1064
            </ul>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1065
          </div>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1066
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1067
        <div id="cryptooperation-events" class="section">
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1068
          <h3>12.2. Event Handler Attributes</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1069
          <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1070
            The following are the <a href="#event-handler-idl-attributes">event handler IDL attributes</a>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1071
            (and their corresponding <a href="#event-handler-event-type">event handler event
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1072
            types</a>) that user agents must support on the <a href="#dfn-CryptoOperation">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1073
            <code>CryptoOperation</code></a> as DOM attributes:
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1074
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1075
          <table>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1076
            <thead>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1077
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1078
                <th>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1079
                  <a href="#event-handler-idl-attributes" title="event handler IDL attributes">event
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1080
                  handler IDL attributes</a>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1081
                </th>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1082
                <th>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1083
                  <a href="#event-handler-event-type" title="event handler event types">event
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1084
                  handler event type</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1085
                </th>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1086
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1087
            </thead>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1088
            <tbody>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1089
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1090
                <td><dfn id="dfn-CryptoOperation-onabort">onabort</dfn></td>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
  1091
                <td>abort</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1092
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1093
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1094
                <td><dfn id="dfn-CryptoOperation-onerror">onerror</dfn></td>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
  1095
                <td>error</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1096
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1097
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1098
                <td><dfn id="dfn-CryptoOperation-onprogress">onprogress</dfn></td>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
  1099
                <td>progress</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1100
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1101
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1102
                <td><dfn id="dfn-CryptoOperation-oncomplete">oncomplete</dfn></td>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
  1103
                <td>complete</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1104
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1105
            </tbody>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1106
          </table>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1107
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1108
        <div id="CryptoOperation-attributes" class="section">
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1109
          <h3>12.3. Attributes</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1110
          <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1111
            <dt id="dfn-CryptoOperation-key"><code>key</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1112
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1113
              <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1114
                On getting, the <code>key</code> attribute returns the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1115
                <a href="#dfn-Key"><code>Key</code></a> used to initialize the <code>CryptoOperation</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1116
              </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1117
              <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1118
                If the <code>CryptoOperation</code> represents a keyless-operation, such as digesting,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1119
                then <code>key</code> <span class="RFC2119">MUST</span> return <code>null</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1120
              </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1121
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1122
            <dt id="dfn-CryptoOperation-algorithm"><code>algorithm</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1123
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1124
              On getting, the <code>algorithm</code> attribute returns the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1125
              <a href="#algorithm-normalizing-rules">normalized algorithm</a> of the algorithm used
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1126
              to initialize the <code>CryptoOperation</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1127
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1128
            <dt id="dfn-CryptoOperation-result"><code>result</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1129
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1130
              On getting, the <code>result</code> attribute returns the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1131
              <a href="#algorithm-result">algorithm-specific result</a> for the current
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1132
              <code>CryptoOperation</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1133
              <ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1134
                <li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1135
                  <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1136
                    On getting, if an error in performing the operation has occurred, then the
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1137
                    <code>result</code> attribute <span class="RFC2119">MUST</span> return
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1138
                    <code>null</code>.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1139
                  </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1140
                </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1141
              </ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1142
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1143
          </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1144
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1145
        <div id="CryptoOperation-methods" class="section">
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1146
          <h3>12.4. Methods</h3>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1147
          <div id="CryptoOperation-method-process" class="section">
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1148
            <h4>12.4.1. <dfn id="dfn-CryptoOperation-method-process"><code>process(ArrayBufferView data)</code></dfn></h4>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1149
            <p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1150
              When the <code>process(ArrayBufferView data)</code> method is called, the user agent must run
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1151
              the following steps:
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1152
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1153
            <ol>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1154
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1155
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1156
                  If the internal state is in the <code>"error"</code> state, throw an
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1157
                  <code>InvalidStateError</code> exception and abort these steps.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1158
                </p>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1159
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1160
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1161
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1162
                  Let <var>data</var> be the data to be processed.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1163
                </p>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1164
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1165
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1166
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1167
                  Add <var>data</var> to the <a href="#dfn-CryptoOperation-list-of-pending-data">list of pending data</a>.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1168
                </p>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1169
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1170
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1171
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1172
                  If the underlying cryptographic implementation for the specified
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1173
                  <a href="#dfn-CryptoOperation-algorithm">algorithm</a> supports multi-part cryptographic operations,
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1174
                  asynchrously <a href="#dfn-CryptoOperation-process-data">process data</a>, allowing the task that
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1175
                  invoked this algorithm to continue.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1176
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1177
                <div class="ednote"><div class="ednoteHeader">Editorial note</div>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1178
                  <p>
23
c78e44be0eee Cleanup prior to publishing next WD. Fixing broken links and addressing remaining feedback items raised during publication call.
Ryan Sleevi <sleevi@google.com>
parents: 22
diff changeset
  1179
                    Warning: The text here is currently ambiguous in terms of defining how the <a href="#event-loops">event loop</a>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1180
                    processes events; in particular, it leaves under-specified how the <a href="#dfn-CryptoOperation-method-abort">
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1181
                    <code>abort()</code></a> method should be handled when data is being processed.
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1182
                  </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1183
                </div>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1184
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <s&