4.9 Certificate Management

The certificates that RTCPeerConnection instances use to authenticate with peers use the RTCCertificate interface. These objects can be explicitly generated by applications using the generateCertificate method and can be provided in the RTCConfiguration when constructing a new RTCPeerConnection instance.

The explicit certificate management functions provided here are optional. If an application does not provide the certificates configuration option when constructing an RTCPeerConnection a new set of certificates MUST be generated by the user agent. That set MUST include an ECDSA certificate with a private key on the P-256 curve and a signature with a SHA-256 hash.

WebIDLpartial interface RTCPeerConnection {
  static Promise<RTCCertificate>
      generateCertificate(AlgorithmIdentifier keygenAlgorithm);
};

Methods

generateCertificate, static

The generateCertificate function causes the user agent to create 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 RTCPeerConnection.

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 following values MUST be supported by a user agent: { name: "[RSASSA-PKCS1-v1_5](https://www.w3.org/TR/WebCryptoAPI/#rsassa-pkcs1)", modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]), hash: "SHA-256" }, and { name: "[ECDSA](https://www.w3.org/TR/WebCryptoAPI/#ecdsa)", namedCurve: "[P-256](https://www.w3.org/TR/WebCryptoAPI/#dfn-NamedCurve)" }.

Note

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

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 RTCPeerConnection, 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-4] 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.

When the method is called, the user agent MUST run the following steps:

1. Let keygenAlgorithm be the first argument to generateCertificate.

2. Let expires be a DOMTimeStamp value of 2592000000.

   Note

   This means the certificate will by default expire in 30 days from the time of the generateCertificate call.

3. If keygenAlgorithm is an object, run the following steps:

   1. Let certificateExpiration be the result of converting the ECMAScript object represented by keygenAlgorithm to an RTCCertificateExpiration dictionary.

   2. If the conversion fails with an error, return a promise that is rejected with error.

   3. If certificateExpiration.expires is not undefined, set expires to certificateExpiration.expires.

   4. If expires is greater than 31536000000, set expires to 31536000000.

      Note

      This means the certificate cannot be valid for longer than 365 days from the time of the generateCertificate call.

      A user agent MAY further cap the value of expires.

4. Let normalizedKeygenAlgorithm be the result of normalizing an algorithm with an operation name of [generateKey](https://www.w3.org/TR/WebCryptoAPI/#SubtleCrypto-method-generateKey) and a supportedAlgorithms value specific to production of certificates for RTCPeerConnection.

5. If the above normalization step fails with an error, return a promise that is rejected with error.

6. If the normalizedKeygenAlgorithm parameter identifies an algorithm that the user agent cannot or will not use to generate a certificate for RTCPeerConnection, return a promise that is rejected with a DOMException of type NotSupportedError. In particular, normalizedKeygenAlgorithm MUST be an asymmetric algorithm that can be used to produce a signature used to authenticate DTLS connections.

7. Let p be a new promise.

8. Run the following steps in parallel:

   1. Perform the generate key operation specified by normalizedKeygenAlgorithm using keygenAlgorithm.

   2. Let generatedKeyingMaterial and generatedKeyCertificate be the private keying material and certificate generated by the above step.

   3. Let certificate be a new RTCCertificate object.

   4. Set certificate.[[Expires]] to the current time plus expires value.

   5. Set certificate.[[Origin]] to the relevant settings object‘s origin.

   6. Store the generatedKeyingMaterial in a secure module, and let handle be a reference identifier to it.

   7. Set certificate.[[KeyingMaterialHandle]] to handle.

   8. Set certificate.[[Certificate]] to generatedCertificate.

   9. Resolve p with certificate.

9. Return p.

4.9.1 RTCCertificateExpiration Dictionary

RTCCertificateExpiration is used to set an expiration date on certificates generated by generateCertificate.

WebIDLdictionary RTCCertificateExpiration {
  [EnforceRange] DOMTimeStamp expires;
};

expires, of type DOMTimeStamp

An optional expires attribute MAY be added to the definition of the algorithm that is passed to generateCertificate. If this parameter is present it indicates the maximum time that the RTCCertificate is valid for relative to the current time.

4.9.2 RTCCertificate Interface

The RTCCertificate interface represents a certificate used to authenticate WebRTC communications. In addition to the visible properties, internal slots contain a handle to the generated private keying materal ([[KeyingMaterialHandle]]), a certificate ([[Certificate]]) that RTCPeerConnection uses to authenticate with a peer, and the origin ([[Origin]]) that created the object.

WebIDL[Exposed=Window, Serializable]
interface RTCCertificate {
  readonly attribute DOMTimeStamp expires;
  sequence<RTCDtlsFingerprint> getFingerprints();
};

Attributes

expires of type DOMTimeStamp, readonly

The expires 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 RTCPeerConnection using this certificate fail.

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

Methods

getFingerprints

Returns the list of certificate fingerprints, one of which is computed with the digest algorithm used in the certificate signature.

For the purposes of this API, the [[Certificate]] slot contains unstructured binary data. No mechanism is provided for applications to access the [[KeyingMaterialHandle]] internal slot or the keying material it references. Implementations MUST support applications storing and retrieving RTCCertificate objects from persistent storage, in a manner that also preserves the keying material referenced by [[KeyingMaterialHandle]]. Implementations SHOULD store the sensitive keying material in a secure module safe from same-process memory attacks. This allows the private key to be stored and used, but not easily read using a memory attack.

RTCCertificate objects are serializable objects [HTML]. Their serialization steps, given value and serialized, are:

1. Set serialized.[[Expires]] to the value of value.expires attribute.
2. Set serialized.[[Certificate]] to a copy of the unstructured binary data in value.[[Certificate]].
3. Set serialized.[[Origin]] to a copy of the unstructured binary data in value.[[Origin]].
4. Set serialized.[[KeyingMaterialHandle]] to a serialization of the handle in value.[[KeyingMaterialHandle]] (not the private keying material itself).

Their deserialization steps, given serialized and value, are:

1. Initialize value.expires attribute to contain serialized.[[Expires]].
2. Set value.[[Certificate]] to a copy of serialized.[[Certificate]].
3. Set value.[[Origin]] to a copy of serialized.[[Origin]].
4. Set value.[[KeyingMaterialHandle]] to the private keying material handle resulting from deserializing serialized.[[KeyingMaterialHandle]].

Note

Supporting structured cloning in this manner allows RTCCertificate instances to be persisted to stores. It also allows instances to be passed to other origins using APIs like postMessage(message, options) [html]. However, the object cannot be used by any other origin than the one that originally created it.