From de1200cafd3463256720a9d95ecd90fd05b94e4c Mon Sep 17 00:00:00 2001 From: Cindy Lin <9029396+cindylindeed@users.noreply.github.com> Date: Mon, 31 Aug 2026 16:00:02 -0700 Subject: [PATCH] Edit Mozilla MLS Explainer. --- MessagingLayerSecurity.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/MessagingLayerSecurity.md b/MessagingLayerSecurity.md index 849fa2e..8e5b310 100644 --- a/MessagingLayerSecurity.md +++ b/MessagingLayerSecurity.md @@ -2,43 +2,43 @@ Author: [Anna Weine](https://github.com/Frosne) -Last updated: May 28, 2026 +Last updated: Aug 31, 2026 -People increasingly use web applications for group communication, collaboration, and shared work. These groups often exchange sensitive information, such as messages, documents, files, comments, tasks, or project state. Users need this information to remain confidential and authentic even as group membership changes over time. When a group adds a new participant or removes an existing participant, future communication should be protected according to the updated membership. +People increasingly use web applications for group communication, collaboration, and shared work. These groups often exchange sensitive information, such as messages, documents, files, comments, tasks, or project state. Users need this information to remain confidential and authenticated even as group membership changes over time. When a group adds a new participant or removes an existing participant, future communication should be protected according to the updated membership. **Building end-to-end protected group communication is difficult.** Applications need to manage cryptographic identities, group membership changes, message protection, state updates, and asynchronous delivery. There are many subtle ways for this design to fail: a missed update, an incorrectly authenticated membership change, unsafe key reuse, or inconsistent group state can silently undermine the protections users believe they have. Some applications will make these mistakes; others may avoid offering strong group protection entirely because the engineering cost and security risk are too high. In both cases, users lose. -These risks do not disappear just because an application uses an existing MLS library. The application still needs to integrate that library correctly with its identity model, storage, delivery system, application state, and user interface. That means some security-sensitive parts of group communication are still left to each web application to assemble and maintain.  A browser-provided API can reduce this burden by making secure group communication available as a common web platform capability, rather than requiring every application to build the same security-sensitive machinery around MLS independently.  +These risks do not disappear just because an application uses an existing MLS library. The application still needs to integrate that library correctly with its identity model, storage, delivery system, application state, and user interface. That means security-sensitive parts of group communication are still left to each web application to assemble and maintain. A browser-provided API can reduce this burden by making secure group communication available as a common web platform capability, rather than requiring every application to build the same MLS API independently.  -This explainer proposes a “batteries included” continuous group key agreement API based on a subset of the Messaging Layer Security protocol. The proposed API focuses on providing the basic tools necessary to secure group communication in web applications, while keeping group secrets in browser-managed state and minimizing the amount of cryptographic state management that each application needs to implement itself. +This explainer proposes a “batteries included” continuous group key agreement API based on a subset of the Messaging Layer Security protocol. The proposed API focuses on providing the basic tools necessary to secure group communication in web applications, while keeping group secrets in browser-managed state, requiring web applications to handle identity management, and minimizing the amount of cryptographic operations that each application needs to implement itself. ## **Alternatives** -There is currently no Web platform API for group secret establishment and end-to-end group communication. Existing security mechanisms generally address two-party or client-server communication, not shared cryptographic group state for dynamic groups. As a result, web applications that want this property usually need to build and integrate it themselves. +There is currently no Web platform API for group secret establishment and end-to-end group communication. Existing security mechanisms address two-party or client-server communication, not shared cryptographic group state for dynamic groups. As a result, web applications that want this property need to build this themselves. -The Web platform does provide pieces that can be used to assemble such a system. Applications can use Web Cryptography APIs for lower-level cryptographic operations, JavaScript or WebAssembly for protocol logic, persistence mechanisms such as IndexedDB for local state, and transport APIs to exchange protocol messages between clients. +The Web platform does provide pieces that can be used to assemble such a system. Applications can use Web Cryptography APIs for low-level cryptographic operations, JavaScript or WebAssembly for protocol logic, persistence mechanisms such as IndexedDB for local state, and transport APIs to exchange protocol messages between clients. -Applications can also bring an MLS implementation into the web application directly. For example, a Rust implementation such as OpenMLS can be compiled to WebAssembly and used from JavaScript. This makes it possible to run MLS-related logic in a web application today, but only as part of an application-managed design rather than as a common Web platform capability. +Applications can also bring an MLS implementation into the web application directly. For example, a Rust implementation like OpenMLS can be compiled to WebAssembly and used from JavaScript. This makes it possible to run MLS-related logic in a web application today, but as part of an application-managed design rather than as a common Web platform capability. ## **Outline of a proposed solution** The `MLS` interface is the client-level entry point for the API. It lets an application create a browser-managed client identity for participating in MLS groups, and exposes group lifecycle operations such as creating a new group or joining an existing group. -`MLSGroupView` represents an MLS group. Applications can use this to decrypt protected messages received from other group members, produce protected application messages to send to the group, and manage group state. +`MLSGroupView` represents an MLS group. Applications use this to decrypt protected messages received from other group members, produce protected application messages to send to the group, and manage group state. ## **Proposed API Usage** -The following examples illustrate how an application could use the proposed API. Method names and return types may change as the API design is refined. +The following examples illustrate how an application uses the proposed API. Method names and return types may change as the API design is refined. In the following examples, calls on `myApp` represent application-defined operations, such as network delivery or server communication. These are not part of the proposed API. ### Preparing a client -A client first creates a local MLS identity, which includes the credential and key package needed to participate in groups. The application can then store or publish this identity through its own service so that another client can add this client to a group. +A client first creates a local MLS identity, which includes the credential and public key package used to participate in groups. The application stores or publishes this identity through its own service so other clients can add this client to a group. ```js const identity = await mls.createIdentity("alice@example"); @@ -85,14 +85,14 @@ if (commitOutput.welcome) { ## **Joining a group** -A newly added client joins a group by processing a `welcome` message delivered by the application. +A newly added client (“bob”) joins a group by processing a `welcome` message (generated and sent by “alice”) and delivered by the application. ```js const welcome = await myApp.receiveWelcomeFromApplicationServer(); const joinedGroup = await mls.joinGroup(identity, welcome); ``` -The `groupJoin()` operation produces an  `MLSGroupView` that represents the new client’s local view of the group. The new member (“bob”) has the same view of the group state as the creator of the group (“alice”). +The `joinGroup()` operation produces an  `MLSGroupView` that represents the client’s local view of the group. The new member (“bob”) has the same view of the group state as the creator of the group (“alice”). The API also supports removing members from groups, using a similar pattern. @@ -151,7 +151,7 @@ The following example illustrates secret export, one of the more commonly needed ### Exporting an application secret -Some applications need group-derived secret material for application-specific cryptographic operations. For example, a file sharing application might use an exported secret to encrypt a file. Bytes exported from the group are converted to a WebCrypto API AES-256-GCM key. +Some applications need group-derived secret material for cryptographic operations external to MLS. For example, a file sharing application might use an exported secret to encrypt a file. Bytes exported from the group are converted to a WebCrypto API AES-256-GCM key. ```js const context = new TextEncoder().encode("shared-folder-123"); @@ -167,9 +167,9 @@ const fileKey = await crypto.subtle.importKey( ## **Caveats, shortcomings, and other drawbacks of design choices, both current and any prior iterations** -MLS can protect message contents and authenticate group state, but delivery services and network observers may still learn information such as message timing, message size, group activity, and delivery patterns depending on the application’s transport design. +MLS can protect message contents and authenticate group state, but delivery services and network observers can learn information such as message timing, message size, group activity, and delivery patterns depending on the application’s transport design. -Applications are responsible for binding credentials to user accounts and verifying who they're communicating with. Users may not have visibility into whether this binding is done correctly. +Applications are responsible for binding credentials to user accounts and their key packages. Users do not have visibility into whether this binding is done correctly unless an additional mechanism is offered, for example, key transparency. ## **draft specification**