You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 25, 2026. It is now read-only.
Repository navigation
This repository was archived by the owner on Feb 25, 2026. It is now read-only.
Certificate management API in 1.0 pull request #195
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.
Potential text of a new Section 15 below, which assumes a new RTCCertificate object (instead of just adding a generateCertificate method to DtlsTransport ).
Certificate Management
NOTE
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.
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.
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.
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).
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.
Activity
aboba commentedon 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 commentedon 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 ).
NOTE
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
Added support for the WebRTC 1.0 certificate management API, as noted…
aboba commentedon Sep 28, 2015
Comment from Shijun on making the certificate optional in the DtlsTransport constructor:
https://lists.w3.org/Archives/Public/public-ortc/2015Sep/0029.html
aboba commentedon 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;
};
martinthomson commentedon Sep 29, 2015
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
createOfferandcreateAnswerfunctions, which are asynchronous. (Firefox just blocks on certificate availability before running these functions proper.) You might also note thatgetConfigurationis synchronous. In that case, we plan to cheat and return null if the certificate isn't ready yet.aboba commentedon 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?
martinthomson commentedon Sep 29, 2015
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.
martinthomson commentedon Sep 29, 2015
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 commentedon 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.