Re: Issue 195: Certificate Management API

WebRTC 1.0 added an (optional) Certificate Management API in Section 5.5 in the last Editor’s draft.   This appears needed in ORTC API in order to solve the DtlsTransport forking problem.

So below find the proposed text to be inserted in Section 15.   Some oddities found in the API:


a.       keygenAlgorithm only specifies the algorithm used to generate the key – it does not specify the hash algorithm.  So if in future we needed to transition from SHA-256 to some other hash algorithm, it isn’t clear how that would happen.

b.      In practice, implementations are likely to use the certificate generation functionality in the underlying DTLS implementation (e.g. BoringSSL, OpenSSL, S-Channel, etc.).  So why the references to WebCrypto?


15. Certificate Management
NOTE
This section of the ORTC API specification is based 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<http://internaut.com:8080/~baboba/ortc/ortc-9-21-2015.html#widl-RTCCertificate-expires>;

    readonly    attribute RTCDtlsFingerprint fingerprint;

    static Promise<RTCCertificate> 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<http://internaut.com:8080/~baboba/ortc/ortc-9-21-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-9-21-2015.html#idl-def-RTCDtlsFingerprint>, readonly

The fingerprint of the certificate.

15.2.2 Methods
generateCertificate, static

The generateCertificate method causes the user agent<http://internaut.com:8080/~baboba/ortc/ortc-9-21-2015.html#dfn-user-agent> to create and store an X.509 certificate [X509V3<http://internaut.com:8080/~baboba/ortc/ortc-9-21-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-9-21-2015.html#idl-def-RTCCertificate> interface. The returned RTCCertificate<http://internaut.com:8080/~baboba/ortc/ortc-9-21-2015.html#idl-def-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. ThekeygenAlgorithm 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<http://internaut.com:8080/~baboba/ortc/ortc-9-21-2015.html#bib-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 byRTCDtlsTransport, 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-9-21-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-9-21-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-9-21-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-9-21-2015.html#dfn-user-agent> cannot or will not use to generate a certificate for RTCDtlsTransport.

The following values must be supported by a user agent<http://internaut.com:8080/~baboba/ortc/ortc-9-21-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-9-21-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>