spec/Overview-WebCryptoAPI.xml
author David Dahl <ddahl@mozilla.com>
Tue, 21 May 2013 13:01:23 -0500
changeset 45 45c433f19151
parent 43 f32607659446
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
<?xml version='1.0'?>
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.xml
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     5
I reuse WebIDL.xsl 
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
This is written in XHTML 1.0 Strict with an inline <options> element that
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     8
helps the WebIDL.xsl stylesheet process the document (generating a table
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
     9
of contents, section numbers, certain processing instructions).
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    10
-->
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    11
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    12
<?xml-stylesheet href='WebIDL.xsl' type='text/xsl'?>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    13
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    14
<html xmlns='http://www.w3.org/1999/xhtml' xmlns:x='http://mcc.id.au/ns/local' xml:lang='en'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    15
  <head>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    16
    <meta http-equiv='Content-Type' content='text/html; charset=UTF-8'/>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    17
    <title>Web Cryptography API</title>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    18
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    19
    <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
    20
    <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
    21
      .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
    22
      .XXX > :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
    23
      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
    24
    </style>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    25
    <script src='section-links.js' type='application/ecmascript'/>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    26
    <script src='dfn.js' type='application/ecmascript'/>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    27
    <!--[if IE]>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    28
        <style type='text/css'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    29
        .ignore {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    30
        -ms-filter:"progid:DXImageTransform.Microsoft.Alpha(Opacity=50)";
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    31
        filter: alpha(opacity=50);
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
        </style>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    34
        <![endif]-->
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    35
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    36
    <options xmlns='http://mcc.id.au/ns/local'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    37
      <versions>
2
d73cb1b6596e Update URLs for ED vs WD
Ryan Sleevi <sleevi@google.com>
parents: 1
diff changeset
    38
        <cvs href='http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html' />
d73cb1b6596e Update URLs for ED vs WD
Ryan Sleevi <sleevi@google.com>
parents: 1
diff changeset
    39
        <this href='http://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html' />
22
f5e8d9a3e18f Update the link to the previous version for this batch of changes (old CVS base version)
Ryan Sleevi <sleevi@google.com>
parents: 21
diff changeset
    40
        <previous href='https://dvcs.w3.org/hg/webcrypto-api/raw-file/0fe9b34c13fb/spec/Overview.html' />
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    41
        <latest href='http://www.w3.org/TR/WebCryptoAPI/' />
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    42
      </versions>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    43
      <editors>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    44
        <person homepage='http://ddahl.com/' email='ddahl@mozilla.com'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    45
          <name>David Dahl</name>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    46
          <affiliation>Mozilla Corporation</affiliation>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    47
        </person>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    48
        <person homepage='http://www.google.com/' email='sleevi@google.com'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    49
          <name>Ryan Sleevi</name>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    50
          <affiliation>Google, Inc.</affiliation>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    51
        </person>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    52
      </editors>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    53
      <maturity>ED</maturity>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    54
      <participate qual="STND"></participate>  
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    55
    </options>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    56
  </head>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    57
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    58
  <body>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    59
    <?top?>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    60
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    61
    <div class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    62
      <h2>Abstract</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    63
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    64
This specification describes a JavaScript API for performing basic
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    65
cryptographic operations in web applications, such as hashing,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    66
signature generation and verification, and encryption and decryption.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    67
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
    68
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
    69
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
    70
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
    71
communications.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    72
      </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    73
  
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    74
      <?revision-note?>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    75
    </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    76
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    77
    <div class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
    78
      <h2>Status of this Document</h2>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    79
      <?sotd-top public-webcrypto-comments@w3.org http://lists.w3.org/Archives/Public/public-webcrypto-comments/ ?>
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    80
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
    81
      <p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    82
        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
    83
        <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
    84
      </p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
    85
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
    86
      <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
    87
        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
    88
        <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
    89
        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
    90
        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
    91
        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
    92
      </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
    93
      <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
    94
        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
    95
        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
    96
        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
    97
        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
    98
      </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
    99
      <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
   100
        <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
   101
        <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
   102
        <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
   103
      </ul>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   104
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   105
        Previous discussion of this specification has taken place on three other
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   106
        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
   107
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   108
        (<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
   109
        , <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
   110
        (<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
   111
        <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
   112
        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
   113
        mailing list.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   114
      </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   115
      
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
        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
   118
        <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
   119
        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
   120
        to Web Cryptography.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   121
        <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
   122
        <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
   123
        are available.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   124
      </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   125
      <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   126
        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
   127
        <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
   128
      </p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   129
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   130
      <?sotd-bottom http://www.w3.org/2004/01/pp-impl/54174/status?>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   131
    </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   132
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   133
    <div id='toc'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   134
      <h2>Table of Contents</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   135
      <?toc sections appendices?>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   136
    </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   137
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   138
    <div id='sections'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   139
      <div id='introduction' class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   140
        <h2>Introduction</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   141
        <p class='norm'>This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   142
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   143
          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
   144
          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
   145
          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
   146
          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
   147
          verification, hashing and verification, encryption and decryption, without requiring
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   148
          access to the raw keying material.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   149
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   150
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   151
          Cryptographic transformations are exposed via the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   152
          <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
   153
          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
   154
          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
   155
          generation and verification, hashing and verification, and encryption and decryption,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   156
          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
   157
          and key discovery.
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
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   160
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   161
      <div id="use-cases" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   162
        <h2>Use Cases</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   163
        <p class='norm'>This section is non-normative</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   164
        <div id="multifactor-authentication" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   165
          <h3>Multi-factor Authentication</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   166
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   167
            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
   168
            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
   169
            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
   170
            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
   171
            experience by providing authentication within the application itself.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   172
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   173
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   174
            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
   175
            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
   176
            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
   177
            as decrypting an authentication challenge followed by signing an authentication response.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   178
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   179
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   180
            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
   181
            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
   182
            properties of the underlying transport.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   183
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   184
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   185
            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
   186
            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
   187
            the user's choosing. 
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
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   190
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   191
        <div id="protected-document" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   192
          <h3>Protected Document Exchange</h3>
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
            When exchanging documents that may contain sensitive or personal information, a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   195
            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
   196
            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
   197
            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
   198
            with the public keys associated with authorized users.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   199
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   200
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   201
            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
   202
            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
   203
            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
   204
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   205
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   206
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   207
        <div id="cloud-storage" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   208
          <h3>Cloud Storage</h3>
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 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
   211
            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
   212
            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
   213
            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
   214
            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
   215
            using existing APIs.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   216
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   217
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   218
            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
   219
            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
   220
            protected data with himself in the future.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   221
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   222
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   223
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   224
        <div id="document-signing" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   225
          <h3>Document Signing</h3>
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
            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
   228
            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
   229
            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
   230
            client generated specifically for the web application.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   231
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   232
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   233
            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
   234
            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
   235
            the document.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   236
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   237
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   238
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   239
        <div id="data-integrity-protection" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   240
          <h3>Data Integrity Protection</h3>
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
            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
   243
            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
   244
            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
   245
            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
   246
            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
   247
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   248
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   249
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   250
        <div id="secure-messaging" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   251
          <h3>Secure Messaging</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   252
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   253
            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
   254
            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
   255
            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
   256
            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
   257
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   258
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   259
            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
   260
            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
   261
            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
   262
            messages through the MACs.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   263
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   264
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   265
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   266
        <div id="jose" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   267
          <h3>Javascript Object Signing and Encryption (JOSE)</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   268
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   269
            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
   270
            messages defined by the IETF Javascript Object Signing and Encryption
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   271
            (JOSE) Working Group. The web application wishes to manipulate public
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   272
            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
   273
            integrity protected using digital signatures or MACs (JWS), or that
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   274
            have been encrypted (JWE).
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   275
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   276
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   277
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   278
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   279
      
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   280
      <div id='conformance' class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   281
        <h2>Conformance</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   282
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   283
          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
   284
          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
   285
          this specification is normative.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   286
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   287
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   288
          The keywords <span class='RFC2119'>MUST</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   289
          <span class='RFC2119'>MUST NOT</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   290
          <span class='RFC2119'>REQUIRED</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   291
          <span class='RFC2119'>SHALL</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   292
          <span class='RFC2119'>SHALL NOT</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   293
          <span class='RFC2119'>RECOMMENDED</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   294
          <span class='RFC2119'>MAY</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   295
          <span class='RFC2119'>OPTIONAL</span>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   296
          in this specification are to be interpreted as described in 
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   297
          <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
   298
          Indicate Requirement Levels</a></cite> [<a href='#RFC2119'>RFC2119</a>].
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   299
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   300
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   301
          The following conformance classes are defined by this specification:
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   302
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   303
        <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   304
          <dt><dfn id='dfn-conforming-implementation'>conforming user agent</dfn></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   305
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   306
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   307
              A user agent is considered to be a
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   308
              <a class='dfnref' href='#dfn-conforming-implementation'>conforming user agent</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   309
              if it satisfies all of the <span class='RFC2119'>MUST</span>-,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   310
              <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
   311
              criteria in this specification that apply to implementations. This specification
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   312
              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
   313
              product class.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   314
            </p>
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
              User agents <span class='RFC2119'>MAY</span> implement algorithms in this
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   317
              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
   318
              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
   319
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   320
          </dd>         
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   321
        </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   322
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   323
          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
   324
          <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
   325
          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
   326
          as this specification uses that specification and terminology.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   327
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   328
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   329
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   330
      <div id='scope' class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   331
        <h2>Scope</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   332
        <p class='norm'>This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   333
        <div class="section" id="scope-abstraction">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   334
          <h3>Level of abstraction</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   335
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   336
            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
   337
            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
   338
            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
   339
            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
   340
            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
   341
            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
   342
            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
   343
            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
   344
            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
   345
            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
   346
            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
   347
            aware of the nature of the underlying key storage.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   348
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   349
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   350
        <div class="section" id="scope-algorithms">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   351
          <h3>Cryptographic algorithms</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   352
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   353
            Because the underlying cryptographic implementations will vary between conforming user agents,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   354
            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
   355
            or industry regulation, security best practices, intellectual property concerns, and
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   356
            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
   357
            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
   358
            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
   359
            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
   360
            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
   361
            implemented.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   362
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   363
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   364
        <div class="section" id="scope-operations">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   365
          <h3>Operations</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   366
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   367
            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
   368
            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
   369
            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
   370
            cryptographic operations involving that key.
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-out-of-scope">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   374
          <h3>Out of scope</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
            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
   377
            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
   378
            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
   379
            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
   380
            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
   381
            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
   382
            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
   383
            cryptographic libraries, and implementations.
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
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   386
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   387
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   388
      <div id="security" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   389
        <h2>Security considerations</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   390
        <p class='norm'>This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   391
        <div id="security-implementers" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   392
          <h2>Security considerations for implementers</h2>
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
            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
   395
            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
   396
            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
   397
            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
   398
            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
   399
            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
   400
            trust relationship.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   401
          </p>
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 be aware of the security considerations of each algorithm
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   404
            implemented and exposed to applications. For a number of algorithms, their
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   405
            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
   406
            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
   407
            through the repeatedly iterating through the same algorithm to reduce its
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   408
            susceptibility to brute force. Implementations should therefore take measures to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   409
            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
   410
            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
   411
            may call certain APIs/algorithms, and defining implementation-specific upper limits
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   412
            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
   413
            which the implementation executes.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   414
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   415
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   416
            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
   417
            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
   418
            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
   419
            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
   420
            applications to recover the raw material.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   421
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   422
          <div class="ednote">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   423
            <ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   424
              <li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   425
                <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
   426
                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
   427
                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
   428
                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
   429
                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
   430
                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
   431
                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
   432
                it might cause.
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
            </ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   435
          </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   436
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   437
        <div id="security-developers" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   438
          <h2>Security considerations for developers</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   439
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   440
            While this API provides important functionality for the development of secure
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   441
            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
   442
            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
   443
            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
   444
            functionality such as Content Security Policy and the use of TLS.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   445
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   446
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   447
            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
   448
            security issues when used inappropriately. Application developers should take care to
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   449
            review the appropriate cryptographic literature before making use of certain algorithms,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   450
            and should avoid attempting to develop new cryptographic protocols whenever possible.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   451
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   452
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   453
            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
   454
            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
   455
            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
   456
            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
   457
            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
   458
            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
   459
            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
   460
            the key.
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
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   463
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   464
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   465
      <div id="privacy" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   466
        <h2>Privacy considerations</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   467
        <p class='norm'>This section is non-normative.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   468
        <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   469
          <dt>Fingerprinting</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   470
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   471
            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
   472
            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
   473
            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
   474
            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
   475
            more accurately than just the particular user agent.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   476
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   477
          <dt>Tracking</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   478
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   479
            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
   480
            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
   481
            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
   482
            to access a common key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   483
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   484
          <dt>Super-cookies</dt>
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
            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
   487
            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
   488
            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
   489
            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
   490
            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
   491
            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
   492
            revoke these keys.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   493
            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
   494
            [<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
   495
            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
   496
            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
   497
            no user interaction was provided.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   498
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   499
        </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   500
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   501
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   502
      <div id='dependencies' class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   503
        <h3>Dependencies</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   504
        <p>This specification relies on underlying specifications.</p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   505
        <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   506
          <dt>DOM</dt>
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
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   509
              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
   510
              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
   511
              upon; in particular, it MUST support <code>EventTarget</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   512
              [<a href="#DOM4">DOM4</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   513
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   514
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   515
          <dt>HTML</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 HTML that this specification relies
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   520
              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
   521
              <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
   522
              [<a href="#HTML">HTML</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   523
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   524
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   525
          <dt>Web IDL</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   526
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   527
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   528
              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
   529
              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
   530
              the Web IDL specification. [<a href="#WebIDL">WebIDL</a>]
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   531
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   532
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   533
          <dt>Typed Arrays</dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   534
          <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   535
            <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   536
              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
   537
              Typed Arrays specification [<a href="#TypedArrays">TypedArrays</a>].
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   538
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   539
          </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   540
        </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   541
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   542
   
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   543
      <div id='terminology' class='section'>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   544
        <h2>Terminology</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   545
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   546
          The terms and algorithms
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   547
          <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
   548
          <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
   549
          <dfn id="event-handler-event-type">event handler event type</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   550
          <dfn id="origin">origin</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   551
          <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
   552
          <dfn id="df-URL">URL</dfn>,
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   553
          <dfn id="event-loops">event loops</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   554
          <dfn id="dfn-task">task</dfn>,
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   555
          <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
   556
          <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
   557
          <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
   558
          <dfn id="structured-clone">structured clone</dfn>,
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   559
          are defined by the HTML specification [<a href="#HTML">HTML</a>].
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   560
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   561
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   562
          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
   563
          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
   564
          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
   565
          cryptographic algorithm that may be in the midst of processing.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   566
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   567
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   568
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
   569
      <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
   570
        <h2>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
   571
        <x:codeblock language="idl">
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
   572
[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
   573
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
   574
  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
   575
};
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
   576
        </x:codeblock>
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
   577
        <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
   578
          <h3>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
   579
          <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
   580
            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
   581
            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
   582
          </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
   583
          <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
   584
            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
   585
            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
   586
            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
   587
            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
   588
            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
   589
            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
   590
          </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
   591
          <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
   592
            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
   593
            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
   594
            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
   595
            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
   596
            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
   597
            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
   598
            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
   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
        </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
   601
        <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
   602
          <h3>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
   603
          <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
   604
            <h4>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
   605
            <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
   606
              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
   607
              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
   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
            <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
   610
              <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
   611
                <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
   612
                  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
   613
                  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
   614
                  <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
   615
                  <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
   616
                </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
   617
              </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
   618
              <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
   619
                <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
   620
                  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
   621
                  <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
   622
                  <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
   623
                </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
   624
              </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
   625
              <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
   626
                <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
   627
                  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
   628
                  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
   629
                </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
   630
              </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
   631
              <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
   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
                  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
   634
                </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
   635
              </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
   636
            </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
   637
            <div class="note">
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
   638
              <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
   639
                Do not generate keys using the <code>getRandomValues</code> method. Use the
41
0a055470d6ac Fix incorrect links from SubtleSubtleCrypto -> SubtleCrypto
Ryan Sleevi <sleevi@google.com>
parents: 40
diff changeset
   640
                <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
   641
              </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
   642
            </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
   643
          </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
   644
        </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
   645
      </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
   646
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
   647
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   648
      <div id="algorithm-dictionary" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   649
        <h2>Algorithm dictionary</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   650
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   651
          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
   652
          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
   653
          specify the desired operation.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   654
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   655
        <x:codeblock language="idl">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   656
<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
   657
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
   658
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   659
dictionary <dfn id="dfn-Algorithm">Algorithm</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   660
  DOMString <a href="#dfn-Algorithm-name">name</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   661
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   662
        </x:codeblock>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   663
        <div id="algorithm-dictionary-members" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   664
          <h3><a href="#dfn-Algorithm">Algorithm</a> Dictionary Members</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   665
          <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   666
            <dt id="dfn-Algorithm-name">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   667
              <code>name</code>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   668
            </dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   669
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   670
              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
   671
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   672
          </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   673
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   674
      </div>
6
9baa26b28e78 ISSUE-17 and ISSUE-25: Remove the KeyAttributes object
Ryan Sleevi <sleevi@google.com>
parents: 5
diff changeset
   675
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   676
      <div id="key-interface" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   677
        <h2>Key interface</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   678
        <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   679
          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
   680
          user agent.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   681
        </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   682
        <x:codeblock language="idl">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   683
enum <dfn id="dfn-KeyType">KeyType</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   684
  "secret",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   685
  "public",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   686
  "private"
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   687
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   688
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   689
enum <dfn id="dfn-KeyUsage">KeyUsage</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   690
  "encrypt",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   691
  "decrypt",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   692
  "sign",
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   693
  "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: 41
diff changeset
   694
  "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: 41
diff changeset
   695
  "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: 41
diff changeset
   696
  "unwrap"
0
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
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   699
interface <dfn id="dfn-Key">Key</dfn> {
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   700
  readonly attribute KeyType <a href="#dfn-Key-type">type</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   701
  readonly attribute bool <a href="#dfn-Key-extractable">extractable</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   702
  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
   703
  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
   704
};
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   705
        </x:codeblock>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   706
        <div id="key-interface-description" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   707
          <h3>Description</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   708
          <span class="normative">This section is non-normative</span>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   709
          <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   710
            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
   711
            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
   712
            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
   713
            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
   714
            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
   715
            any keying material including actual keys for cryptographic operations and secret
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   716
            values obtained within key derivation or exchange operations.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   717
          </p>
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
            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
   720
            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
   721
            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
   722
            <a href="#dfn-CryptoOperation">CryptoOperation</a>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   723
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   724
        </div>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   725
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   726
        <div id="key-interface-members" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   727
          <h3>Key interface members</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   728
          <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   729
            <dt id="dfn-Key-type"><code>type</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   730
            <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
   731
              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
   732
              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
   733
              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
   734
              <code>"public"</code> or <code>"private"</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   735
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   736
            <dt id="dfn-Key-extractable"><code>extractable</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   737
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   738
              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
   739
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   740
            <dt id="dfn-Key-algorithm"><code>algorithm</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   741
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   742
              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
   743
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   744
            <dt id="dfn-Key-keyUsage"><code>keyUsage</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   745
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   746
              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
   747
              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
   748
              key.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   749
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   750
          </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   751
        </div>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   752
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   753
        <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
   754
          <h3>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
   755
          <p>
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   756
            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
   757
            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
   758
          </p>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   759
          <ol>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   760
            <li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   761
              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
   762
              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
   763
              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
   764
            </li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   765
            <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
   766
            <li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   767
              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
   768
              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
   769
              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
   770
              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
   771
              <ul>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   772
                <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
   773
                <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
   774
                <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
   775
                <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
   776
              </ul>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   777
            </li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   778
            <li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   779
              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
   780
              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
   781
            </li>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   782
          </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
   783
          <div class="note">
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
   784
            <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
   785
            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
   786
            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
   787
            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
   788
            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
   789
            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
   790
          </div>
4
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   791
        </div>
7b55923657e7 Remove the KeyStorage interface in favor of defining a structured clone
Ryan Sleevi <sleevi@google.com>
parents: 3
diff changeset
   792
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   793
      </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   794
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   795
      <div id="cryptooperation-interface" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   796
        <h2>CryptoOperation interface</h2>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   797
        <x:codeblock language="idl">
24
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   798
interface <dfn id="dfn-CryptoOperation">CryptoOperation</dfn> : EventTarget {
60de9e02a40b Fix additional PubRules violations, such as:
Ryan Sleevi <sleevi@google.com>
parents: 23
diff changeset
   799
  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
   800
  void <a href="#dfn-CryptoOperation-method-finish">finish</a>();
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   801
  void <a href="#dfn-CryptoOperation-method-abort">abort</a>();
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   802
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   803
  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
   804
  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
   805
  readonly attribute any <a href="#dfn-CryptoOperation-result">result</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   806
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   807
  [TreatNonCallableasNull] attribute Function? <a href="#dfn-CryptoOperation-onabort">onabort</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   808
  [TreatNonCallableAsNull] attribute Function? <a href="#dfn-CryptoOperation-onerror">onerror</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   809
  [TreatNonCallableAsNull] attribute Function? <a href="#dfn-CryptoOperation-onprogress">onprogress</a>;
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   810
  [TreatNonCallableAsNull] attribute Function? <a href="#dfn-CryptoOperation-oncomplete">oncomplete</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
        </x:codeblock>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   813
        <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
   814
          <h3>Processing Model</h3>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   815
          <p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   816
            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
   817
            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
   818
            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
   819
            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
   820
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
   821
          <p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   822
            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
   823
            agent must execute the following steps:
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
          <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   826
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   827
              <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
   828
                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
   829
                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
   830
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   831
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   832
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   833
              <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
   834
                <dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   835
                  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
   836
                  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
   837
                </dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   838
                <dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   839
                  <ol>
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
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   842
                        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
   843
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   844
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   845
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   846
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   847
                        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
   848
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   849
                      <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   850
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   851
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   852
                            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
   853
                            <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
   854
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   855
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   856
                        <li>
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
                            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
   859
                            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
   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
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   862
                        <li>
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
                            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
   865
                            <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
   866
                            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
   867
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   868
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   869
                      </ol>
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
                        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
   874
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   875
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   876
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   877
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   878
                        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
   879
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   880
                      <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   881
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   882
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   883
                            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
   884
                          </p>
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
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   887
                          <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
   888
                            <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
   889
                            <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
   890
                            <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
   891
                            <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
   892
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   893
                        </li>
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
                          <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
   896
                            <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
   897
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   898
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   899
                      </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   900
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   901
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   902
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   903
                        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
   904
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   905
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   906
                  </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   907
                </dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   908
                <dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   909
                  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
   910
                  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
   911
                  algorithm:
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   912
                </dt>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   913
                <dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   914
                  <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   915
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   916
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   917
                        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
   918
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   919
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   920
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   921
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   922
                        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
   923
                        <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
   924
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   925
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   926
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   927
                      <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
   928
                        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
   929
                        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
   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
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   932
                    <li>
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
                        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
   935
                        <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
   936
                        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
   937
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   938
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   939
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   940
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   941
                        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
   942
                        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
   943
                        <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
   944
                        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
   945
                        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
   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
                        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
   951
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   952
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   953
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   954
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   955
                        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
   956
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   957
                      <ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   958
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   959
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   960
                            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
   961
                          </p>
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
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   964
                          <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   965
                            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
   966
                          </p>
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
                        <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   969
                          <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
   970
                            <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
   971
                            <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
   972
                            <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
   973
                            <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
   974
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   975
                        </li>
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
                          <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
   978
                            <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
   979
                          </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   980
                        </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   981
                      </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   982
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   983
                    <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   984
                      <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   985
                        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
   986
                      </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   987
                    </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   988
                  </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   989
                </dd>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   990
              </dl>
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
                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
   995
                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
   996
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
   997
              <div class="ednote">
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
   998
                <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
   999
                  <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
  1000
                    <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
  1001
                      <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
  1002
                      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
  1003
                      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
  1004
                      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
  1005
                    </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
  1006
                    <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
  1007
                      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
  1008
                      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
  1009
                      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
  1010
                      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
  1011
                    </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
  1012
                  </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
  1013
                </ul>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1014
              </div>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1015
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1016
            <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1017
              <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
  1018
                <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
  1019
                <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
  1020
                <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
  1021
                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
  1022
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1023
            </li>
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
              <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
  1026
                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
  1027
                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
  1028
                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
  1029
              </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1030
            </li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1031
          </ol>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1032
          <div class="ednote">
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1033
            <ul>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1034
              <li>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1035
                <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
  1036
                  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
  1037
                  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
  1038
                  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
  1039
                  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
  1040
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1041
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1042
                  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
  1043
                  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
  1044
                  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
  1045
                  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
  1046
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1047
                <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
  1048
                  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
  1049
                  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
  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
              </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
  1052
              <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
  1053
                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
  1054
              </li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1055
            </ul>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1056
          </div>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1057
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1058
        <div id="cryptooperation-events" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1059
          <h3>Event Handler Attributes</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1060
          <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
  1061
            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
  1062
            (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
  1063
            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
  1064
            <code>CryptoOperation</code></a> as DOM attributes:
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1065
          </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1066
          <table>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1067
            <thead>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1068
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1069
                <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
  1070
                  <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
  1071
                  handler IDL attributes</a>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1072
                </th>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1073
                <th>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1074
                  <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
  1075
                  handler event type</a>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1076
                </th>
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
            </thead>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1079
            <tbody>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1080
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1081
                <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
  1082
                <td>abort</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1083
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1084
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1085
                <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
  1086
                <td>error</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1087
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1088
              <tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1089
                <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
  1090
                <td>progress</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1091
              </tr>
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
                <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
  1094
                <td>complete</td>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1095
              </tr>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1096
            </tbody>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1097
          </table>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1098
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1099
        <div id="CryptoOperation-attributes" class="section">
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1100
          <h3>Attributes</h3>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1101
          <dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1102
            <dt id="dfn-CryptoOperation-key"><code>key</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1103
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1104
              <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1105
                On getting, the <code>key</code> attribute returns the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1106
                <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
  1107
              </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1108
              <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1109
                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
  1110
                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
  1111
              </p>
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
            <dt id="dfn-CryptoOperation-algorithm"><code>algorithm</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1114
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1115
              On getting, the <code>algorithm</code> attribute returns the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1116
              <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
  1117
              to initialize the <code>CryptoOperation</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1118
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1119
            <dt id="dfn-CryptoOperation-result"><code>result</code></dt>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1120
            <dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1121
              On getting, the <code>result</code> attribute returns the
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1122
              <a href="#algorithm-result">algorithm-specific result</a> for the current
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1123
              <code>CryptoOperation</code>.
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1124
              <ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1125
                <li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1126
                  <p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1127
                    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
  1128
                    <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
  1129
                    <code>null</code>.
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1130
                  </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1131
                </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1132
              </ul>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1133
            </dd>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1134
          </dl>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1135
        </div>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1136
        <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
  1137
          <h3>Methods</h3>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1138
          <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
  1139
            <h4><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
  1140
            <p>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1141
              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
  1142
              the following steps:
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1143
            </p>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1144
            <ol>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1145
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1146
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1147
                  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
  1148
                  <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
  1149
                </p>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1150
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1151
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1152
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1153
                  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
  1154
                </p>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1155
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1156
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1157
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1158
                  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
  1159
                </p>
0
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1160
              </li>
ca944b205467 Initial commit from CVS
Ryan Sleevi <sleevi@google.com>
parents:
diff changeset
  1161
              <li>
17
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1162
                <p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1163
                  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
  1164
                  <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
  1165
                  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
  1166
                  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
  1167
                </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1168
                <div class="ednote">
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1169
                  <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
  1170
                    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
  1171
                    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
  1172
                    <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
  1173
                  </p>
38a2944310c4 Attempt to describe how the multi-part process() method works, in particular
Ryan Sleevi <sleevi@google.com>
parents: 16
diff changeset
  1174
                </div>
0
ca944b205467 Initial commit from CVS