Certificate management API in 1.0 pull request #195

robin-raymond opened this Issue Apr 21, 2015 · 9 comments


None yet

3 participants

@robin-raymond robin-raymond added the 1.0 label Apr 21, 2015
aboba commented Jun 24, 2015

Resolution discussed at the ORTC CG meeting was to make the WebRTC 1.0 certificate management API mandatory-to-implement in ORTC, and use it to resolve other issues (210, 211, 218). Peter Thatcher suggested adding a static generateCertificate method to RTCDtlsTransport.

@aboba aboba added the 1.1 label Jun 24, 2015
aboba commented Aug 27, 2015

Potential text of a new Section 15 below, which assumes a new RTCCertificate object (instead of just adding a generateCertificate method to DtlsTransport ).

  1. Certificate Management

This section of the ORTC API specification depends on the WebRTC 1.0 Certificate Management API, which was recently introduced and is still a work-in-progress.

15.1 Overview

The RTCCertificate interface enables the certificates used by an RTCDtlsTransport to be provided in the constructor. This makes it possible to support forking, where the offerer will create multiple RTCDtlsTransport objects using the same local certificate and fingerprint.

15.2 RTCCertificate Interface

The Certificate API is described below.

interface RTCCertificate {
readonly attribute Date expires;
readonly attribute RTCDtlsFingerprint fingerprint;
static Promise generateCertificate (AlgorithmIdentifier keygenAlgorithm);

15.2.1 Attributes

expires of type Date, readonly
The expires attribute indicates the date and time after which the certificate will be considered invalid by the browser. After this time, attempts to construct an RTCDtlsTransport using this certificate fail.

Note that this value might not be reflected in a notAfter parameter in the certificate itself.

fingerprint of type RTCDtlsFingerprint, readonly
The fingerprint of the certificate.

15.2.2 Methods

generateCertificate, static
The generateCertificate function causes the user agent to create and store an X.509 certificate [X509V3] and corresponding private key. A handle to information is provided in the form of the RTCCertificate interface. The returned RTCCertificate can be used to control the certificate that is offered in the DTLS sessions established by RTCDtlsTransport.

The keygenAlgorithm argument is used to control how the private key associated with the certificate is generated. The keygenAlgorithm argument uses the WebCrypto [WebCryptoAPI] AlgorithmIdentifier type. The keygenAlgorithm value must be a valid argument to Crypto.subtle.generateKey; that is, the value must produce a non-error result when normalized according to the WebCrypto algorithm normalization process [WebCryptoAPI] with an operation name of generateKey and a [[supportedAlgorithms]] value specific to production of certificates for RTCDtlsTransport.

Signatures produced by the generated key are used to authenticate the DTLS connection. The identified algorithm (as identified by the name of the normalized AlgorithmIdentifier) must be an asymmetric algorithm that can be used to produce a signature.

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 RTCDtlsTransport, 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 should select SHA-256 [FIPS-180-3] if a hash algorithm is needed.

The resulting certificate must not include information that can be linked to a user or user agent. Randomized values for distinguished name and serial number should be used.

A user agent must reject a call to generateCertificate() with a DOMError of type "InvalidAccessError" if the keygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCDtlsTransport.

The following values must be supported by a user agent: { name: "RSASSA-PKCS1-v1_5", modulusLength: 2048, publicExponent: 65537 }, and { name: "ECDSA", namedCurve: "P-256" }.

It is expected that a user agent will have a small or even fixed set of values that it will accept.

Parameter Type Nullable Optional Description
keygenAlgorithm AlgorithmIdentifier ✘ ✘
Return type: Promise

@robin-raymond robin-raymond pushed a commit that referenced this issue Sep 21, 2015
Robin Raymond Added support for the WebRTC 1.0 certificate management API, as noted…
… in: Issue #195

Added certificate argument to the RTCDtlsTransport constructor, as noted in: Issue #218
Added the "failed" state to RTCDtlsTransportState, as noted in: Issue #219
Changed getNominatedCandidatePair to getSelectedCandidatePair, as noted in: Issue #220
Added support for WebRTC 1.0 RTCIceCredentialType, as noted in: Issue #222
Clarified behavior of createAssociatedGatherer(), as noted in: Issue #223
Changed spelling from "iceservers" to "iceServers" for consistency with WebRTC 1.0, as noted in: Issue #225
Added support for SCTP port numbers, as noted in: Issue #227
Changed "outbound-rtp" to "outboundrtp" within the Statistics API, as noted in: Issue #229
Changed maxPacketLifetime and maxRetransmits from unsigned short to unsigned long, as noted in: Issue #231
Clarified DataChannel negotiation, as noted in: Issue #233
Added getContributingSources() method, as noted in: Issue #236
Fixes to Examples 5 and 6, as noted in: Issue 237 and Issue #239
Fixed cut and paste errors in Example 11, as noted in: Issue #241
aboba commented Sep 28, 2015

Comment from Shijun on making the certificate optional in the DtlsTransport constructor:

aboba commented Sep 29, 2015

To address Shijun's comment, make the certificate optional in the constructor and add a readonly attribute for the certificate, as follows:

[Constructor(RTCIceTransport transport, optional RTCCertificate certificate)]
partial interface RTCDtlsTransport : RTCStatsProvider {
readonly attribute RTCCertificate certificate;


The problem with this, is that you can't provide a synchronous accessor for certificate. If the certificate is not provided in the constructor, you have to make one, and that is an asynchronous process.

1.0 doesn't offer a certificate accessor in the same way: it's only accessible through the createOffer and createAnswer functions, which are asynchronous. (Firefox just blocks on certificate availability before running these functions proper.) You might also note that getConfiguration is synchronous. In that case, we plan to cheat and return null if the certificate isn't ready yet.

aboba commented Sep 29, 2015

The assumption is that if the certificate is not provided in the constructor then by default a certificate would be created using ECDSA and SHA-256.. Based on the measurements you provided, certificate creation appeared likely to be very quick (e.g. <2 ms). Are you saying that even that long a delay requires async treatment?


Maybe not at 2ms, but those numbers didn't account for overheads. But it depends on where you are doing your keygen. If it needs to go to another process, or an HSM, then time accumulates quickly.


I ran a few tests in my current browser, which is running on a 2013 MacBook Pro, which runs a two core 2.8 GHz Intel Core i7. P-256 keygen normally takes 3-4ms, but I've seen 2ms and 5ms.

But that's a pretty fast machine. On a mobile device, even though keygen is fast, this is not going to be that good. On my Samsung Galaxy S4, a fast phone for the time, keygen takes anywhere from 17ms (too long) to around 90ms (way too long) with a median of around 40. Test here yourself with any super-recent gecko-based browser.

I'm not going to suggest that these are perfect. The P-256 implementation in Firefox isn't the best around, but I think that it is within a factor of 2 of ideal performance for the curve (we might get better performance with the new CFRG curves, but they don't exist yet).

aboba commented Oct 6, 2015

Until Martin's points are addressed (such as by changing DtlsTransport.getLocalParameters() to a promise) a certificate cannot be an optional argument to the constructor, and support for the Certificate Management API needs to be mandatory in ORTC.

@aboba aboba closed this Oct 6, 2015
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment