FF138 Relnote: Certificate returns fingerprints (mdn#39010)

Author: hamishwillee

files/en-us/mozilla/firefox/releases/138/index.md

@@ -56,6 +56,9 @@ Firefox 138 is the current [Beta version of Firefox](https://www.mozilla.org/en-
   ([Firefox bug 1945576](https://bugzil.la/1945576) and [Firefox bug 1945573](https://bugzil.la/1945573)).
 - The [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) now supports bidirectional messaging on an {{domxref("AudioWorklet.port")}} and an {{domxref("AudioWorkletGlobalScope.port")}}.
   This allows for custom, asynchronous communication between code in the main thread and the global scope of an audio worklet, such as receiving control data or global settings. ([Firefox bug 1951240](https://bugzil.la/1951240))
+- The {{domxref("RTCCertificate.getFingerprints()","getFingerprints()")}} method of the {{domxref("RTCCertificate")}} interface is now supported.
+  An application can use this to get fingerprints for a certificate, which might be shared out-of-band in order to identify a particular user or browser across WebRTC sessions.
+  ([Firefox bug 1525241](https://bugzil.la/1525241)).
 
 #### DOM
 

files/en-us/web/api/rtccertificate/getfingerprints/index.md

@@ -10,8 +10,7 @@ browser-compat: api.RTCCertificate.getFingerprints
 
 The **`getFingerprints()`** method of the **{{domxref("RTCCertificate")}}** interface is used to get an array of certificate fingerprints.
 
-An application can use this method to compare the client certificate fingerprints with the certificate fingerprints from the server.
-The server and client may support different sets of algorithms: all fingerprint values for the set of algorithms supported by both client and server should match.
+This can be used in application-level code to get certificate fingerprints, which are {{glossary("hash function","hashes")}} of the certificate created using the various algorithms supported by the browser.
 
 ## Syntax
 
@@ -35,28 +34,56 @@ Each fingerprint is represented by an object with the following properties:
   - : A string containing the certificate fingerprint in lowercase hex string, as calculated with the `algorithm` hash function.
     The format is more precisely defined in [RFC4572, Section 5](https://www.rfc-editor.org/rfc/rfc4572#section-5).
 
+## Description
+
+The {{domxref("RTCCertificate")}} instances used for a particular {{DOMxRef("RTCPeerConnection")}} can created using the {{DOMxRef("RTCPeerConnection.generateCertificate_static", "RTCPeerConnection.generateCertificate()")}} static method or fetched from storage in an [IndexedDB](/en-US/docs/Web/API/IndexedDB_API), and set in the constructor.
+If no certificates are passed in the constructor they will be created automatically, in which case the certificates used can be fetched with {{DOMxRef("RTCPeerConnection.getConfiguration()")}}.
+
+Browsers will automatically exchange certificates and fingerprints associated with each {{DOMxRef("RTCPeerConnection")}} during the SDP offer phase, and these will be used as part of the DTLS handshake to verify that the remote party matches the certificate/endpoint send in the SDP.
+This provides a low level validation that the WebRTC communication is being set up with the remote party that initiated the offer, but does not, for example, provide any validation of the identity of the communicating users.
+
+In some cases it can be useful for the application layer to share certificate fingerprints out-of-band:
+
+- If a trust relationship has been established between two web-browsers it can be persisted by storing the certificates and reusing them in a later session (up to a year later).
+  The trusted certificates are identified by their fingerprints.
+- Peers than want to identify a particular user can send fingerprints and validate the associated user "out of band" (i.e., outside of the browser-mediated WebRTC communications flow).
+  The application can use the fingerprint to identify later sessions with the specific user.
+- In some conferencing server ("middlebox") implementations, the server may need to known the fingerprints before doing any offer/answer.
+
+Peers may support different sets of algorithms.
+When comparing certificates, all fingerprint values for the set of algorithms supported by peers should match.
+
 ## Examples
 
 ### Getting certificate fingerprints
 
-This example shows how you might get certificate fingerprints and compare them to fingerprints from a server.
+This example shows how you might get certificate fingerprints from the local peer and compare them to fingerprints from the remote peer.
 
-First we create a connection and get the fingerprints.
-We also get the fingerprints from the server using "some mechanism".
+First we create a connection and get certificates and their fingerprints.
+We get the fingerprints from the remote peer using "some out of band mechanism".
 
 ```js
+// Get the certificate fingerprints from the local peer.
 const rtcPeerConnection = new RTCPeerConnection();
+const configuration = rtcPeerConnection.getConfiguration();
+const certificates = configuration.certificates;
+let fingerprintsFromClient;
+
+if (certificates && certificates.length > 0) {
+  certificates.forEach((cert) => {
+    // For purpose of demonstration, just get first certificate
+    fingerprintsFromClient = cert.getFingerprints();
+    break;
+  });
+}
 
-// Get the certificate fingerprints from the client.
-const fingerprintsFromClient = rtcPeerConnection.certificate.getFingerprints();
-
-// Get the certificate fingerprints from the server (pseudo code)
+// Get the certificate fingerprints from the remote peer for particular certificate (pseudo code)
 const fingerprintsFromServer = [
   /* … */
 ];
 ```
 
-There are numerous ways to compare the fingerprint arrays.
+There are numerous ways to compare the fingerprint arrays for a particular certificate.
 Here we convert the arrays to dictionary objects where the algorithm name is the property and then compare them.
 This works because only one fingerprint value can exist for each algorithm.
 (There are many other ways to sort and compare the two arrays).