polyproto-mls Extension Specification

Namespace: mls

Version: v1.0-alpha.2

Base Path: /.p2/mls/v1/

Semantic versioning v2.0.0 is used to version this specification.

The polyproto-mls extension defines how Messaging Layer Security (herein after referred to as its commonly used acronym, MLS) integrates with polyproto. The basis of this document is IETF RFC 9420.

1. Cryptographic Suites

This section lists predefined cryptographic suites that can be implemented by polyproto-mls compatible implementations.

Name	Numeric Identifier (MLS Numeric Value)	Quantum-Secure?	Recommended?	Required?
MLS default	0x0001	No	Yes	Yes
Hybrid PQS	0xF110	Yes	Yes	Yes

1.1. MLS default cipher suite

In coherence with section #6.5 of the core polyproto specification document and section #17.1 of RFC 9420, the cipher suite MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519 must be implemented by polyproto-mls implementations. This cipher suite uses Curve25519 for key exchange, AES-128-GCM for HPKE, HKDF over SHA2-256, and Ed25519 for signatures.

MLS Cipher Suite Component	Component	Quantum-Secure?
Key Exchange	Curve25519	No
HPKE	AES-128-GCM	Partially
HKDF	SHA2-256	Partially
Signatures	Ed25519	No

1.2. Hybrid PQC cipher suite

polyproto-mls v1 offers a Post-Quantum cryptography (PQC) cipher suite in order to resist possible cryptanalytic attacks by a quantum computer on encrypted messages shared via polyproto-mls.

info

The MLS working group is considering adoption of the draft document ML-KEM and Hybrid Cipher Suites for MLS. Until official recommendations are made regarding eligible, well-suited cipher suites for hybrid, Post-Quantum/Traditional authenticity and confidentiality guarantees, polyproto-mls may either employ a temporary, own cipher suite, or leave this particular section unfinished.

2. Home Server Responsibilities

Services aiming to be compliant with polyproto-mls v1 must take on the roles of Authentication Service (AS) and Delivery Service (DS) in the context of Messaging Layer Security.

Quote from the MLS Architecture Document:

An Authentication Service (AS), which is responsible for attesting to bindings between application-meaningful identifiers and the public key material used for authentication in the MLS protocol. The AS must also be able to generate credentials that encode these bindings and validate credentials provided by MLS clients.
A Delivery Service (DS), which can receive and distribute messages between group members. In the case of group messaging, the DS may also be responsible for acting as a "broadcaster" where the sender sends a single message which is then forwarded to each recipient in the group by the DS. The DS is also responsible for storing and delivering initial public key material required by MLS clients in order to proceed with the group secret key establishment that is part of the MLS protocol.

Source

3. HTTP APIs

polyproto-mls provides a set of versioned HTTP APIs accessible via the mls namespace. The HTTP APIs provide functionality required by the MLS specification for polyproto-mls implementers to also be compliant MLS implementations.

The HTTP APIs offered through polyproto-mls are fully documented as OpenAPI specification documents for OpenAPI versions 3.0.0 and 3.1.0. The OpenAPI specification documents can be found at this link. Select the preferred OpenAPI version and find the versioned .yaml files in the corresponding folder.

4. WebSocket Gateway

The polyproto-mls extension specification also registers a namespace mls for the WebSocket protocol defined in section #3 of the polyproto-core specification. As usual for WebSockets, this provides optional, real-time bidirectional communication functionality for implementations that require it.

Servers must offer the mls namespace for the WebSocket Gateway and the functionality described by this chapter. Clients may subscribe to the mls WebSocket Gateway Service Channel by sending a subscribe event with the appropriate contents to the polyproto-mls WebSocket Gateway server.

Example MLS subscribe payload

{
    "n": "core",
    "op": 8,
    "d": {
        "action": "subscribe",
        "service": "mls"
    }
}

4.1. Gateway Event Opcodes

The following opcodes are defined by the mls namespace:

Opcode	Name	Action	Description
TBD	TBD	TBD	TBD