Skip to main content

P6. Processing rules

Work in progress — not audited

Normative protocol documentation for the current implementation. Not independently audited.

P6.1 Terminology​

Keywords MUST, MUST NOT, SHOULD, and MAY are used per RFC 2119.

P6.2 Outbound encrypt path​

Given application PDU data with type and payload fields:

  1. If enableEncryption is false → send data unchanged; STOP.
  2. If remote peer ∉ encryptedConnections → send cleartext or queue handshake; implementation-defined; MUST NOT claim E2EE.
  3. Serialize inner payload to bytes (typically UTF-8 JSON of message fields).
  4. If enableCascadingCipher and cascade ready:
    1. Build CipherKeys per P5.
    2. cascadingCipher.encrypt(plaintextBytes, keys).
    3. Wrap result in encryptedMessage per P5.
    4. If size > 8192 bytes → chunk per P5.5.
  5. Else → MLS-only envelope per P4.
  6. Set data.encryptedMessage = result; preserve data.type.
  7. JSON.stringify → send on data channel via PeerJS.

On any encrypt failure at step 4, implementation MAY fall back to step 5 and SHOULD log.

P6.3 Inbound decrypt path​

On data channel data event:

  1. Parse JSON; if parse fails → MUST drop.
  2. If type === "__mls_chunk__" → buffer; if complete → reconstruct encryptedMessage; goto 4.
  3. If encryptedMessage absent → dispatch cleartext PDU to action router; STOP.
  4. If encryptedMessage.chunked → reassemble chunks → single payload.
  5. If encryptedMessage.cascaded:
    1. Rebuild Uint8Array from finalCiphertext or chunks.
    2. cascadingCipher.decrypt(cascadedPayload, keys) reverse layer order.
    3. On error → MUST NOT deliver plaintext; MUST drop or surface error.
  6. Else MLS-only → mlsManager.decryptMessage(envelope).
  7. Parse decrypted bytes to inner fields (message, etc.).
  8. Dispatch to handler for original type (e.g. message action).

P6.4 Handshake dispatch​

PDUs listed in P3 MUST be processed even when encryptionReady is false. Handlers MUST update local crypto state before replying.

P6.5 Ordering​

  • JSON PDUs have no global sequence number at application layer.
  • Signal ratchet MUST handle out-of-order ciphertext within a session.
  • Chunk PDUs MUST be ordered by chunkIndex before decrypt.

P6.6 Fast file transfer profile​

When fast transfer active:

  • file-chunk / byte-range-* PDUs MAY carry binary without encryptedMessage.
  • Protection is DTLS + optional path security only.
  • UI MUST indicate reduced protection (product requirement).

P6.7 Debug / disabled encryption​

When encryption disabled for development:

  • Senders MUST NOT set encryptedMessage.
  • Receivers MUST accept cleartext message fields.
  • Deployments MUST NOT disable encryption in production.