Merge pull request #812 from w3c/issue-811-patch

robin-raymond · web-flow · commit 74123661f74c · 2018-01-29T14:46:00.000-05:00
RTCCertificate Interface compatibility with WebRTC 1.0
diff --git a/index.html b/index.html
@@ -2241,7 +2241,10 @@ <h3>Overview</h3>
       <h3>Operation</h3>
       <p>A <code><a>RTCDtlsTransport</a></code> instance is constructed
       using an <code><a>RTCIceTransport</a></code> and a sequence of
-      <code><a>RTCCertificate</a></code> objects.
+      <code><a>RTCCertificate</a></code> objects. Although any given DTLS
+      connection will use only one certificate, multiple certificates can be provided
+      that support different algorithms. The final certificate will be selected
+      based on the DTLS handshake, which establishes which certificates are allowed.
       An <code><a>RTCDtlsTransport</a></code> object in the <code>closed</code> or
       <code>failed</code> states can be garbage-collected when it is no longer
       referenced.</p>
@@ -8495,7 +8498,10 @@ <h3>Overview</h3>
       <h3>Operation</h3>
       <p>A <code><a>RTCQuicTransport</a></code> instance is constructed
       using an <code><a>RTCIceTransport</a></code> and a sequence of
-      <code><a>RTCCertificate</a></code> objects.
+      <code><a>RTCCertificate</a></code> objects. Although any given QUIC
+      connection will use only one certificate, multiple certificates can be provided
+      that support different algorithms. The final certificate will be selected
+      based on the QUIC handshake, which establishes which certificates are allowed.
       An <code><a>RTCQuicTransport</a></code> object in the <code>closed</code> or
       <code>failed</code> states can be garbage-collected when it is no longer
       referenced.</p>
@@ -10673,20 +10679,60 @@ <h2>Certificate Management</h2>
     <section id="rtccertificate-overview*">
       <h3>Overview</h3>
       <p>The <code>RTCCertificate</code> interface enables the certificates
-      used by an <code><a>RTCDtlsTransport</a></code> to be provided in the constructor.
-      This makes it possible to support forking, where the offerer will create multiple
-      <code><a>RTCDtlsTransport</a></code> objects using the same local certificate and
-      fingerprint.</p>
+      used by an <code><a>RTCDtlsTransport</a></code> or <code><a>RTCQuicTransport</a></code>
+      to be provided in the constructor. This makes it possible to support forking, where
+      the offerer will create multiple <code><a>RTCDtlsTransport</a></code> or
+      <code><a>RTCQuicTransport</a></code> objects using the same local certificate and
+      fingerprint. Also, an <code>RTCCertificate</code> can be persisted in
+      [[INDEXEDDB]] and reused. Persistence and reuse also avoids the
+      cost of key generation.</p>
     </section>
+    <section>
+        <h2><dfn>RTCCertificateExpiration</dfn> Dictionary</h2>
+        <p><code><a>RTCCertificateExpiration</a></code> is used to set an
+        expiration date on certificates generated by
+        <code><a>generateCertificate</a></code>.</p>
+        <pre class="idl">dictionary RTCCertificateExpiration {
+    [EnforceRange]
+    DOMTimeStamp expires;
+};</pre>
+        <dl data-link-for="RTCCertificateExpiration" data-dfn-for=
+        "RTCCertificateExpiration" class="methods">
+          <dt><dfn>expires</dfn></dt>
+          <dd>
+            <p>An optional <code>expires</code> attribute MAY be added to the
+            definition of the algorithm that is passed to
+            <code>generateCertificate</code>. If this
+            parameter is present it indicates the maximum time that the
+            <code><a>RTCCertificate</a></code> is valid for relative to the
+            current time.</p>
+            <p>When <code>generateCertificate</code> is called
+            with an <code><a>object</a></code> argument, the <a>user agent</a>
+            attempts to convert the object into an
+            <code><a>RTCCertificateExpiration</a></code>. If this is
+            unsuccessful, immediately return a promise that is <a>rejected</a> with a
+            newly <a data-link-for="exception" data-lt="create">created</a>
+            <code>TypeError</code> and abort processing.</p>
+            <p>A <a>user agent</a> generates a certificate that has an
+            expiration date set to the current time plus the value of the
+            <code>expires</code> attribute. The <a data-for=
+            "RTCCertificate"><code>expires</code></a> attribute of the returned
+            <a><code>RTCCertificate</code></a> is set to the expiration time of
+            the certificate. A <a>user agent</a> MAY choose to limit the value
+            of the <a data-for="RTCCertificate"><code>expires</code></a>
+            attribute.</p>
+          </dd>
+        </dl>
+      </section>
     <section>
       <h3><dfn>RTCCertificate</dfn> Interface</h3>
       <p>The <code>RTCCertificate</code> interface is described below.</p>
       <div>
         <pre class="idl">[Exposed=Window]
         interface RTCCertificate {
     readonly        attribute DOMTimeStamp       expires;
-    readonly        attribute RTCDtlsFingerprint fingerprint;
-    AlgorithmIdentifier            getAlgorithm ();
+    static sequence&lt;AlgorithmIdentifier&gt; getSupportedAlgorithms();
+    sequence&lt;RTCDtlsFingerprint&gt; getFingerprints ();
     static Promise&lt;RTCCertificate&gt; generateCertificate (AlgorithmIdentifier keygenAlgorithm);
 };</pre>
         <section>
@@ -10699,37 +10745,51 @@ <h2>Attributes</h2>
               <p>The <code>expires</code> attribute indicates the date and time in
               milliseconds relative to 1970-01-01T00:00:00Z after which the certificate
               will be considered invalid by the browser. After this time, attempts to
