Skip to content

Commit

Permalink
Merge pull request #812 from w3c/issue-811-patch
Browse files Browse the repository at this point in the history 
RTCCertificate Interface compatibility with WebRTC 1.0
  • Loading branch information
@robin-raymond
robin-raymond committed Jan 29, 2018
2 parents e8023ce + 9358358 commit 7412366
Showing 1 changed file with 98 additions and 39 deletions.
137 changes: 98 additions & 39 deletions index.html
View file
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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>
Expand All @@ -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]]
Expand All @@ -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
Expand Down

0 comments on commit 7412366

Please sign in to comment.