Section 15: Certificate Management API

Assuming that we do indeed want RTCCertificate to stand on its own within ORTC API (instead of having generateCertificate be a method of the RTCDtlsTransport as Peter suggested),  find below a draft of a new section 15 on Certificate Management.
There are still a number of open issues with the Certificate Management API in WebRTC 1.0, let alone with this draft.  As an example, a single keygenAlgorithm appears inadequate; other attributes aside from duration may be needed; it is unclear whether the intent is for RTCCertificate to be used a universal interface to certificates, etc.
However, given the potential impact of the Certificate Management API (assuming we really do want to mandate it in ORTC), it seemed like a good idea to have a discussion about those issues ASAP.
15. Certificate Management
Note
This section of the ORTC API specification depends on the WebRTC 1.0 Certificate Management API, and needs to be synchronized once it is updated.
15.1 Overview

The RTCCertificate interface enables the certificates used by an RTCDtlsTransport<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCDtlsTransport> to be provided in the constructor. This makes it possible to support forking, where the offerer will create multiple RTCDtlsTransport<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#widl-RTCCertificate-expires>;

    readonly    attribute RTCDtlsFingerprint<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCDtlsFingerprint> fingerprint<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#widl-RTCCertificate-fingerprint>;

    static Promise<RTCCertificate<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCCertificate>> generateCertificate<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#widl-RTCCertificate-generateCertificate-Promise-RTCCertificate--AlgorithmIdentifier-keygenAlgorithm> (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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCDtlsFingerprint>, readonly

The fingerprint of the certificate.

15.2.2 Methods
generateCertificate, static

The generateCertificate function causes the user agent<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#dfn-user-agent> to create and store an X.509 certificate [X509V3<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#bib-X509V3>] and corresponding private key. A handle to information is provided in the form of the RTCCertificate<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCCertificate> interface. The returned RTCCertificate<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCCertificate> can be used to control the certificate that is offered in the DTLS sessions established by RTCDtlsTransport<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#bib-WebCryptoAPI>] AlgorithmIdentifier<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#dfn-AlgorithmIdentifier> type. The keygenAlgorithm value MUST be a valid argument to Crypto.subtle.generateKey<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#SubtleCrypto-method-generateKey>; that is, the value MUST produce a non-error result when normalized according to the WebCrypto algorithm normalization process<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#algorithm-normalization> [WebCryptoAPI<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#bib-WebCryptoAPI>] with an operation name of generateKey and a [[supportedAlgorithms<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#dfn-supportedAlgorithms>]] value specific to production of certificates for RTCDtlsTransport<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#bib-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#dfn-user-agent>. Randomized values for distinguished name and serial number SHOULD be used.

A user agent<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#dfn-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<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#dfn-user-agent> cannot or will not use to generate a certificate for RTCDtlsTransport<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCDtlsTransport>.

The following values MUST be supported by a user agent<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#dfn-user-agent>: { name: "RSASSA-PKCS1-v1_5<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#rsassa-pkcs1>", modulusLength: 2048, publicExponent: 65537 }, and { name: "ECDSA<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#ecdsa>", namedCurve: "P-256<https://dvcs.w3.org/hg/webcrypto-api/raw-file/tip/spec/Overview.html#dfn-NamedCurve>" }.
It is expected that a user agent<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#dfn-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<RTCCertificate<http://internaut.com:8080/~baboba/ortc/ortc-7-04-2015.html#idl-def-RTCCertificate>>