-              construct an <code><a>RTCDtlsTransport</a></code> object using this
-              certificate will fail.</p>
+              construct an object using this certificate will fail.</p>
               <p>Note that this value might not be reflected in a <code>notAfter</code>
               parameter in the certificate itself.</p>
             </dd>
-            <dt><dfn><code>fingerprint</code></dfn> of type <span class=
-            "idlAttrType"><a>RTCDtlsFingerprint</a></span>, readonly</dt>
-            <dd>
-              <p>The fingerprint of the certificate. As noted in [[!JSEP]] Section 5.2.1,
-              the digest algorithm used for the fingerprint matches that used in the
-              certificate signature.</p>
-            </dd>
           </dl>
         </section>
         <section>
           <h2>Methods</h2>
           <dl data-link-for="RTCCertificate" data-dfn-for="RTCCertificate" class=
           "methods">
-            <dt><dfn><code>getAlgorithm</code></dfn></dt>
-            <dd>
-              <p>Returns the value of <code>keygenAlgorithm</code> passed in the call to
-              <code>generateCertificate()</code>.</p>
-              <div class="issue atrisk">
-              <p>getAlgorithm is marked as a feature at risk, since there is no
-              clear commitment from implementers.</p>
-              </div>
-              <div>
-                <em>No parameters.</em>
-              </div>
-              <div>
-                <em>Return type:</em> <code>AlgorithmIdentifier</code>
+            <dt><dfn><code>getSupportedAlgorithms</code></dfn></dt>
+            <dd>
+                <p>Returns a sequence providing a representative set of supported
+                certificate algorithms. At least one algorithm MUST be returned.</p>
+                <div class="note">
+                  <p>For example, the "RSASSA-PKCS1-v1_5" algorithm dictionary,
+                  <code>RsaHashedKeyGenParams</code>, contains fields for the modulus
+                  length, public exponent, and hash algorithm. Implementations
+                  are likely to support a wide range of modulus lengths and exponents,
+                  but a finite number of hash algorithms. So in this case, it would be
+                  reasonable for the implementation to return one
+                  <code>AlgorithmIdentifier</code> for each supported hash algorithm
+                  that can be used with RSA, using default/recommended values for
+                  <code>modulusLength</code> and <code>publicExponent</code>
+                  (such as 1024 and 65537, respectively).</p>
+                </div>
+                <div>
+                  <em>No parameters.</em>
+                </div>
+                <div>
+                  <em>Return type:</em>
+                  sequence&lt;<code>AlgorithmIdentifier</code>&gt
+                </div>
+            </dd>
+            <dt><dfn><code>getFingerprints</code></dfn></dt>
+            <dd>
+                <p>Returns the list of certificate fingerprints, one of which is
+                computed with the digest algorithm used in the certificate
+                signature.</p>
+                <div>
+                  <em>No parameters.</em>
+                </div>
+                <div>
+                  <em>Return type:</em>
+                  sequence&lt;<code><a>RTCDtlsFingerprint</a></code>&gt
               </div>
             </dd>
             <dt><dfn><code>generateCertificate</code></dfn>, static</dt>
@@ -10739,9 +10799,8 @@ <h2>Methods</h2>
               X.509 certificate [[!X509V3]] and corresponding private key. A handle to
               information is provided in the form of the
               <code><a>RTCCertificate</a></code> interface. The returned
-              <code><a>RTCCertificate</a></code> can be used to control the certificate
-              that is offered in the DTLS session established by
-              <code><a>RTCDtlsTransport</a></code>.</p>
+              <code><a>RTCCertificate</a></code> can be used to control the certificates
+              that are offered in DTLS or QUIC.</p>
               <p>The <code>keygenAlgorithm</code> argument is used to control how the
               private key associated with the certificate is generated. The
               <code>keygenAlgorithm</code> argument uses the WebCrypto [[!WebCryptoAPI]]
@@ -10762,18 +10821,18 @@ <h2>Methods</h2>
               process produces an error, the call to <code>generateCertificate()</code>
               <em title="MUST" class="rfc2119">MUST</em> be <a>rejected</a> with that error.</p>
               <p>Signatures produced by the generated key are used to authenticate the
-              DTLS connection. The identified algorithm (as identified by the
+              DTLS or QUIC connection. The identified algorithm (as identified by the
               <code>name</code> of the normalized <code>AlgorithmIdentifier</code>)
               <em title="MUST" class="rfc2119">MUST</em> be an asymmetric algorithm that
               can be used to produce a signature.</p>
               <p>The certificate produced by this process also contains a signature. The
               validity of this signature is only relevant for compatibility reasons. Only
               the public key and the resulting certificate fingerprint are used by
-              <code><a>RTCDtlsTransport</a></code>, but it is more likely that a
-              certificate will be accepted if the certificate is well formed. The browser
-              selects the algorithm used to sign the certificate; a browser <em title=
-              "SHOULD" class="rfc2119">SHOULD</em> select SHA-256 [[!FIPS-180-4]] if a
-              hash algorithm is needed.</p>
+              <code><a>RTCDtlsTransport</a></code> or <code><a>RTCQuicTransport</a></code>,
+              but it is more likely that a certificate will be accepted if the certificate
+              is well formed. The browser selects the algorithm used to sign the certificate;
+              a browser <em title="SHOULD" class="rfc2119">SHOULD</em> select
+              SHA-256 [[!FIPS-180-4]] if a hash algorithm is needed.</p>
               <p>The resulting certificate <em title="MUST NOT" class="rfc2119">MUST
               NOT</em> include information that can be linked to a user or <a class=
               "internalDFN" href="#dfn-user-agent">user agent</a>. Randomized values for
