Skip to content

discord-php/RFC9420

BranchesTags

Repository files navigation

PHP interfaces implementing RFC 9420 (Messaging Layer Security). This repository provides interface-only definitions for the main MLS abstractions (groups, ratchet tree, messages, proposals, commits, credentials, and crypto primitives) as a starting point for implementations.

Reference: https://www.rfc-editor.org/rfc/rfc9420.html

Status

  • Interface-first: comprehensive RFC-shaped interfaces and registry enums implemented; no concrete cryptographic primitives included.
  • Goal: provide a complete set of PHP interfaces that mirror RFC 9420 concepts for downstream implementations and tests.

Current status

  • Interfaces: comprehensive interface-only definitions for the major RFC 9420 concepts (groups, ratchet tree, messages, proposals, commits, credentials, crypto abstractions).
  • Registry enums: added enum-style classes mirroring RFC tables and registries (Tables 4–7 and related): CipherSuite, KEM, KDF, AEAD, HashAlgorithm, SignatureScheme, ExtensionType, ProposalType, CredentialType, EpochSecrets, SignatureLabels, PublicKeyEncryptionLabels, MessageWireFormat, and ContentType.
  • Tests: a basic PHPUnit test (tests/MLSInterfacesTest.php) asserts presence of interfaces and method signatures; run locally with ./vendor/bin/phpunit.
  • Implementations: no concrete cryptographic implementations included — those remain out of scope.
  • Recent API changes: MLSPlaintextInterface::getSender() and FramedContentInterface::getSender() return a SenderInterface (typed sender union). KeyScheduleInterface::init() now accepts an ordered array of PSKs (array $psks) to reflect RFC PSK chaining semantics. CommitInterface::getSender() and ProposalInterface::getSender() now also return SenderInterface.

DTOs & Adapters (examples/tests)

  • src/MLS/Group/BasicGroup.php — simple in-memory Group adapter that creates proposals, builds commits, and applies them to maintain an internal members list; paired with BasicGroupContext and BasicGroupInfo DTOs.
  • src/MLS/Crypto/BasicKeySchedule.php — illustrative key-schedule adapter that accepts PSKs and derives epoch secrets used by tests (not cryptographically secure).
  • src/MLS/Crypto/BasicHPKE.php — minimal envelope helper providing seal() and open() helpers used by tests to simulate HPKE behavior.
  • src/MLS/Credentials/BasicCredential.php — credential DTO storing type, identity, and publicKey, implements __toString() and a simple verifySignature() stub for tests.
  • src/MLS/Handshake/BasicKeyPackage.php — lightweight KeyPackage DTO containing an init key material, cipher suite, and credential reference for examples.
  • src/MLS/Handshake/KeyPackageBundle.php — convenience wrapper around KeyPackage objects with simple serialization/verification helpers used in tests.
  • src/MLS/Proposal/BasicProposal.php — proposal DTO capturing a type, sender, and payload; used with ProposalList.php which provides collection and basic validation helpers.
  • src/MLS/Commit/BasicCommit.php — commit DTO that packages proposals (and optionally an update path) produced by BasicGroup::commit().
  • src/MLS/Tree/LeafNode.php, src/MLS/Commit/UpdatePath.php, src/MLS/Commit/UpdatePathNode.php — small DTOs representing leaf nodes and update-path structures used by commit/update tests.

These adapters are intentionally minimal and intended for tests and examples only — they are not production-grade cryptographic implementations. Implemented (interface files) — ordered by RFC section

Enums / identifiers

All RFC sections listed in the original TODO have corresponding interface files and identifiers in this repository. See the Implemented list above for file-level cross-references to RFC sections.

Quick start

Install dependencies:

composer install

Run formatting (Pint):

composer run-script pint

Run tests:

composer run-script unit
# or directly:
./vendor/bin/phpunit tests/

On Windows use the shipped .bat wrappers in vendor/bin (for example vendor/bin/phpunit.bat).

Notes

  • The project is interface-first; concrete implementations are intentionally out of scope for now.
  • Tests assert presence of core interfaces and method signatures (see tests/MLSInterfacesTest.php).
  • Registry enums were added to reflect RFC 9420 numeric/label registries; see src/MLS/Enums/ for details.
  • Running the test suite may surface configuration or deprecation warnings depending on your environment (PHPUnit version, PHP version). Addressing deprecations and expanding test coverage are planned.

RFC coverage

  • Core group lifecycle (Group, Commit, Proposal): partial — interfaces exist for proposals and commits.
  • Ratchet tree (Tree, LeafNode, ParentNode): covered by tree interfaces; concrete hashing/ratchet logic not implemented.
  • Handshake: KeyPackage and Welcome interfaces added; key package bundles and encrypted secrets not implemented.
  • Crypto: Cipher suite, KeySchedule, HPKE, and signature scheme abstractions provided; implementations required.
  • Extensions & Transcript: extension and transcript interfaces included for payloads and hash tracking.
  • RFC registries mirrored: wire formats, proposal types, extension types, credential types, signature labels, and public-key encryption labels are represented under src/MLS/Enums/.

Registry details

  • Epoch-derived secrets (Table 4): common labels used by the key schedule are mirrored in src/MLS/Enums/EpochSecrets.php. Labels include "sender data", "encryption", "exporter", "external", "confirm", "membership", "resumption", and "authentication". Each label maps to a derived secret name (for example, "confirm" → confirmation_key) and a short-purpose description.

  • Cipher suites (Tables 6 & 7): the CipherSuite registry is represented in src/MLS/Enums/CipherSuite.php. It includes the initial MLS 1.0 suites (e.g. MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519) and GREASE/private-use ranges. The mandatory-to-implement suite for MLS 1.0 is MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519. Each suite exposes component mappings (KEM/KDF/AEAD/Hash/Signature) via helper accessors in the enum class.

Roadmap

  1. Address PHPUnit deprecation(s) and stabilize CI runs.
  2. Expand tests to validate enum mappings, serialization formats, and contract behavior.
  3. Add minimal reference implementations or adapters for HPKE/signature primitives.
  4. Implement end-to-end examples that exercise the KeySchedule, Commit, and Welcome flows.

If you'd like, I can add a short example showing how to construct a SenderInterface instance value (as a simple DTO) for use with these interfaces — or scaffold minimal reference implementations for KeySchedule and HPKE to exercise PSK chaining and welcome creation.

Contributing

  • Add concrete implementations under src/MLS/ and tests under tests/.
  • Follow code style in pint.json and run composer run-script pint before submitting PRs.

License

See LICENSE.md in the repository root.

About

RFC 9420 MLS PHP implementation

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors 1

Languages