@open-e2ee/signal-protocol-sdk 0.1.0-alpha.3 → 0.1.0-alpha.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +82 -2
- package/NOTICE +3 -1
- package/README.md +10 -5
- package/dist/blocking/types.d.ts +1 -1
- package/dist/blocking/types.js +1 -1
- package/dist/client/client.d.ts +3 -3
- package/dist/client/client.js +4 -4
- package/dist/client/client.js.map +1 -1
- package/dist/client/compose.d.ts +1 -1
- package/dist/client/compose.d.ts.map +1 -1
- package/dist/client/config.d.ts +2 -2
- package/dist/client/event-hooks.d.ts +1 -1
- package/dist/client/headless.d.ts +2 -2
- package/dist/client/headless.js +2 -2
- package/dist/client/key-rotation-core.d.ts +4 -4
- package/dist/client/key-rotation-core.js +11 -11
- package/dist/client/key-rotation-core.js.map +1 -1
- package/dist/client/media.d.ts +2 -2
- package/dist/client/media.js +5 -5
- package/dist/client/media.js.map +1 -1
- package/dist/client/messages.js +2 -2
- package/dist/client/messages.js.map +1 -1
- package/dist/client/relay-subscription.js +17 -0
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/retry.js +1 -1
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender-ops.js +1 -1
- package/dist/client/sealed-sender-ops.js.map +1 -1
- package/dist/client/sessions.d.ts.map +1 -1
- package/dist/client/sessions.js +3 -0
- package/dist/client/sessions.js.map +1 -1
- package/dist/client/signal-service-cipher.d.ts +5 -1
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +19 -14
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/device/provisioning.d.ts +3 -3
- package/dist/device/provisioning.js +2 -2
- package/dist/device/provisioning.js.map +1 -1
- package/dist/hooks/use-connection-presence.d.ts +2 -2
- package/dist/hooks/use-connection-presence.d.ts.map +1 -1
- package/dist/hooks/use-connection-presence.js +1 -1
- package/dist/hooks/use-group-membership.d.ts +2 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/internal/crypto/index.js +1 -1
- package/dist/internal/crypto/index.js.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.d.ts +1 -1
- package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.js +2 -2
- package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
- package/dist/internal/crypto/key-prefix.d.ts +1 -1
- package/dist/internal/crypto/key-prefix.js +1 -1
- package/dist/internal/crypto/pq/kyber.d.ts +1 -1
- package/dist/internal/crypto/pq/kyber.js +1 -1
- package/dist/internal/crypto/symmetric/aes-gcm-siv.d.ts +1 -1
- package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
- package/dist/internal/crypto/utils.d.ts +2 -2
- package/dist/internal/crypto/utils.js +2 -2
- package/dist/internal/encoding/proto/index.js +1 -1
- package/dist/internal/encoding/proto/index.js.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +2 -2
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js +2 -2
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
- package/dist/internal/groups/group-id.d.ts +1 -1
- package/dist/internal/groups/group-id.js +1 -1
- package/dist/internal/groups/group-id.js.map +1 -1
- package/dist/internal/groups-v2/access-control.d.ts +8 -1
- package/dist/internal/groups-v2/access-control.d.ts.map +1 -1
- package/dist/internal/groups-v2/access-control.js +8 -1
- package/dist/internal/groups-v2/access-control.js.map +1 -1
- package/dist/internal/groups-v2/change-actions.d.ts +8 -3
- package/dist/internal/groups-v2/change-actions.d.ts.map +1 -1
- package/dist/internal/groups-v2/change-actions.js +8 -3
- package/dist/internal/groups-v2/change-actions.js.map +1 -1
- package/dist/internal/groups-v2/index.d.ts +7 -2
- package/dist/internal/groups-v2/index.d.ts.map +1 -1
- package/dist/internal/groups-v2/index.js.map +1 -1
- package/dist/internal/groups-v2/manager.d.ts +4 -2
- package/dist/internal/groups-v2/manager.d.ts.map +1 -1
- package/dist/internal/groups-v2/manager.js +5 -3
- package/dist/internal/groups-v2/manager.js.map +1 -1
- package/dist/internal/groups-v2/types.d.ts +10 -3
- package/dist/internal/groups-v2/types.d.ts.map +1 -1
- package/dist/internal/groups-v2/types.js.map +1 -1
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +25 -14
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.d.ts +1 -1
- package/dist/internal/protocol/double-ratchet/chains.js +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts +1 -1
- package/dist/internal/protocol/double-ratchet/ratchet.js +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.js +2 -2
- package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +1 -1
- package/dist/internal/protocol/sender-keys/index.d.ts +1 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts +2 -2
- package/dist/internal/protocol/sender-keys/manager.js +3 -3
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/index.d.ts +1 -1
- package/dist/internal/protocol/spqr/index.js +1 -1
- package/dist/internal/protocol/spqr/message.d.ts +1 -1
- package/dist/internal/protocol/spqr/message.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/index.js +2 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/index.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/lagrange.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +5 -5
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.d.ts +9 -9
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +9 -9
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.js +1 -1
- package/dist/internal/protocol/username/generate.d.ts +1 -1
- package/dist/internal/protocol/username/generate.js +1 -1
- package/dist/internal/protocol/username/hash.d.ts +1 -1
- package/dist/internal/protocol/username/hash.js +1 -1
- package/dist/internal/protocol/username/link.d.ts +1 -1
- package/dist/internal/protocol/username/link.js +1 -1
- package/dist/internal/protocol/username/proof.d.ts +1 -1
- package/dist/internal/protocol/username/proof.js +1 -1
- package/dist/internal/protocol/x3dh/x3dh.js +3 -3
- package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts +5 -4
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +2 -2
- package/dist/internal/sesame/device-registry.d.ts +11 -6
- package/dist/internal/sesame/device-registry.d.ts.map +1 -1
- package/dist/internal/sesame/device-registry.js +11 -7
- package/dist/internal/sesame/device-registry.js.map +1 -1
- package/dist/internal/sesame/manager.js +1 -1
- package/dist/internal/sesame/manager.js.map +1 -1
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +8 -0
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/internal/session/keys.d.ts +1 -1
- package/dist/keys/generation.d.ts +4 -3
- package/dist/keys/generation.d.ts.map +1 -1
- package/dist/keys/generation.js +2 -2
- package/dist/keys/generation.js.map +1 -1
- package/dist/keys/types.d.ts +1 -1
- package/dist/keys/types.d.ts.map +1 -1
- package/dist/local/store/expo/adapter.d.ts +3 -3
- package/dist/local/store/expo/adapter.js +2 -2
- package/dist/local/store/expo/db.js +1 -1
- package/dist/local/store/expo/db.js.map +1 -1
- package/dist/local/store/expo/index.d.ts +1 -1
- package/dist/local/store/expo/models/local-identity.d.ts +1 -1
- package/dist/local/store/expo/models/local-identity.js +1 -1
- package/dist/local/store/expo/models/sender-key.d.ts +3 -3
- package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
- package/dist/local/store/expo/models/sender-key.js +3 -3
- package/dist/local/store/expo/models/sender-key.js.map +1 -1
- package/dist/local/store/expo/schema.d.ts +1 -1
- package/dist/local/store/expo/schema.js +1 -1
- package/dist/local/store/expo/secure-store-options.d.ts +1 -1
- package/dist/local/store/mock/adapter.d.ts +6 -0
- package/dist/local/store/mock/adapter.d.ts.map +1 -1
- package/dist/local/store/mock/adapter.js +117 -47
- package/dist/local/store/mock/adapter.js.map +1 -1
- package/dist/local/store/mock/failures.d.ts +34 -0
- package/dist/local/store/mock/failures.d.ts.map +1 -0
- package/dist/local/store/mock/failures.js +75 -0
- package/dist/local/store/mock/failures.js.map +1 -0
- package/dist/local/store/mock/index.d.ts +4 -3
- package/dist/local/store/mock/index.d.ts.map +1 -1
- package/dist/local/store/mock/index.js +3 -2
- package/dist/local/store/mock/index.js.map +1 -1
- package/dist/local/store/node/database-key.js +1 -1
- package/dist/local/store/react-native/adapter.js +2 -2
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/react-native/storage.d.ts +1 -1
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +14 -2
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/vault/index.d.ts +1 -1
- package/dist/logger.d.ts +1 -1
- package/dist/logger.js +1 -1
- package/dist/media/index.d.ts +2 -2
- package/dist/media/index.js +2 -2
- package/dist/profile/cipher.d.ts +1 -1
- package/dist/profile/cipher.js +1 -1
- package/dist/profile/contact-state.d.ts +1 -1
- package/dist/profile/contact-state.js +1 -1
- package/dist/profile/crypto.d.ts +1 -1
- package/dist/profile/crypto.js +1 -1
- package/dist/profile/profile-key.js +1 -1
- package/dist/profile/update-service.d.ts +2 -2
- package/dist/profile/update-service.d.ts.map +1 -1
- package/dist/remote/object-store/convex-r2/server.d.ts +1 -1
- package/dist/remote/relay/convex/index.d.ts +1 -1
- package/dist/remote/relay/convex/index.js +1 -1
- package/dist/remote/relay/convex/relay.d.ts +2 -2
- package/dist/remote/relay/convex/relay.js +2 -2
- package/dist/remote/relay/convex/types.d.ts +7 -7
- package/dist/remote/relay/convex/types.js +1 -1
- package/dist/remote/relay/mock/adapter.d.ts +13 -2
- package/dist/remote/relay/mock/adapter.d.ts.map +1 -1
- package/dist/remote/relay/mock/adapter.js +165 -51
- package/dist/remote/relay/mock/adapter.js.map +1 -1
- package/dist/remote/relay/mock/failures.d.ts +57 -0
- package/dist/remote/relay/mock/failures.d.ts.map +1 -0
- package/dist/remote/relay/mock/failures.js +118 -0
- package/dist/remote/relay/mock/failures.js.map +1 -0
- package/dist/remote/relay/mock/index.d.ts +4 -3
- package/dist/remote/relay/mock/index.d.ts.map +1 -1
- package/dist/remote/relay/mock/index.js +4 -3
- package/dist/remote/relay/mock/index.js.map +1 -1
- package/dist/remote/relay/types.d.ts +1 -1
- package/dist/remote/relay/types.js +1 -1
- package/dist/safety/protobuf.d.ts +1 -1
- package/dist/safety/protobuf.d.ts.map +1 -1
- package/dist/types/api.d.ts +6 -6
- package/dist/types/errors.d.ts +2 -2
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +2 -2
- package/dist/types/errors.js.map +1 -1
- package/dist/types/protocol-config.d.ts +3 -2
- package/dist/types/protocol-config.d.ts.map +1 -1
- package/dist/types/protocol-config.js.map +1 -1
- package/dist/types/protocol-constants.d.ts +1 -1
- package/dist/types/protocol-constants.js +1 -1
- package/dist/utils/binary-transfer.d.ts +1 -1
- package/dist/utils/errors.d.ts +2 -2
- package/dist/utils/errors.js +2 -2
- package/dist/utils/retry.d.ts +2 -1
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +3 -1
- package/dist/utils/retry.js.map +1 -1
- package/dist/zk/groups.d.ts +1 -1
- package/dist/zk/groups.js +1 -1
- package/docs/CLIENT_COMPOSITION.md +5 -3
- package/docs/DEVIATIONS.md +892 -0
- package/docs/GETTING_STARTED.md +10 -6
- package/docs/PACKAGE_SURFACE.md +2 -2
- package/docs/PROTOCOL_POLICY.md +11 -2
- package/docs/RECIPES.md +4 -0
- package/docs/api/classes/SignalProtocolClient.md +4 -4
- package/docs/api/functions/createDefaultSignalLogger.md +2 -2
- package/docs/api/functions/resolveSignalLogger.md +2 -2
- package/docs/api/interfaces/BlockedRecipientEntry.md +1 -1
- package/docs/api/interfaces/ILogger.md +1 -1
- package/docs/api/interfaces/ISignalLocalSecretVault.md +2 -2
- package/docs/api/interfaces/ISignalLocalStore.md +2 -2
- package/docs/api/interfaces/ISignalProtocolClient.md +2 -2
- package/docs/api/interfaces/MLKEMBraidAgentState.md +1 -1
- package/docs/api/interfaces/PreKeyMaintenanceStore.md +2 -1
- package/docs/api/interfaces/SealedSenderConfig.md +2 -2
- package/docs/api/interfaces/SignalProtocolClientCompositionOptions.md +2 -2
- package/docs/api/interfaces/SignalProtocolClientConfig.md +2 -2
- package/docs/api/interfaces/SignalProtocolClientHooks.md +1 -1
- package/docs/api/interfaces/SignalProtocolClientIdentityConfig.md +1 -1
- package/docs/api/interfaces/SignalProtocolClientMediaConfig.md +3 -3
- package/docs/api/interfaces/SignalProtocolConfig.md +1 -1
- package/docs/api/namespaces/encoding/functions/bytesToUrlSafeBase64.md +2 -2
- package/docs/api/namespaces/keys/functions/generateKemOneTimePreKeys.md +1 -1
- package/docs/api/namespaces/media/functions/prepareMediaAttachmentUpload.md +1 -1
- package/docs/api/namespaces/media/functions/resolveMediaAttachment.md +1 -1
- package/docs/api/namespaces/media/variables/downloadMediaAttachment.md +1 -1
- package/docs/api/type-aliases/GroupId.md +1 -1
- package/docs/api/variables/MAX_RECEIVER_CHAINS.md +1 -1
- package/docs/api/variables/ONE_TIME_PREKEY_BATCH_SIZE.md +1 -1
- package/docs/api/variables/defaultSignalLogger.md +2 -2
- package/local/store/mock/README.md +31 -0
- package/package.json +2 -1
- package/remote/relay/mock/README.md +37 -0
|
@@ -0,0 +1,892 @@
|
|
|
1
|
+
# Deviations from the Signal Protocol Specifications
|
|
2
|
+
|
|
3
|
+
> Navigation: [README](../README.md) | [ARCHITECTURE](../ARCHITECTURE.md) |
|
|
4
|
+
> [Security](./SECURITY.md) | [Protocol Policy](./PROTOCOL_POLICY.md) |
|
|
5
|
+
> **Deviations**
|
|
6
|
+
|
|
7
|
+
## What compatibility means here
|
|
8
|
+
|
|
9
|
+
This SDK implements the same cryptographic core as the published Signal Protocol
|
|
10
|
+
specifications — X3DH/PQXDH key agreement, the Double Ratchet, the ML-KEM Braid
|
|
11
|
+
post-quantum ratchet, Sesame multi-device session management, sealed sender, and
|
|
12
|
+
the Signal Protocol's zero-knowledge group credential system. In many places it is faithful
|
|
13
|
+
down to the byte: the same KDF labels, the same chain-key constants, the same
|
|
14
|
+
protobuf field numbers, the same iteration counts.
|
|
15
|
+
|
|
16
|
+
It is **not wire-compatible with Signal Messenger or with `libsignal`**, and it
|
|
17
|
+
is not intended to be. Messages produced by this SDK cannot be decrypted by a
|
|
18
|
+
Signal Messenger client, identities cannot be exchanged, safety numbers computed here
|
|
19
|
+
cannot be compared against safety numbers shown in Signal Messenger, and sessions cannot be
|
|
20
|
+
migrated in either direction. This is a distinct wire profile —
|
|
21
|
+
`IndependentProfileV1` — that shares the Signal Protocol's cryptographic design and
|
|
22
|
+
deliberately does not share its encoding.
|
|
23
|
+
|
|
24
|
+
That distinction matters in a specific way. Reading "implements X3DH and the
|
|
25
|
+
Double Ratchet" reasonably leads someone to expect interoperability. There is
|
|
26
|
+
none. Reading "safety numbers compatible with Signal Messenger" would reasonably
|
|
27
|
+
lead someone to expect that a user could verify a contact by comparing a number
|
|
28
|
+
shown in this SDK against the same contact's number in Signal Messenger. They
|
|
29
|
+
cannot; the numbers are computed over different inputs and will never match.
|
|
30
|
+
|
|
31
|
+
This document is the complete, honest account of where and why the profile
|
|
32
|
+
differs. Each entry names the implementing file, the specification section or
|
|
33
|
+
`libsignal` source it departs from, the engineering reason, and the cost. Where a
|
|
34
|
+
deviation weakens an assurance that a reader of the specification would
|
|
35
|
+
reasonably assume, that is stated plainly rather than framed as a feature.
|
|
36
|
+
|
|
37
|
+
Deviations fall into three kinds:
|
|
38
|
+
|
|
39
|
+
- **Deviation** — does something different from the specification or from
|
|
40
|
+
`libsignal`, deliberately.
|
|
41
|
+
- **Extension** — adds a mechanism the specification does not describe.
|
|
42
|
+
- **Independent design** — shares a name and a goal with a Signal Protocol system, but is
|
|
43
|
+
the SDK's own construction rather than a port of the corresponding `libsignal` system.
|
|
44
|
+
|
|
45
|
+
A fourth label, **faithful**, appears in the table where an area follows the
|
|
46
|
+
specification closely enough that its presence in this document is only to
|
|
47
|
+
delimit what the neighbouring deviations do and do not touch.
|
|
48
|
+
|
|
49
|
+
Companion documents: [Protocol Policy](./PROTOCOL_POLICY.md) states which
|
|
50
|
+
protocol modes run and which fail closed; this document states how the profile
|
|
51
|
+
differs from the specifications. [Security](./SECURITY.md) states the threat
|
|
52
|
+
model and what is out of scope.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Summary
|
|
57
|
+
|
|
58
|
+
| Area | Specification followed | Deviation or extension | Why | Consequence |
|
|
59
|
+
|---|---|---|---|---|
|
|
60
|
+
| **Identity keys** | X3DH §2.2; `libsignal` `identity_key.rs` | **Deviation.** A 67-byte composite of separate X25519 and Ed25519 keys replaces the single 33-byte Curve25519 identity key | Avoids XEdDSA, a non-standard signature scheme with no vetted JavaScript implementation; standard Ed25519 is independently verifiable | Two keys to store and rotate; larger identity; **no wire compatibility for any identity-bearing material** |
|
|
61
|
+
| **Prekey signatures** | X3DH §2.2, §4.5 | **Deviation.** RFC 8032 Ed25519 over a domain-separated context binding the identity commitment, algorithm tag, and key ID — not XEdDSA over the bare key | Defeats cross-algorithm and cross-key-ID substitution that a bare-key signature does not cover | Strictly stronger binding; signatures are unverifiable by Signal Messenger clients and vice versa |
|
|
62
|
+
| **Safety numbers** | `libsignal` `fingerprint.rs` | **Deviation.** Iteration and digit encoding are byte-identical, but the input is a composite-identity commitment under an SDK domain string, the QR version is `3`, and the two halves are ordered by user ID rather than by digit string | Follows from the composite identity; a single-key fingerprint cannot authenticate both components | **Safety numbers are not comparable to Signal Messenger's.** The ordering rule also differs from `libsignal` even on the single-key path |
|
|
63
|
+
| **X3DH / PQXDH** | X3DH rev. 1; PQXDH rev. 3 | **Faithful** on DH order, the `0xFF`×32 prefix, zero-salt HKDF, and KEM-secret position. **Deviation:** ML-KEM-1024 (FIPS 203) runs under an info string naming `CRYSTALS-KYBER-1024` | Standardized ML-KEM preferred over round-3 Kyber; the label was inherited from `libsignal` and not updated | Identical label with a different KEM means the same transcript derives a **different** shared secret, with no domain separation signalling it. Violates PQXDH §2.2 |
|
|
64
|
+
| **Associated data** | X3DH §3.3 | **Deviation.** `AD` is a domain-separated HMAC input over SHA-256 commitments to both composite identities, not `IK_A ‖ IK_B` | Binds the Ed25519 component, which a raw-key `AD` would leave uncovered | Stronger binding; wire-incompatible |
|
|
65
|
+
| **Double Ratchet** | Double Ratchet rev. 4 | **Faithful** on `WhisperRatchet`, `WhisperMessageKeys`, the `0x01`/`0x02` seeds, the 80-byte split, AES-256-CBC, the `0x44` version byte, and 8-byte MAC truncation | — | The ratchet core follows the Double Ratchet specification |
|
|
66
|
+
| **Message wire format** | `libsignal` `wire.proto` | **Faithful** field numbers 1–8. **Extension:** fields at 100+ carry identity type and ML-KEM one-time prekey material. **Deviation:** address binding uses variable-length UTF-8 user IDs and 4-byte device IDs instead of 17-byte ServiceIds and 1-byte device IDs | The SDK binds application-defined identifiers, not Signal Messenger ACIs | Wire-incompatible; a Signal Messenger client would silently ignore the added fields |
|
|
67
|
+
| **Skipped keys and archiving** | Double Ratchet §2.6; `libsignal` `consts.rs` | **Deviation.** The 2000-key cap is global rather than per-chain, eviction is by wall-clock timestamp, and skipped keys expire after 7 days. Session records serialize as JSON, not protobuf | Simpler storage accounting and bounded growth | **Legitimate messages can become undecryptable** where `libsignal` would still decrypt them: a 5× smaller effective cap, cross-chain eviction, and a hard 7-day limit for offline recipients |
|
|
68
|
+
| **Padding** | — | **Extension.** ISO 7816-4 bit padding to 160-byte buckets inside the library | Length hiding by default rather than left to the application | `libsignal` does not pad at this layer; Signal Messenger's apps do. PKCS#7 then adds a block, so ciphertext lands 16 bytes past each boundary |
|
|
69
|
+
| **SPQR / ML-KEM Braid** | ML-KEM Braid rev. 1 | **Deviation.** Same protocol, same KDF labels, same Reed–Solomon parameters, byte-identical message framing — except `hek = SHA3-256(ek_seed ‖ ek_vector)`, the operand order the specification states, which is the reverse of `libsignal`'s implementation | The normative text was followed over the executable reference | Wire-visible. Headers, ciphertexts, and shared secrets diverge; a braid session cannot complete a single epoch against `libsignal`'s implementation. Also means the KEM is not FIPS 203 in braid mode |
|
|
70
|
+
| **Triple Ratchet** | `libsignal` `triple_ratchet.rs` | **Faithful.** The PQ secret enters as the HKDF salt at message-key expansion, same label, same order | — | The braiding construction follows the ML-KEM Braid specification |
|
|
71
|
+
| **Sesame** | Sesame rev. 2 | **Deviation** on session expiry (§4.2 applies only to unacknowledged sessions) and on deleted devices (hard-removed rather than marked stale). **Extensions:** QR provisioning, device transfer, encrypted device names, identity-change gating, a 5-device cap | Product requirements the specification does not address | Hard deletion **drops the MAXLATENCY window, so in-flight messages from a just-removed device become permanently undecryptable**. Device transfer clones ratchet state, which weakens the forward-secrecy bound |
|
|
72
|
+
| **Sealed sender v1** | `libsignal` `sealed_sender.rs` | **Deviation.** Correct labels, cipher, and MAC length, but the 96-byte HKDF output is split `(cipher, mac, chain)` where `libsignal` splits `(chain, cipher, mac)`; keys in the salt omit the `0x05` type byte; the inner envelope is a hand-rolled varint format rather than the `UnidentifiedSenderMessage.Message` protobuf | The slice order and the missing prefix are unintentional; the envelope is a deliberate simplification | Self-consistent and secure, but every v1 key sits in a different slot than `libsignal`'s. The envelope also drops the message-type field |
|
|
73
|
+
| **Sealed sender v2** | `libsignal` `sealed_sender.rs` | **Faithful** on all four labels, the KEM, AES-256-GCM-SIV, the multi-recipient binary format, and the `0x3FFF` registration-ID mask | — | The v2 construction follows `libsignal` |
|
|
74
|
+
| **Delivery token** | `libsignal` `profile_key.rs` | **Faithful.** `deriveAccessKey` follows `libsignal`'s `ProfileKey::derive_access_key`, and reproduces `libsignal`'s published known-answer values | — | Not an SDK invention, despite what the module name suggests |
|
|
75
|
+
| **Sender keys** | `libsignal` `sender_keys.rs` | **Deviation.** Protobuf field numbers and `0x33` framing match, and the `0x01`/`0x02` seeds match, but message-key derivation **omits HKDF-Extract**, signatures are Ed25519 not XEdDSA, and `distributionUuid` carries a UTF-8 string rather than 16 UUID bytes | The Ed25519 choice follows the identity profile; the missing Extract appears unintentional | Group message keys differ from `libsignal`'s for the same chain key. Confirmed numerically, not merely by inspection |
|
|
76
|
+
| **Groups v2** | Signal Private Group System | **Independent design.** Real zkgroup primitives underneath, but the client is the state authority: it re-encrypts and uploads whole group state, and server signatures are not verified | Ships a working group system without a validating server | The relay **cannot validate group changes**, so it cannot enforce roles or membership. This is a materially weaker trust model than the Signal Private Group System, where the server validates every change against zero-knowledge presentations |
|
|
77
|
+
| **zkgroup / zkcredential** | `libsignal` `zkgroup`, `zkcredential`, `poksho` | **Faithful** port of the Ristretto255 KVAC and Sigma-protocol system, verified against `libsignal`'s known-answer vectors. **Deviation:** server parameter derivation uses SDK-specific labels | Server keys are the SDK's own trust root, not Signal Messenger's | The zero-knowledge properties are real. Credentials are not interchangeable with Signal Messenger's |
|
|
78
|
+
| **Registration IDs** | `libsignal` `sealed_sender.rs` | **Faithful** as of 0.1.0-alpha.4. Generated in `[1, 16383]`, strictly inside the 14 bits the wire format reserves | — | Through alpha.3 the range ran to 16384, which masked to `0` on the wire in multi-recipient sealed sender for roughly 1 install in 16,384 |
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 1. Identity keys and signatures
|
|
83
|
+
|
|
84
|
+
### 1.1 Composite identity replaces the single Curve25519 key
|
|
85
|
+
|
|
86
|
+
`libsignal` represents an identity as one Curve25519 public key serialized as
|
|
87
|
+
`0x05 ‖ key` — 33 bytes ([`identity_key.rs:23-49`][ik]). The same private key is
|
|
88
|
+
used both for Diffie-Hellman and, via XEdDSA, for signing.
|
|
89
|
+
|
|
90
|
+
This SDK stores a versioned tuple of two separate keys
|
|
91
|
+
(`keys/identity.ts:20-23`, `:66-72`):
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
0x01 version
|
|
95
|
+
|| 0x01 || 32-byte X25519 public key DH component
|
|
96
|
+
|| 0x02 || 32-byte Ed25519 public key signing component
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
67 bytes, X25519 first. Decoding fails closed on any wrong version byte, tag, or
|
|
100
|
+
length (`keys/identity.ts:75-96`).
|
|
101
|
+
|
|
102
|
+
**Why.** XEdDSA ([spec][xeddsa]) lets one Curve25519 key serve both roles by
|
|
103
|
+
converting a Montgomery point to an Edwards point at signing time. It is
|
|
104
|
+
elegant, and it is also non-standard: no vetted JavaScript implementation exists,
|
|
105
|
+
the conversion has sign-bit handling that is easy to get subtly wrong, and the
|
|
106
|
+
resulting signatures cannot be checked by any general-purpose Ed25519 verifier.
|
|
107
|
+
Carrying an explicit Ed25519 key costs 32 bytes and one more key to manage, and
|
|
108
|
+
buys signatures that any RFC 8032 implementation can verify and that auditors can
|
|
109
|
+
reason about without first reasoning about curve conversion.
|
|
110
|
+
|
|
111
|
+
**Cost.** Two keys to generate, store, rotate, and back up. A larger identity on
|
|
112
|
+
the wire and at rest. And no wire compatibility for anything that carries an
|
|
113
|
+
identity: prekey bundles, initial messages, sender certificates, safety numbers.
|
|
114
|
+
`libsignal`'s `IdentityKey::decode` reads the leading `0x01` as an unknown key
|
|
115
|
+
type and errors.
|
|
116
|
+
|
|
117
|
+
A commitment binds the tuple (`keys/identity.ts:98-100`):
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
SHA-256(UTF8("signal-protocol-js composite identity v1") || CompositeIdentityV1)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
A commitment received from a relay, cache, or caller is never trusted; it is
|
|
124
|
+
recomputed and compared in constant time (`keys/identity.ts:103-111`), and every
|
|
125
|
+
producer of stored identity bytes is forced through a decode/re-encode round trip
|
|
126
|
+
so that two encodings of the same key cannot forge an identity-change event
|
|
127
|
+
(`keys/identity.ts:154-161`). `libsignal` has no commitment concept, because a
|
|
128
|
+
single-key format has nothing to bind together.
|
|
129
|
+
|
|
130
|
+
**Not ported.** `libsignal`'s ACI↔PNI alternate-identity signature
|
|
131
|
+
([`identity_key.rs:61-70`][ik]) has no SDK equivalent. ACI and PNI are fully
|
|
132
|
+
independent identities here with independent trust histories; neither certifies
|
|
133
|
+
the other. An application that wants a user's two identities linked must
|
|
134
|
+
establish that link itself.
|
|
135
|
+
|
|
136
|
+
### 1.2 Prekey signatures are Ed25519 over a domain-separated context
|
|
137
|
+
|
|
138
|
+
`libsignal` signs the bare serialized public key with the identity key via
|
|
139
|
+
XEdDSA, and verifies the same way ([`session.rs:199-213`][sess]).
|
|
140
|
+
|
|
141
|
+
This SDK signs, with the separate Ed25519 key (`keys/prekey-signature.ts:39-45`):
|
|
142
|
+
|
|
143
|
+
```text
|
|
144
|
+
UTF8("signal-protocol-js prekey signature v1")
|
|
145
|
+
|| SHA-256 identity commitment
|
|
146
|
+
|| algorithm tag (1 byte)
|
|
147
|
+
|| key ID (uint32, big-endian)
|
|
148
|
+
|| serialized public key
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
ML-KEM prekeys must carry their `0x0A` tag inside the signed bytes
|
|
152
|
+
(`keys/prekey-signature.ts:33-38`).
|
|
153
|
+
|
|
154
|
+
**Why.** A bare-key signature says only "the identity holder signed these 32
|
|
155
|
+
bytes." It does not say which algorithm the key is for, which key ID it occupies,
|
|
156
|
+
or which identity it belongs to. Binding all three defeats cross-algorithm
|
|
157
|
+
substitution (presenting an X25519 signature as an ML-KEM one) and cross-key-ID
|
|
158
|
+
substitution. This is strictly stronger than the specification requires.
|
|
159
|
+
|
|
160
|
+
**Cost.** Wire incompatibility, and a signature format that no Signal Messenger
|
|
161
|
+
implementation can verify.
|
|
162
|
+
|
|
163
|
+
The same Ed25519-instead-of-XEdDSA choice applies to sealed sender certificates
|
|
164
|
+
(`internal/protocol/sealed-sender/certificate.ts:59`, `:106`) and to sender key
|
|
165
|
+
messages (§7.2).
|
|
166
|
+
|
|
167
|
+
XEdDSA and VXEdDSA are not implemented, not stubbed, and not claimed anywhere in
|
|
168
|
+
this codebase. Where the frozen upstream specification snapshots mention them,
|
|
169
|
+
that is upstream text; the SDK's own documentation consistently states that
|
|
170
|
+
ordinary Ed25519 is used instead.
|
|
171
|
+
|
|
172
|
+
### 1.3 Safety numbers are not comparable to Signal Messenger's
|
|
173
|
+
|
|
174
|
+
State this without hedging: **a safety number produced by this SDK will never
|
|
175
|
+
match the safety number Signal Messenger shows for the same two users.** A user cannot
|
|
176
|
+
verify a contact by reading a number out of one application and comparing it
|
|
177
|
+
against the other.
|
|
178
|
+
|
|
179
|
+
Three independent reasons, any one of which is sufficient.
|
|
180
|
+
|
|
181
|
+
**The user-facing number is computed over a composite commitment.**
|
|
182
|
+
`client.verify()` uses `generateCompositeSafetyNumber`
|
|
183
|
+
(`client/sessions.ts:326`, `:432-433`), whose per-party hash iterates over
|
|
184
|
+
`UTF8("signal-protocol-js composite safety number v1") ‖ type-tagged user ID ‖
|
|
185
|
+
SHA-256 identity commitment` (`safety/core.ts:48-50`, `:205-233`). None of that
|
|
186
|
+
input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
|
|
187
|
+
|
|
188
|
+
**The identity material differs.** Even the raw input is a 67-byte two-key tuple
|
|
189
|
+
rather than a 33-byte `0x05 ‖ X25519` key.
|
|
190
|
+
|
|
191
|
+
**The two halves are ordered by a different rule.** This one applies even on the
|
|
192
|
+
SDK's low-level single-key path, which is otherwise byte-identical to
|
|
193
|
+
`libsignal`. The SDK orders by user identifier — `localId.localeCompare(remoteId)`
|
|
194
|
+
(`safety/core.ts:177`) — where `libsignal` orders by the encoded digit strings
|
|
195
|
+
themselves ([`fingerprint.rs:32-40`][fp]). Both rules are symmetric, so the two
|
|
196
|
+
parties always agree with each other; they simply do not agree with Signal Messenger, and
|
|
197
|
+
roughly half the time the halves come out in the opposite order. `localeCompare`
|
|
198
|
+
is additionally locale-sensitive, so two devices with different default locales
|
|
199
|
+
can in principle disagree with each other on the ordering of the same pair of
|
|
200
|
+
user IDs.
|
|
201
|
+
|
|
202
|
+
What *is* faithful: the iteration is byte-for-byte `libsignal`'s — 5200
|
|
203
|
+
iterations of SHA-512 over `0x0000 ‖ key ‖ id`, then `hash ‖ key`
|
|
204
|
+
(`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp]) — as is the digit
|
|
205
|
+
encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party) and the
|
|
206
|
+
scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
|
|
207
|
+
cross-verification swap and constant-time comparison match as well.
|
|
208
|
+
|
|
209
|
+
The QR format version is the SDK's own: `3` for the composite path
|
|
210
|
+
(`safety/core.ts:46`), where `libsignal` knows only versions 1 and 2 and returns
|
|
211
|
+
`VersionMismatch` for anything else. Using a distinct version in the same
|
|
212
|
+
protobuf namespace is the correct fail-closed choice — a Signal Messenger client rejects
|
|
213
|
+
the code rather than misreading it.
|
|
214
|
+
|
|
215
|
+
The SDK also offers an emoji fingerprint (`safety/core.ts:308-392`) and
|
|
216
|
+
verification deep links (`safety/url.ts`). Both are extensions with no
|
|
217
|
+
`libsignal` counterpart. Note that the emoji form is derived from one party's
|
|
218
|
+
fingerprint only, so it carries roughly half the information of the 60-digit
|
|
219
|
+
number and should not be presented to users as an equal-strength alternative.
|
|
220
|
+
|
|
221
|
+
### 1.4 Registration ID range
|
|
222
|
+
|
|
223
|
+
Registration IDs are generated in the closed range `[1, 16383]`
|
|
224
|
+
(`keys/generation.ts:43-46`). The wire format reserves exactly 14 bits, and
|
|
225
|
+
`libsignal` rejects any ID where `id & 0x3FFF != id`
|
|
226
|
+
([`sealed_sender.rs:1508-1515`][ss]); `libsignal`'s own helper generates `[1, 16380]`.
|
|
227
|
+
|
|
228
|
+
Through 0.1.0-alpha.3 the range was `[1, 16384]`, an off-by-one: 16384 is
|
|
229
|
+
`0x4000` and does not fit in 14 bits, and the SDK's multi-recipient sealed sender
|
|
230
|
+
encoder masks rather than rejects
|
|
231
|
+
(`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so a generated `16384`
|
|
232
|
+
was written to the wire as `0` — roughly 1 install in 16,384. This is corrected
|
|
233
|
+
as of 0.1.0-alpha.4; the generated range is now strictly narrower than
|
|
234
|
+
`libsignal`'s accepted range, and a regression test asserts every generated ID
|
|
235
|
+
survives the mask unchanged.
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
## 2. X3DH and PQXDH
|
|
240
|
+
|
|
241
|
+
The key agreement is the most faithful area in the codebase. The DH computation
|
|
242
|
+
order, the 32-byte `0xFF` discontinuity prefix, the zero-filled HKDF salt, the
|
|
243
|
+
single-step derivation over the full concatenation, the position of the KEM
|
|
244
|
+
shared secret (appended last), and the 96-byte output split all match
|
|
245
|
+
`libsignal` exactly.
|
|
246
|
+
|
|
247
|
+
- Initiator DH order `DH(IK_A,SPK_B)`, `DH(EK_A,IK_B)`, `DH(EK_A,SPK_B)`,
|
|
248
|
+
`DH(EK_A,OPK_B)`: `internal/protocol/pqxdh/pqxdh.ts:243-264` vs
|
|
249
|
+
[`pqxdh.rs:202-224`][pq]. Spec X3DH §3.3.
|
|
250
|
+
- `F = 0xFF × 32` prefix: `internal/protocol/pqxdh/pqxdh.ts:267-271` vs
|
|
251
|
+
[`pqxdh.rs:200`][pq]. Spec X3DH §2.2.
|
|
252
|
+
- KEM secret appended after all DH outputs, then one HKDF:
|
|
253
|
+
`internal/protocol/pqxdh/pqxdh.ts:365-374` vs [`pqxdh.rs:226-230`][pq]. Spec
|
|
254
|
+
PQXDH §3.3.
|
|
255
|
+
|
|
256
|
+
Two hardening extensions go beyond the specification at no interop cost: every
|
|
257
|
+
remote X25519 point is validated before any DH is computed
|
|
258
|
+
(`internal/protocol/pqxdh/pqxdh.ts:219-227`), and prekey bundles are validated
|
|
259
|
+
far more strictly than `libsignal` requires
|
|
260
|
+
(`internal/session/handshake.ts:107-138`).
|
|
261
|
+
|
|
262
|
+
### 2.1 ML-KEM-1024 runs under an info string naming Kyber
|
|
263
|
+
|
|
264
|
+
The SDK uses ML-KEM-1024 (FIPS 203) where `libsignal` uses round-3 Kyber1024,
|
|
265
|
+
tagged `0x0A` rather than `0x08` (`internal/crypto/pq/kyber.ts:79`). That much is
|
|
266
|
+
deliberate: the standardized algorithm is preferred over the round-3 draft, and a
|
|
267
|
+
single unambiguous tag is preferred over carrying a legacy fallback.
|
|
268
|
+
|
|
269
|
+
The info string was not updated to match (`types/protocol-config.ts:365`):
|
|
270
|
+
|
|
271
|
+
```text
|
|
272
|
+
WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
This is byte-identical to `libsignal`'s label ([`pqxdh.rs:73-74`][pq]) while
|
|
276
|
+
naming a KEM the SDK does not use. Two consequences:
|
|
277
|
+
|
|
278
|
+
1. **It violates the SDK's own pinned specification.** PQXDH §2.2 requires the
|
|
279
|
+
info string to be the concatenation of the four PQXDH parameters *including
|
|
280
|
+
the actual `pqkem`*. The running `pqkem` is ML-KEM-1024; the string says
|
|
281
|
+
CRYSTALS-KYBER-1024.
|
|
282
|
+
2. **It removes the domain separation that would make the incompatibility
|
|
283
|
+
self-evident.** Two implementations feeding the identical label derive
|
|
284
|
+
different shared secrets, because the KEM underneath differs. A label naming
|
|
285
|
+
ML-KEM-1024 would make the non-interoperability explicit at the KDF layer.
|
|
286
|
+
|
|
287
|
+
Changing the label to name ML-KEM-1024 would satisfy §2.2 and improve the
|
|
288
|
+
situation. It is a pre-1.0 format break, and is flagged rather than fixed here.
|
|
289
|
+
|
|
290
|
+
### 2.2 Associated data binds identity commitments
|
|
291
|
+
|
|
292
|
+
X3DH §3.3 specifies `AD = Encode(IK_A) ‖ Encode(IK_B)`, and `libsignal`
|
|
293
|
+
implements exactly that with raw 33-byte serialized keys
|
|
294
|
+
([`protocol.rs:225-241`][proto]).
|
|
295
|
+
|
|
296
|
+
The SDK computes (`internal/session/identity-binding.ts:11-25`):
|
|
297
|
+
|
|
298
|
+
```text
|
|
299
|
+
HMAC-SHA256(mac_key,
|
|
300
|
+
UTF8("signal-protocol-js composite identity message mac v1")
|
|
301
|
+
|| SHA-256 commitment to sender's composite identity
|
|
302
|
+
|| SHA-256 commitment to receiver's composite identity
|
|
303
|
+
|| version byte || protobuf bytes
|
|
304
|
+
)[0..8]
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
**Why.** With a two-key identity, an `AD` over the DH key alone would leave the
|
|
308
|
+
Ed25519 signing component unbound — the component that authenticates every prekey
|
|
309
|
+
the peer will ever publish. Hashing the commitment covers both.
|
|
310
|
+
|
|
311
|
+
**Cost.** This is the single largest wire deviation in the message path. The
|
|
312
|
+
truncation to 8 bytes matches `libsignal`'s convention, and the construction is sound
|
|
313
|
+
and domain-separated, but a Signal Messenger client and this SDK cannot exchange a single
|
|
314
|
+
message.
|
|
315
|
+
|
|
316
|
+
### 2.3 One-time prekey deletion is deferred
|
|
317
|
+
|
|
318
|
+
PQXDH §3.4 has Bob delete a used one-time prekey after successful decryption. The
|
|
319
|
+
SDK records a pending deletion (`internal/manager/manager.ts:940-952`) and
|
|
320
|
+
commits it only once a prekey message decrypts
|
|
321
|
+
(`internal/session/cipher.ts:1189-1200`). This is compliant in letter and widens
|
|
322
|
+
the window in which the same first ciphertext can be replayed before commit;
|
|
323
|
+
duplicate and missing-prekey conditions are refused auto-recovery
|
|
324
|
+
(`internal/session/cipher.ts:1519-1527`).
|
|
325
|
+
|
|
326
|
+
### 2.4 Ratchet initialization details
|
|
327
|
+
|
|
328
|
+
Two differences at the boundary between key agreement and the ratchet:
|
|
329
|
+
|
|
330
|
+
**Alice reuses her key-agreement ephemeral as her first ratchet key**
|
|
331
|
+
(`internal/session/builder.ts:159-171`). `libsignal` generates a fresh sending
|
|
332
|
+
ratchet key distinct from the handshake ephemeral ([`ratchet.rs:77-81`][rat]), so
|
|
333
|
+
the prekey message's base key and the first message's ratchet key differ. Here
|
|
334
|
+
they are the same value. No concrete attack follows, but it is a reduction in key
|
|
335
|
+
separation and it is wire-visible.
|
|
336
|
+
|
|
337
|
+
**Bob initializes without a sending chain** (`internal/session/builder.ts:326-364`),
|
|
338
|
+
deriving chains on the first DH ratchet, where `libsignal` seeds a sending chain
|
|
339
|
+
immediately ([`ratchet.rs:137-172`][rat]). A side effect is that bytes 32–64 of
|
|
340
|
+
the 96-byte derivation — the initial chain key — never produce a message key on
|
|
341
|
+
either side. The 96-byte split is retained for shape compatibility, but only the
|
|
342
|
+
root key and the SPQR key are load-bearing.
|
|
343
|
+
|
|
344
|
+
### 2.5 Classical fallback is retained but gated
|
|
345
|
+
|
|
346
|
+
`libsignal` has removed X3DH entirely and rejects pre-Kyber prekey messages
|
|
347
|
+
([`session.rs:105-112`][sess]). The SDK keeps the X3DH path reachable only via an
|
|
348
|
+
explicit opt-in; the default is fail-closed, and any PQXDH failure raises rather
|
|
349
|
+
than silently downgrading (`internal/session/handshake.ts:167-260`). This is a
|
|
350
|
+
downgrade surface that `libsignal` has closed, and it is documented in
|
|
351
|
+
[Protocol Policy](./PROTOCOL_POLICY.md).
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## 3. Double Ratchet and wire format
|
|
356
|
+
|
|
357
|
+
### 3.1 The ratchet core is faithful
|
|
358
|
+
|
|
359
|
+
Byte-for-byte with `libsignal`: the `0x01`/`0x02` chain-key seeds
|
|
360
|
+
(`internal/crypto/kdf/hkdf.ts:183-195` vs [`keys.rs:148-149`][rk]), the
|
|
361
|
+
`WhisperMessageKeys` expansion to 80 bytes split 32/32/16
|
|
362
|
+
(`internal/crypto/kdf/hkdf.ts:215-243` vs [`keys.rs:100-118`][rk]), the
|
|
363
|
+
`WhisperRatchet` root-key step producing a 64-byte split
|
|
364
|
+
(`internal/crypto/kdf/hkdf.ts:141-161` vs [`keys.rs:199-218`][rk]), the DH ratchet
|
|
365
|
+
half-step ordering, `MAX_RECEIVER_CHAINS = 5`, AES-256-CBC with PKCS#7, the
|
|
366
|
+
`0x44` version byte, and 8-byte MAC truncation.
|
|
367
|
+
|
|
368
|
+
Message framing matches too: `[version byte] ‖ protobuf ‖ [8-byte HMAC]` for
|
|
369
|
+
messages and `[version byte] ‖ protobuf` for prekey messages
|
|
370
|
+
(`internal/encoding/proto/envelope.ts:104-168`). What goes *into* the MAC does
|
|
371
|
+
not — see §2.2.
|
|
372
|
+
|
|
373
|
+
Protobuf fields 1–8 match [`wire.proto`][wp] exactly, including `libsignal`'s
|
|
374
|
+
non-obvious ordering where `registrationId` is field 5 and `signedPreKeyId` is
|
|
375
|
+
field 6.
|
|
376
|
+
|
|
377
|
+
### 3.2 Added fields and address binding
|
|
378
|
+
|
|
379
|
+
**Extension.** The SDK adds fields in the 100+ range that `libsignal` does not
|
|
380
|
+
have: `recipientIdentityType` on both message types, and `kemOneTimePreKeyId` /
|
|
381
|
+
`kemOneTimeCiphertext` on prekey messages
|
|
382
|
+
(`internal/encoding/proto/signal-message.ts:80`, `:226-228`). High numbering
|
|
383
|
+
avoids collision with future upstream fields. A Signal Messenger client would parse the
|
|
384
|
+
message and silently ignore them, losing the identity-type binding.
|
|
385
|
+
|
|
386
|
+
**Deviation.** `libsignal` binds addresses as a 17-byte fixed-width ServiceId plus
|
|
387
|
+
a 1-byte device ID ([`protocol.rs:246-260`][proto]). The SDK binds a
|
|
388
|
+
format-version byte, a varint-length-prefixed UTF-8 user ID, and a 4-byte
|
|
389
|
+
big-endian device ID (`internal/encoding/proto/signal-message.ts:84-92`). The
|
|
390
|
+
encoding is unambiguous, but it authenticates an application-defined identifier
|
|
391
|
+
rather than a Signal Messenger ACI or PNI — which is the correct thing for this SDK to bind
|
|
392
|
+
and an incompatible thing to put on the wire.
|
|
393
|
+
|
|
394
|
+
The SDK is also stricter than `libsignal` on decode, requiring fields that
|
|
395
|
+
`libsignal` treats as optional for backward compatibility and enforcing exact
|
|
396
|
+
lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). Safer,
|
|
397
|
+
and one more reason the formats cannot meet.
|
|
398
|
+
|
|
399
|
+
### 3.3 Skipped-key retention is materially tighter than libsignal's
|
|
400
|
+
|
|
401
|
+
The constants match — `MAX_MESSAGE_KEYS = 2000`, `MAX_FORWARD_JUMPS = 25000`
|
|
402
|
+
(`internal/protocol/double-ratchet/ratchet.ts:194-227` vs [`consts.rs:8-9`][consts])
|
|
403
|
+
— but they are applied differently, and the difference is user-visible.
|
|
404
|
+
|
|
405
|
+
**The cap is global, not per-chain.** `libsignal` applies 2000 to each chain's key
|
|
406
|
+
vector ([`double_ratchet.rs:349-361`][dr]), so with five receiver chains the true
|
|
407
|
+
system capacity is 10,000 skipped keys. The SDK counts across all chains and
|
|
408
|
+
evicts when the total reaches 2000
|
|
409
|
+
(`internal/protocol/double-ratchet/chains.ts:478-513`). The effective capacity is
|
|
410
|
+
5× smaller, and traffic on a newer chain can evict keys belonging to an older one.
|
|
411
|
+
|
|
412
|
+
**Eviction is by wall-clock timestamp**, scanning every chain for the oldest
|
|
413
|
+
entry (`internal/protocol/double-ratchet/chains.ts:414-463`), where `libsignal`
|
|
414
|
+
evicts strictly by insertion position. `Date.now()` is not monotonic, so eviction
|
|
415
|
+
order is not deterministic across clock adjustments.
|
|
416
|
+
|
|
417
|
+
**Skipped keys expire after 7 days**
|
|
418
|
+
(`internal/protocol/double-ratchet/ratchet.ts:197`). `libsignal` has no
|
|
419
|
+
time-based expiry for message keys at all.
|
|
420
|
+
|
|
421
|
+
Taken together: **there are message-delivery patterns where this SDK reports an
|
|
422
|
+
undecryptable message and `libsignal` would have decrypted it.** A recipient
|
|
423
|
+
offline for more than a week, or one receiving heavy traffic on a new chain while
|
|
424
|
+
older-chain messages are still in flight, can lose messages that the
|
|
425
|
+
specification's own limits would have preserved. The bounds are defensible as
|
|
426
|
+
storage hygiene; the consequence should not be a surprise.
|
|
427
|
+
|
|
428
|
+
Two related extensions: a `processedChains` map rejects messages bearing a ratchet
|
|
429
|
+
key from an already-retired chain (`internal/protocol/double-ratchet/ratchet.ts:141-153`),
|
|
430
|
+
closing a replay gap that `libsignal` handles only via its five-chain window; and
|
|
431
|
+
self-sessions get a finite 100,000-message skip limit
|
|
432
|
+
(`internal/session/validation.ts:453-461`) where `libsignal` uses `usize::MAX`.
|
|
433
|
+
|
|
434
|
+
### 3.4 Session archiving and serialization
|
|
435
|
+
|
|
436
|
+
The cap matches (40 archived states, [`consts.rs:11`][consts]), but the structure
|
|
437
|
+
differs. `libsignal` keeps an ordered list with strict insertion-order eviction
|
|
438
|
+
([`session.rs:787-830`][st]); the SDK keeps a map keyed by base key and trims by
|
|
439
|
+
`lastUsedAt` (`types/session.ts:815-847`). Archiving a session whose base key
|
|
440
|
+
already exists overwrites rather than appends, so the effective history can be
|
|
441
|
+
shorter than 40.
|
|
442
|
+
|
|
443
|
+
`libsignal` clears unacknowledged prekey state before archiving a session; the SDK
|
|
444
|
+
does not. Retired sessions therefore keep pending prekey references alive in
|
|
445
|
+
storage.
|
|
446
|
+
|
|
447
|
+
**Session records serialize as JSON, not protobuf** (`types/session.ts:1002-1028`).
|
|
448
|
+
This is acknowledged in the source as a simplicity and debuggability choice.
|
|
449
|
+
Consequences worth naming: stored sessions are not portable to or from any Signal Messenger
|
|
450
|
+
client, and key material sits in immutable JavaScript strings that cannot be
|
|
451
|
+
zeroed, where `libsignal`'s byte vectors can be.
|
|
452
|
+
|
|
453
|
+
### 3.5 Padding
|
|
454
|
+
|
|
455
|
+
**Extension.** Message plaintext is padded to 160-byte buckets with ISO 7816-4 bit
|
|
456
|
+
padding — a `0x80` terminator followed by zeros
|
|
457
|
+
(`internal/crypto/symmetric/padding.ts:19-60`). Unpadding scans backwards and
|
|
458
|
+
rejects malformed padding with a deliberately generic error to avoid a padding
|
|
459
|
+
oracle.
|
|
460
|
+
|
|
461
|
+
`libsignal` does not bucket-pad at this layer; in Signal Messenger, that lives in the client
|
|
462
|
+
applications. Doing it in the library means length hiding is on by default rather
|
|
463
|
+
than a thing each integrator must remember.
|
|
464
|
+
|
|
465
|
+
One imprecision: because the padded plaintext is an exact multiple of 160 and
|
|
466
|
+
AES-CBC then applies PKCS#7, a full block is always appended. A 5-byte message
|
|
467
|
+
produces 160 padded bytes and 176 ciphertext bytes. Length is still quantized in
|
|
468
|
+
160-byte steps, so the hiding property holds; the ciphertext simply sits 16 bytes
|
|
469
|
+
past each boundary rather than on it.
|
|
470
|
+
|
|
471
|
+
---
|
|
472
|
+
|
|
473
|
+
## 4. SPQR and the ML-KEM Braid
|
|
474
|
+
|
|
475
|
+
This is the same protocol as the SparsePostQuantumRatchet v1 protocol, implemented
|
|
476
|
+
independently and pinned against `SparsePostQuantumRatchet v1.5.1` (commit
|
|
477
|
+
`f2589fef`). The fidelity is high and specific:
|
|
478
|
+
|
|
479
|
+
- **KDF labels are byte-identical**, including the double space in
|
|
480
|
+
`"Signal PQ Ratchet V1 Chain Start"` (`internal/crypto/kdf/hkdf.ts:353-368`).
|
|
481
|
+
- **The authenticator construction matches**, including `PROTOCOL_INFO =
|
|
482
|
+
"Signal_PQCKA_V1_MLKEM768"` and the `:ekheader` / `:ciphertext` MAC inputs
|
|
483
|
+
(`internal/protocol/spqr/ml-kem-braid/kdf.ts:32-92`).
|
|
484
|
+
- **The Reed–Solomon erasure layer matches**: GF(2^16) with primitive polynomial
|
|
485
|
+
`0x1100b`, 32-byte chunks, 16 polynomials, degree bound 35. Reed–Solomon is
|
|
486
|
+
present in `libsignal`; it is not an SDK addition.
|
|
487
|
+
- **The production wire framing is byte-compatible**:
|
|
488
|
+
`VERSION ‖ LEB128(epoch) ‖ LEB128(chain_index) ‖ MSG_TYPE ‖ [LEB128(chunk_index) ‖ CHUNK]`
|
|
489
|
+
(`internal/encoding/proto/pq-ratchet-serialize.ts`), matching `libsignal`'s
|
|
490
|
+
`serialize.rs`, with the same message-type values and the same epoch offset.
|
|
491
|
+
- **ML-KEM-768 with the same incremental split** (32-byte seed, 1152-byte vector,
|
|
492
|
+
960/128-byte ciphertext parts).
|
|
493
|
+
|
|
494
|
+
### 4.1 The `hek` operand order diverges
|
|
495
|
+
|
|
496
|
+
One divergence breaks interoperability completely. The SDK computes
|
|
497
|
+
(`internal/protocol/spqr/ml-kem-braid/noble-pq/index.ts:841-843`):
|
|
498
|
+
|
|
499
|
+
```text
|
|
500
|
+
hek = SHA3-256(ek_seed || ek_vector)
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
`libsignal`, via libcrux, builds the encapsulation key as
|
|
504
|
+
`t̂ ‖ ρ` before hashing — the reverse order.
|
|
505
|
+
|
|
506
|
+
The SDK follows the **normative text of the published ML-KEM Braid
|
|
507
|
+
specification**, which states seed-first ordering. `libsignal` follows FIPS 203,
|
|
508
|
+
which serializes vector-first. The specification and the reference implementation
|
|
509
|
+
disagree, and the SDK chose the specification.
|
|
510
|
+
|
|
511
|
+
The value feeds the Fujisaki–Okamoto transform, so the consequences cascade:
|
|
512
|
+
different header bytes, so `libsignal`'s header validation rejects the SDK's output;
|
|
513
|
+
different ciphertext; different shared secret; different epoch secret; different
|
|
514
|
+
authenticator ratchet. **A braid session between this SDK and Signal Messenger's
|
|
515
|
+
implementation cannot complete a single epoch.**
|
|
516
|
+
|
|
517
|
+
Two further consequences a reader should not have to infer:
|
|
518
|
+
|
|
519
|
+
- **In braid mode the KEM is not FIPS 203 ML-KEM-768.** It is ML-KEM-768 with a
|
|
520
|
+
modified `hek` derivation. The security argument is unaffected — the hash input
|
|
521
|
+
is a permutation of the same material — but a FIPS conformance claim would not
|
|
522
|
+
hold for this path. Direct (non-braid) mode uses stock ML-KEM-768.
|
|
523
|
+
- The SDK resolves the same spec-versus-code conflict in the *opposite* direction
|
|
524
|
+
elsewhere: for `KDF_AUTH`, it follows the `libsignal` Rust reference rather than the
|
|
525
|
+
written specification. The two choices are individually defensible and
|
|
526
|
+
collectively inconsistent about which artifact is authoritative.
|
|
527
|
+
|
|
528
|
+
The operand order is part of the public compatibility boundary stated in
|
|
529
|
+
[Protocol Policy](./PROTOCOL_POLICY.md). Changing it later would invalidate every
|
|
530
|
+
braid session persisted under the former ordering.
|
|
531
|
+
|
|
532
|
+
### 4.2 Direct mode and state format
|
|
533
|
+
|
|
534
|
+
**Extension.** An opt-in direct mode (`protocol.braid: 'disabled'`) uses stock
|
|
535
|
+
ML-KEM-768 and adds wire message types `0x80`–`0x82`
|
|
536
|
+
(`internal/encoding/proto/pq-ratchet-serialize.ts:38-45`). `libsignal`'s parser rejects
|
|
537
|
+
anything above `6`, so these are visible only within the SDK; they occupy a byte
|
|
538
|
+
range `libsignal` has not claimed. This mode has no Signal Protocol analogue.
|
|
539
|
+
|
|
540
|
+
**Independent design.** Persisted SPQR state uses a flat message with 20 fields
|
|
541
|
+
where `libsignal` uses an 11-variant `oneof` over nested structures. Serialized SPQR
|
|
542
|
+
state is not portable in either direction.
|
|
543
|
+
|
|
544
|
+
**Deviation.** Skipped-key eviction in the SPQR chain triggers at the cap and
|
|
545
|
+
evicts by wall-clock timestamp, where `libsignal` triggers at `max_ooo × 11/10 + 1` and
|
|
546
|
+
evicts by message index. `libsignal`'s rule is deterministic and index-anchored; the
|
|
547
|
+
SDK's introduces a clock dependency into ratchet state.
|
|
548
|
+
|
|
549
|
+
### 4.3 The Triple Ratchet is faithful
|
|
550
|
+
|
|
551
|
+
The post-quantum secret enters as the HKDF **salt** at message-key expansion, with
|
|
552
|
+
the classical message key as IKM and the `WhisperMessageKeys` label
|
|
553
|
+
(`internal/session/cipher.ts:453-510`) — the same combination order and the same
|
|
554
|
+
label as [`triple_ratchet.rs`][tr]. There is no root-key braiding in either
|
|
555
|
+
implementation.
|
|
556
|
+
|
|
557
|
+
Note that `internal/protocol/triple-ratchet/` contains a second, unused hybrid KDF
|
|
558
|
+
using the label `'Signal Triple Ratchet V1'`. It is exported but not called from
|
|
559
|
+
the message path, and it is incompatible with what the SDK actually puts on the
|
|
560
|
+
wire. It is documented in the PR that accompanied this file as cleanup work.
|
|
561
|
+
|
|
562
|
+
---
|
|
563
|
+
|
|
564
|
+
## 5. Sesame
|
|
565
|
+
|
|
566
|
+
Sesame has no reference implementation to compare against — `libsignal` does not
|
|
567
|
+
implement it; device and session management lives in the Signal Messenger service and its
|
|
568
|
+
clients. Everything below is measured against the pinned specification text
|
|
569
|
+
(revision 2) alone.
|
|
570
|
+
|
|
571
|
+
Faithful: the user-record and device-record structure (§3.1), the per-device
|
|
572
|
+
session fan-out on send including the sender's own other devices (§3.3), the
|
|
573
|
+
bounded send loop (§3.3, §6.5), discard-all-changes-on-error handled
|
|
574
|
+
transactionally (§3.3, §3.4, §6.7), and creating a session on receive only from an
|
|
575
|
+
initiating message (§3.4). The per-user identity model is one of the two the
|
|
576
|
+
specification explicitly permits (§3.1).
|
|
577
|
+
|
|
578
|
+
### 5.1 Deleted devices are removed rather than marked stale
|
|
579
|
+
|
|
580
|
+
§3.1 and §3.3 require a removed device's record to be marked stale and retained
|
|
581
|
+
for MAXLATENCY, so that messages already in flight from that device still
|
|
582
|
+
decrypt. The SDK removes the record immediately
|
|
583
|
+
(`internal/sesame/manager.ts:2098-2102`).
|
|
584
|
+
|
|
585
|
+
**Consequence, stated plainly: a message sent by a device that was removed moments
|
|
586
|
+
earlier becomes permanently undecryptable.** The specification's staleness window
|
|
587
|
+
exists precisely to prevent this. This is the most substantive contradiction of
|
|
588
|
+
the Sesame text in the codebase.
|
|
589
|
+
|
|
590
|
+
Relatedly, the SDK reuses the word `stale` for a different concept — a device
|
|
591
|
+
*list* that needs refetching (`internal/sesame/types.ts:476-483`) — rather than
|
|
592
|
+
the specification's meaning of a deleted user or device.
|
|
593
|
+
|
|
594
|
+
### 5.2 Session expiry applies only to unacknowledged sessions
|
|
595
|
+
|
|
596
|
+
§4.2 is unconditional: at MAXSEND past its timestamp, a session must no longer be
|
|
597
|
+
used for encryption. The SDK applies that bound only to sessions that have never
|
|
598
|
+
received a reply (`internal/sesame/types.ts:175-199`). A session that received one
|
|
599
|
+
message on its first day remains a valid encryption session indefinitely.
|
|
600
|
+
|
|
601
|
+
The configuration field is honestly renamed to `maxUnacknowledgedSessionAge` to
|
|
602
|
+
reflect this. The gap worth naming is that the §4.2 invariant check
|
|
603
|
+
(`internal/sesame/validation.ts:93-101`) is still validated against that renamed
|
|
604
|
+
quantity, so it is enforcing the specification's arithmetic over a value that no
|
|
605
|
+
longer carries the specification's meaning.
|
|
606
|
+
|
|
607
|
+
### 5.3 Device limit
|
|
608
|
+
|
|
609
|
+
A hard cap of 5 devices per user (`internal/sesame/types.ts:45-50`, enforced at
|
|
610
|
+
`internal/sesame/manager.ts:285-290`). §6.5 recommends *a* limit without fixing
|
|
611
|
+
one; `libsignal` permits device IDs up to 127. This is a product decision, and a
|
|
612
|
+
source comment attributing it to the Signal Protocol is inaccurate.
|
|
613
|
+
|
|
614
|
+
### 5.4 Extensions: provisioning, transfer, device names
|
|
615
|
+
|
|
616
|
+
None of these exist in Sesame rev. 2, which says nothing about how devices come to
|
|
617
|
+
exist, are named, or migrate.
|
|
618
|
+
|
|
619
|
+
**QR device provisioning** (`device/provisioning.ts`). Ephemeral X25519 ECDH →
|
|
620
|
+
HKDF → AES-256-GCM, with a `signalprotocol://link-device` QR scheme, strict prefix
|
|
621
|
+
and key validation, a 5-minute TTL, and rollback on both server and local failure.
|
|
622
|
+
The construction is sound. The property worth naming: the provisioning key is not
|
|
623
|
+
bound to the primary device's long-term identity, so the channel is authenticated
|
|
624
|
+
only by out-of-band display of the QR code.
|
|
625
|
+
|
|
626
|
+
**Device transfer** (`device/transfer.ts`). Clones the identity private key and
|
|
627
|
+
live ratchet state to a new device. This is useful and it **violates the
|
|
628
|
+
invariant Sesame is built on** — one device record, one device, its own sessions.
|
|
629
|
+
After a transfer, two physical devices hold the same identity private key and the
|
|
630
|
+
same ratchet state for every peer. Peer messages decrypted by one desynchronize
|
|
631
|
+
the other, and duplicating ratchet state weakens the forward-secrecy guarantee
|
|
632
|
+
that compromise of one endpoint is bounded to that endpoint. Archived sessions are
|
|
633
|
+
deliberately dropped on restore, which also discards the convergence state §3.4
|
|
634
|
+
depends on.
|
|
635
|
+
|
|
636
|
+
**Encrypted device names** (`device/device-name-crypto.ts`). A three-field
|
|
637
|
+
protobuf with a synthetic IV derived by HMAC and AES-256-CTR — the standard SIV
|
|
638
|
+
pattern, correctly constructed. No specification counterpart.
|
|
639
|
+
|
|
640
|
+
**Identity-change gating.** Unseen identities are TOFU-pinned; a changed identity
|
|
641
|
+
sets `pendingVerification` and blocks sending until the application accepts the
|
|
642
|
+
rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame rev. 2 has
|
|
643
|
+
no such concept. This is a genuine improvement.
|
|
644
|
+
|
|
645
|
+
**Not implemented:** proof of possession. Device registration does not require the
|
|
646
|
+
device to sign a server-issued nonce with the identity private key, so
|
|
647
|
+
registration places more trust in the relay than §6.3's discussion assumes. A
|
|
648
|
+
deployment that needs this must add it at the application layer.
|
|
649
|
+
|
|
650
|
+
---
|
|
651
|
+
|
|
652
|
+
## 6. Sealed sender
|
|
653
|
+
|
|
654
|
+
### 6.1 Version 2 is faithful
|
|
655
|
+
|
|
656
|
+
All four HKDF labels are byte-identical, the KEM construction and its
|
|
657
|
+
direction-swapped IKM orderings match, the authentication tag is the same 16-byte
|
|
658
|
+
raw HKDF output, AES-256-GCM-SIV is used with a zero nonce and no AAD as
|
|
659
|
+
`libsignal` does, and the multi-recipient binary format — version bytes
|
|
660
|
+
`0x22`/`0x23`, varint count, 17-byte ServiceIds, the packed device ID and 14-bit
|
|
661
|
+
registration ID, the `0x3FFF` mask — matches ([`sealed_sender.rs:1023-1153`][ss],
|
|
662
|
+
`:1306-1360`). Certificate validation order and semantics match as well, including
|
|
663
|
+
the non-short-circuiting trust-root loop that avoids revealing which root
|
|
664
|
+
validated.
|
|
665
|
+
|
|
666
|
+
### 6.2 Version 1 diverges in three places
|
|
667
|
+
|
|
668
|
+
**The 96-byte HKDF output is split in a different order.** `libsignal` derives
|
|
669
|
+
`(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss]); the SDK
|
|
670
|
+
derives `(cipher, mac, chain)`
|
|
671
|
+
(`internal/protocol/sealed-sender/encryption.ts:164-166`). The construction is
|
|
672
|
+
self-consistent and secure — the keys are independent HKDF output either way — but
|
|
673
|
+
every v1 key sits in a different slot than `libsignal`'s. This is an
|
|
674
|
+
implementation divergence rather than a design decision, and the SDK's own pinned
|
|
675
|
+
specification document records the same order, so the two are at least consistent
|
|
676
|
+
with each other.
|
|
677
|
+
|
|
678
|
+
**Public keys in the v1 salt and in certificates omit the `0x05` type byte.**
|
|
679
|
+
`libsignal` uses the 33-byte serialized form; the SDK uses raw 32 bytes and
|
|
680
|
+
enforces that length
|
|
681
|
+
(`internal/protocol/sealed-sender/certificate.ts:306-309`). Notably the SDK's own
|
|
682
|
+
v2 path *does* apply the `0x05` prefix, so the two sealed-sender versions are
|
|
683
|
+
internally inconsistent about this.
|
|
684
|
+
|
|
685
|
+
**The inner envelope is a hand-rolled varint format**
|
|
686
|
+
(`internal/protocol/sealed-sender/encryption.ts:46-86`) rather than the
|
|
687
|
+
`UnidentifiedSenderMessage.Message` protobuf. It omits the message-type field that
|
|
688
|
+
`libsignal` uses to dispatch between prekey and regular messages
|
|
689
|
+
([`sealed_sender.rs:2055-2075`][ss]); the unseal path reconstructs the envelope
|
|
690
|
+
with a fixed type instead.
|
|
691
|
+
|
|
692
|
+
### 6.3 The delivery token follows `libsignal`, not an SDK invention
|
|
693
|
+
|
|
694
|
+
Despite the module name, `deriveAccessKey`
|
|
695
|
+
(`internal/protocol/sealed-sender/delivery-token.ts:52-91`) is `libsignal`'s
|
|
696
|
+
`ProfileKey::derive_access_key` — AES-256-GCM over 16 zero bytes with a zero
|
|
697
|
+
nonce, truncated to 16 bytes — and it reproduces the values `libsignal`
|
|
698
|
+
publishes for that derivation. It is a 16-byte value derived from the
|
|
699
|
+
recipient's profile key
|
|
700
|
+
that proves to the relay that the sender knows that profile key, gating anonymous
|
|
701
|
+
delivery to contacts. It never enters the sealed-sender wire format; it is
|
|
702
|
+
presented out of band.
|
|
703
|
+
|
|
704
|
+
The SDK's own documentation previously described a different, 12-byte HKDF
|
|
705
|
+
construction that no code implements. That description is wrong and is corrected
|
|
706
|
+
in the PR accompanying this file.
|
|
707
|
+
|
|
708
|
+
Certificate signatures use Ed25519 rather than XEdDSA, per §1.2, so SDK
|
|
709
|
+
certificates cannot validate against a Signal Messenger trust root or vice versa. The
|
|
710
|
+
revocation list is empty where `libsignal` revokes one key ID, which is
|
|
711
|
+
appropriate for a different trust root but worth noting.
|
|
712
|
+
|
|
713
|
+
---
|
|
714
|
+
|
|
715
|
+
## 7. Sender keys and groups
|
|
716
|
+
|
|
717
|
+
### 7.1 Sender key message format
|
|
718
|
+
|
|
719
|
+
Protobuf field numbers and types match [`wire.proto`][wp] exactly, the
|
|
720
|
+
`[version byte] ‖ protobuf ‖ [64-byte signature]` framing with version `0x33`
|
|
721
|
+
matches, the `0x01`/`0x02` chain seeds and the `WhisperGroup` info string match,
|
|
722
|
+
AES-256-CBC with the derived IV matches, and the capacity constants match.
|
|
723
|
+
|
|
724
|
+
Three things do not:
|
|
725
|
+
|
|
726
|
+
**`distributionUuid` carries a UTF-8 string, not 16 UUID bytes.** The SDK writes
|
|
727
|
+
`groupId:userId:deviceId:timestamp`
|
|
728
|
+
(`internal/protocol/sender-keys/manager.ts:266`, `:493`); `libsignal` writes
|
|
729
|
+
exactly 16 raw bytes and rejects anything else on parse. Related: `chain_id` is
|
|
730
|
+
an FNV-1a hash of that string rather than a random 31-bit value.
|
|
731
|
+
|
|
732
|
+
**Signatures are Ed25519, not XEdDSA**, per §1.2 — and `libsignal` serializes the
|
|
733
|
+
signing key as 33 bytes where the SDK uses 32.
|
|
734
|
+
|
|
735
|
+
### 7.2 Message-key derivation omits HKDF-Extract
|
|
736
|
+
|
|
737
|
+
This one is worth stating precisely because the field numbers and labels above
|
|
738
|
+
make the format look compatible.
|
|
739
|
+
|
|
740
|
+
`libsignal` derives sender message keys with
|
|
741
|
+
`Hkdf::<Sha256>::new(None, &seed).expand(b"WhisperGroup", 48)`
|
|
742
|
+
([`sender_keys.rs:36-38`][sk]). `Hkdf::new` performs HKDF-**Extract** first:
|
|
743
|
+
`PRK = HMAC-SHA256(salt = zeros[32], seed)`. Only then does it expand.
|
|
744
|
+
|
|
745
|
+
The SDK calls `hkdfExpand(seed, info, 48)` directly
|
|
746
|
+
(`internal/protocol/sender-keys/manager.ts:1062-1066`), where `hkdfExpand`
|
|
747
|
+
(`internal/crypto/kdf/hkdf.ts:86-116`) is pure RFC 5869 Expand using the seed
|
|
748
|
+
itself as the PRK. The extract step is missing.
|
|
749
|
+
|
|
750
|
+
The derived IV and cipher key therefore differ from `libsignal`'s for the same
|
|
751
|
+
chain key. This was confirmed numerically, not merely by inspection: for a chain
|
|
752
|
+
key of 32 repeated `0x42` bytes, the SDK derives IV
|
|
753
|
+
`2a56b9eb80b3c1ffebd97221b2175960` where `libsignal` derives
|
|
754
|
+
`890d51ea73e564722351dc0d5a09142c`.
|
|
755
|
+
|
|
756
|
+
This appears unintentional. It is not a weakness — omitting Extract from a
|
|
757
|
+
uniformly random HMAC output is cryptographically fine — but the repository's own
|
|
758
|
+
sender-keys note claims equivalence with `libsignal` at this step, and that claim
|
|
759
|
+
is incorrect. Flagged for correction.
|
|
760
|
+
|
|
761
|
+
### 7.3 Groups v2 is an independent design
|
|
762
|
+
|
|
763
|
+
The zero-knowledge primitives underneath are real and faithful (§7.4). The group
|
|
764
|
+
system built on them is not the Signal Private Group System.
|
|
765
|
+
|
|
766
|
+
What is faithful: role and access-control enum values match `libsignal`'s exactly,
|
|
767
|
+
group ID derivation from the master key is correct, the `__signal_group__v2__!`
|
|
768
|
+
identifier encoding follows `libsignal`, authentication genuinely uses zkgroup
|
|
769
|
+
credentials, and member identifiers and profile keys are encrypted with real
|
|
770
|
+
`UidCiphertext` and `ProfileKeyCiphertext`.
|
|
771
|
+
|
|
772
|
+
What differs, and it is structural:
|
|
773
|
+
|
|
774
|
+
**The client is the state authority.** The SDK's client applies a change,
|
|
775
|
+
re-encrypts the entire group state, and uploads it
|
|
776
|
+
(`internal/groups-v2/manager.ts:1176-1193`). Signal Messenger's client submits only a set of
|
|
777
|
+
change actions, each carrying zero-knowledge presentations, and the **server**
|
|
778
|
+
validates every action and signs the result.
|
|
779
|
+
|
|
780
|
+
**Consequence, stated plainly: the relay cannot validate group changes.** It can
|
|
781
|
+
compare an expected version number and nothing else. It cannot verify that the
|
|
782
|
+
member making a change was permitted to make it, because the change actions carry
|
|
783
|
+
no zero-knowledge presentations for it to check. Any authenticated member can
|
|
784
|
+
rewrite roles, membership, and the ban list. Server signatures are returned but
|
|
785
|
+
never verified on receipt.
|
|
786
|
+
|
|
787
|
+
This is a materially weaker trust model than the Signal Private Group System, and
|
|
788
|
+
anyone deploying group messaging on this SDK needs to know it: group membership
|
|
789
|
+
and roles are enforced by cooperating clients, not by the server, and not
|
|
790
|
+
cryptographically against a malicious member. It is a reasonable position for an
|
|
791
|
+
SDK that ships without a validating server component, and it is not what a reader
|
|
792
|
+
of the Signal Private Group System documentation would assume.
|
|
793
|
+
|
|
794
|
+
**Serialization is JSON**, not protobuf, both for group state
|
|
795
|
+
(`internal/groups-v2/manager.ts:1229-1236`) and for the blob payloads inside the
|
|
796
|
+
AES-256-GCM-SIV envelope (`internal/groups-v2/encrypted-state.ts:70-81`). Every
|
|
797
|
+
encrypted group title and description is undecryptable by Signal Messenger even with the
|
|
798
|
+
correct master key.
|
|
799
|
+
|
|
800
|
+
**Invite links** use `https://join.open-e2ee.dev/#` with a 49-byte raw payload
|
|
801
|
+
(`internal/groups-v2/invite-link.ts:36`, `:78-85`), where `libsignal` uses
|
|
802
|
+
`https://signal.group/#` with a protobuf. This is labelled accurately in source as
|
|
803
|
+
the package's own format.
|
|
804
|
+
|
|
805
|
+
### 7.4 The zero-knowledge layer is a faithful port
|
|
806
|
+
|
|
807
|
+
Stated directly, because "zk" in a codebase often means something weaker: this is
|
|
808
|
+
a genuine zero-knowledge credential system, not HMAC tokens, not signatures, not a
|
|
809
|
+
placeholder.
|
|
810
|
+
|
|
811
|
+
`internal/protocol/zk/` implements the Sigma protocol over Ristretto255 with
|
|
812
|
+
Fiat–Shamir, matching `poksho`'s protocol label
|
|
813
|
+
`POKSHO_Ristretto_SHOHMACSHA256` exactly, and the Chase–Perrin–Zaverucha algebraic
|
|
814
|
+
MAC credential system matching `zkcredential`'s five domain labels byte for byte.
|
|
815
|
+
The Lizard encoding, `UidStruct` derivation, `AuthCredentialWithPni` flow, and
|
|
816
|
+
redemption window all match `libsignal`. The strongest evidence is a test that
|
|
817
|
+
asserts the 416-byte serialized system parameters against a hex string taken from
|
|
818
|
+
`libsignal`'s own Rust test, and passes.
|
|
819
|
+
|
|
820
|
+
One deviation: server secret parameters are derived under four SDK-specific labels
|
|
821
|
+
rather than `libsignal`'s single seeded derivation
|
|
822
|
+
(`internal/protocol/zk/groups/server-params.ts:43-54`). The same randomness
|
|
823
|
+
therefore yields different server keys, and credentials are not interchangeable
|
|
824
|
+
with Signal Messenger's. That follows from the SDK being its own trust root.
|
|
825
|
+
|
|
826
|
+
Credential serialization is also ad hoc and carries no version byte, where
|
|
827
|
+
`libsignal` uses a leading version byte. That is a forward-compatibility gap
|
|
828
|
+
rather than a security one.
|
|
829
|
+
|
|
830
|
+
---
|
|
831
|
+
|
|
832
|
+
## Unverified and needs review
|
|
833
|
+
|
|
834
|
+
Listed rather than asserted, because these could not be confirmed in source
|
|
835
|
+
within this review.
|
|
836
|
+
|
|
837
|
+
- **Whether a sealed-sender-wrapped prekey message decrypts end to end.** The
|
|
838
|
+
unseal path reconstructs the envelope with a fixed message type
|
|
839
|
+
(`client/sealed-sender-ops.ts:263-265`), and an adjacent comment suggests the
|
|
840
|
+
Sesame layer re-derives the initiation state from the ciphertext. That path was
|
|
841
|
+
not traced and the integration tests were not executed. If Sesame does not
|
|
842
|
+
self-detect, first-contact sealed messages would be affected.
|
|
843
|
+
- **Whether the session-identity-key check the sealed-sender note requires is
|
|
844
|
+
enforced downstream.** The decrypt path compares the certificate's identity key
|
|
845
|
+
against the decrypted static key but does not consult the session store. In
|
|
846
|
+
`libsignal` the equivalent guarantee arrives later via the identity store.
|
|
847
|
+
- **Whether `@noble/post-quantum`'s ML-KEM-1024 is byte-identical to libcrux's.**
|
|
848
|
+
The repository claims pinned known-answer-test coverage; those tests were not
|
|
849
|
+
executed as part of this review.
|
|
850
|
+
- **Lizard encoding correctness against `libsignal`'s vectors.** The forward and
|
|
851
|
+
inverse Elligator maps are hand-implemented in TypeScript. Structure and labels
|
|
852
|
+
are correct and unit tests exist, but the outputs were not diffed against
|
|
853
|
+
`libsignal`'s. A subtle error here would silently corrupt every `UidStruct`.
|
|
854
|
+
- **SPQR state-machine transition equivalence.** State names, message types, and
|
|
855
|
+
chunk counts match `libsignal`'s; the eleven-state transition table was not diffed
|
|
856
|
+
transition by transition.
|
|
857
|
+
- **Whether the SPQR decoder enforces a bound on stored points.** `libsignal` caps
|
|
858
|
+
stored points per polynomial; no equivalent bound was located in the SDK's
|
|
859
|
+
decoder.
|
|
860
|
+
- **Whether SPQR state mutations are rolled back when message authentication
|
|
861
|
+
fails.** `libsignal` commits the new state only after the MAC and decryption
|
|
862
|
+
succeed; the SDK's receive path mutates state during decode, and the caller's
|
|
863
|
+
rollback behaviour was not traced.
|
|
864
|
+
- **Whether an equivalent of `libsignal`'s `promote_matching_session` exists.**
|
|
865
|
+
`libsignal` matches archived sessions on `(version, base key)`; the SDK's map is
|
|
866
|
+
keyed on base key alone.
|
|
867
|
+
|
|
868
|
+
---
|
|
869
|
+
|
|
870
|
+
## Reporting an error in this document
|
|
871
|
+
|
|
872
|
+
If something here is wrong — a citation that does not say what it is claimed to
|
|
873
|
+
say, a deviation that has since been fixed, or a deviation that is missing —
|
|
874
|
+
email security@open-e2ee.dev or open an issue. A deviations document that has
|
|
875
|
+
drifted from the code is worse than none, because it invites exactly the
|
|
876
|
+
assumption it exists to prevent.
|
|
877
|
+
|
|
878
|
+
[ik]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/identity_key.rs
|
|
879
|
+
[fp]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/fingerprint.rs
|
|
880
|
+
[sess]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/session.rs
|
|
881
|
+
[pq]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/pqxdh.rs
|
|
882
|
+
[rat]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/ratchet.rs
|
|
883
|
+
[rk]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/ratchet/keys.rs
|
|
884
|
+
[dr]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/double_ratchet.rs
|
|
885
|
+
[proto]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/protocol.rs
|
|
886
|
+
[wp]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/proto/wire.proto
|
|
887
|
+
[consts]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/consts.rs
|
|
888
|
+
[st]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/state/session.rs
|
|
889
|
+
[ss]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/sealed_sender.rs
|
|
890
|
+
[sk]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/sender_keys.rs
|
|
891
|
+
[tr]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/triple_ratchet.rs
|
|
892
|
+
[xeddsa]: https://signal.org/docs/specifications/xeddsa/
|