@open-e2ee/signal-protocol-sdk 0.2.3 → 0.4.0
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/ADAPTERS.md +11 -4
- package/ARCHITECTURE.md +19 -16
- package/CHANGELOG.md +72 -0
- package/COMMERCIAL.md +6 -6
- package/NOTICE +1 -1
- package/README.md +65 -93
- package/SECURITY.md +16 -13
- package/TROUBLESHOOTING.md +12 -5
- package/blocking/README.md +7 -5
- package/client/README.md +15 -5
- package/device/README.md +13 -8
- package/dist/blocking/types.d.ts +2 -2
- package/dist/blocking/types.js +2 -2
- package/dist/client/client.d.ts +46 -45
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/client.js +61 -60
- package/dist/client/client.js.map +1 -1
- package/dist/client/config.d.ts +32 -32
- package/dist/client/constants.d.ts +7 -6
- package/dist/client/constants.d.ts.map +1 -1
- package/dist/client/constants.js +5 -4
- package/dist/client/constants.js.map +1 -1
- package/dist/client/dual-store.d.ts +2 -2
- package/dist/client/dual-store.js +2 -2
- package/dist/client/endorsement-manager.d.ts +14 -14
- package/dist/client/endorsement-manager.d.ts.map +1 -1
- package/dist/client/endorsement-manager.js +15 -15
- package/dist/client/endorsement-manager.js.map +1 -1
- package/dist/client/event-hooks.d.ts +16 -16
- package/dist/client/event-hooks.d.ts.map +1 -1
- package/dist/client/event-hooks.js +1 -1
- package/dist/client/event-hooks.js.map +1 -1
- package/dist/client/files.js +4 -4
- package/dist/client/files.js.map +1 -1
- package/dist/client/groups.d.ts.map +1 -1
- package/dist/client/groups.js +14 -4
- package/dist/client/groups.js.map +1 -1
- package/dist/client/headless.d.ts +7 -7
- package/dist/client/headless.d.ts.map +1 -1
- package/dist/client/headless.js +4 -4
- package/dist/client/key-rotation-core.d.ts +19 -17
- package/dist/client/key-rotation-core.d.ts.map +1 -1
- package/dist/client/key-rotation-core.js +35 -31
- package/dist/client/key-rotation-core.js.map +1 -1
- package/dist/client/key-rotation.d.ts +8 -8
- package/dist/client/key-rotation.js +8 -8
- package/dist/client/media.d.ts +1 -1
- package/dist/client/messages.d.ts.map +1 -1
- package/dist/client/messages.js +13 -11
- package/dist/client/messages.js.map +1 -1
- package/dist/client/multi-device.d.ts +5 -4
- package/dist/client/multi-device.d.ts.map +1 -1
- package/dist/client/multi-device.js.map +1 -1
- package/dist/client/prekeys.d.ts +7 -7
- package/dist/client/prekeys.js +10 -10
- package/dist/client/prekeys.js.map +1 -1
- package/dist/client/relay-subscription.d.ts +3 -0
- package/dist/client/relay-subscription.d.ts.map +1 -1
- package/dist/client/relay-subscription.js +7 -4
- package/dist/client/relay-subscription.js.map +1 -1
- package/dist/client/retry-utils.d.ts +5 -6
- package/dist/client/retry-utils.d.ts.map +1 -1
- package/dist/client/retry-utils.js +5 -12
- package/dist/client/retry-utils.js.map +1 -1
- package/dist/client/retry.js +7 -7
- package/dist/client/retry.js.map +1 -1
- package/dist/client/sealed-sender-ops.d.ts +3 -3
- package/dist/client/sealed-sender-ops.js +5 -5
- package/dist/client/sealed-sender-ops.js.map +1 -1
- package/dist/client/sessions.d.ts +2 -2
- package/dist/client/sessions.js +2 -2
- package/dist/client/signal-service-cipher.d.ts +9 -9
- package/dist/client/signal-service-cipher.d.ts.map +1 -1
- package/dist/client/signal-service-cipher.js +41 -40
- package/dist/client/signal-service-cipher.js.map +1 -1
- package/dist/client/state.d.ts +1 -1
- package/dist/client/state.js +1 -1
- package/dist/client/types.d.ts +19 -19
- package/dist/client/types.d.ts.map +1 -1
- package/dist/device/connection.d.ts +1 -1
- package/dist/device/connection.js +2 -2
- package/dist/device/connection.js.map +1 -1
- package/dist/device/constants.d.ts +4 -4
- package/dist/device/constants.js +3 -3
- package/dist/device/device-id.d.ts +4 -4
- package/dist/device/device-id.js +4 -4
- package/dist/device/expo-metadata.d.ts +13 -11
- package/dist/device/expo-metadata.d.ts.map +1 -1
- package/dist/device/expo-metadata.js +13 -11
- package/dist/device/expo-metadata.js.map +1 -1
- package/dist/device/lifecycle/manager.d.ts +6 -6
- package/dist/device/lifecycle/manager.js +7 -7
- package/dist/device/lifecycle/types.d.ts +13 -13
- package/dist/device/lifecycle/types.d.ts.map +1 -1
- package/dist/device/lifecycle/utils.d.ts +2 -2
- package/dist/device/lifecycle/utils.js +5 -5
- package/dist/device/lifecycle/utils.js.map +1 -1
- package/dist/device/provisioning.d.ts +5 -4
- package/dist/device/provisioning.d.ts.map +1 -1
- package/dist/device/provisioning.js +5 -4
- package/dist/device/provisioning.js.map +1 -1
- package/dist/device/transfer.d.ts +2 -2
- package/dist/device/transfer.js +3 -3
- package/dist/device/transfer.js.map +1 -1
- package/dist/encoding/index.d.ts +3 -4
- package/dist/encoding/index.d.ts.map +1 -1
- package/dist/encoding/index.js.map +1 -1
- package/dist/files/index.d.ts +1 -1
- package/dist/files/index.js +1 -1
- package/dist/hooks/use-connection-presence.d.ts +1 -1
- package/dist/hooks/use-connection-presence.js +7 -7
- package/dist/hooks/use-connection-presence.js.map +1 -1
- package/dist/hooks/use-group-membership.d.ts +2 -2
- package/dist/hooks/use-group-membership.d.ts.map +1 -1
- package/dist/hooks/use-group-membership.js +6 -6
- package/dist/hooks/use-group-membership.js.map +1 -1
- package/dist/hooks/use-key-rotation.js +3 -3
- package/dist/hooks/use-key-rotation.js.map +1 -1
- package/dist/hooks/use-single-flight.d.ts +2 -2
- package/dist/hooks/use-single-flight.js +1 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +21 -4
- package/dist/index.js.map +1 -1
- package/dist/internal/crypto/ec/ed25519.d.ts +6 -6
- package/dist/internal/crypto/ec/ed25519.js +6 -6
- package/dist/internal/crypto/ec/x25519-validation.d.ts.map +1 -1
- package/dist/internal/crypto/ec/x25519-validation.js +4 -2
- package/dist/internal/crypto/ec/x25519-validation.js.map +1 -1
- package/dist/internal/crypto/index.d.ts +2 -0
- package/dist/internal/crypto/index.d.ts.map +1 -1
- package/dist/internal/crypto/index.js +2 -0
- package/dist/internal/crypto/index.js.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.d.ts +9 -8
- package/dist/internal/crypto/kdf/hkdf.d.ts.map +1 -1
- package/dist/internal/crypto/kdf/hkdf.js +11 -10
- package/dist/internal/crypto/kdf/hkdf.js.map +1 -1
- package/dist/internal/crypto/key-prefix.d.ts +3 -3
- package/dist/internal/crypto/key-prefix.js +3 -3
- package/dist/internal/crypto/pq/kyber.d.ts +7 -7
- package/dist/internal/crypto/pq/kyber.js +10 -10
- package/dist/internal/crypto/pq/kyber.js.map +1 -1
- package/dist/internal/crypto/random.d.ts +1 -1
- package/dist/internal/crypto/random.js +1 -1
- package/dist/internal/crypto/symmetric/aes-gcm-siv.js +1 -1
- package/dist/internal/crypto/symmetric/aes.js +4 -4
- package/dist/internal/crypto/symmetric/aes.js.map +1 -1
- package/dist/internal/crypto/symmetric/mac.d.ts +1 -1
- package/dist/internal/crypto/symmetric/mac.js +3 -3
- package/dist/internal/crypto/symmetric/padding.js +1 -1
- package/dist/internal/crypto/symmetric/padding.js.map +1 -1
- package/dist/internal/crypto/symmetric/streaming-aead.d.ts +7 -1
- package/dist/internal/crypto/symmetric/streaming-aead.d.ts.map +1 -1
- package/dist/internal/crypto/symmetric/streaming-aead.js +10 -4
- package/dist/internal/crypto/symmetric/streaming-aead.js.map +1 -1
- package/dist/internal/crypto/utils.d.ts +2 -2
- package/dist/internal/crypto/utils.d.ts.map +1 -1
- package/dist/internal/crypto/utils.js +16 -14
- package/dist/internal/crypto/utils.js.map +1 -1
- package/dist/internal/crypto/validation.d.ts +4 -4
- package/dist/internal/crypto/validation.js +2 -2
- package/dist/internal/encoding/proto/envelope.d.ts +1 -1
- package/dist/internal/encoding/proto/envelope.js +1 -1
- package/dist/internal/encoding/proto/index.d.ts +4 -4
- package/dist/internal/encoding/proto/index.js +4 -4
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts +28 -16
- package/dist/internal/encoding/proto/pq-ratchet-serialize.d.ts.map +1 -1
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js +30 -18
- package/dist/internal/encoding/proto/pq-ratchet-serialize.js.map +1 -1
- package/dist/internal/encoding/proto/primitives.d.ts +45 -35
- package/dist/internal/encoding/proto/primitives.d.ts.map +1 -1
- package/dist/internal/encoding/proto/primitives.js +54 -43
- package/dist/internal/encoding/proto/primitives.js.map +1 -1
- package/dist/internal/encoding/proto/sender-key-message.d.ts +2 -2
- package/dist/internal/encoding/proto/sender-key-message.js +2 -2
- package/dist/internal/encoding/proto/signal-message.d.ts +13 -13
- package/dist/internal/encoding/proto/signal-message.d.ts.map +1 -1
- package/dist/internal/encoding/proto/signal-message.js +13 -13
- package/dist/internal/encoding/proto/signal-message.js.map +1 -1
- package/dist/internal/groups/access-control.d.ts +5 -5
- package/dist/internal/groups/access-control.js +6 -6
- package/dist/internal/groups/access-control.js.map +1 -1
- package/dist/internal/groups/change-actions.d.ts +4 -4
- package/dist/internal/groups/change-actions.js +3 -3
- package/dist/internal/groups/encrypted-state.js +1 -1
- package/dist/internal/groups/encrypted-state.js.map +1 -1
- package/dist/internal/groups/group-id.d.ts +1 -1
- package/dist/internal/groups/manager.d.ts +24 -23
- package/dist/internal/groups/manager.d.ts.map +1 -1
- package/dist/internal/groups/manager.js +40 -36
- package/dist/internal/groups/manager.js.map +1 -1
- package/dist/internal/groups/server-engine.d.ts +29 -21
- package/dist/internal/groups/server-engine.d.ts.map +1 -1
- package/dist/internal/groups/server-engine.js +55 -50
- package/dist/internal/groups/server-engine.js.map +1 -1
- package/dist/internal/groups/trust-root.d.ts +2 -2
- package/dist/internal/groups/trust-root.js +2 -2
- package/dist/internal/groups/types.d.ts +4 -4
- package/dist/internal/groups/types.d.ts.map +1 -1
- package/dist/internal/groups/wire.d.ts +6 -7
- package/dist/internal/groups/wire.d.ts.map +1 -1
- package/dist/internal/groups/wire.js +6 -7
- package/dist/internal/groups/wire.js.map +1 -1
- package/dist/internal/manager/manager.d.ts +14 -12
- package/dist/internal/manager/manager.d.ts.map +1 -1
- package/dist/internal/manager/manager.js +47 -41
- package/dist/internal/manager/manager.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.d.ts +8 -6
- package/dist/internal/protocol/double-ratchet/chains.d.ts.map +1 -1
- package/dist/internal/protocol/double-ratchet/chains.js +10 -8
- package/dist/internal/protocol/double-ratchet/chains.js.map +1 -1
- package/dist/internal/protocol/double-ratchet/index.d.ts +2 -2
- package/dist/internal/protocol/double-ratchet/index.js +2 -2
- package/dist/internal/protocol/double-ratchet/ratchet.d.ts +4 -4
- package/dist/internal/protocol/double-ratchet/ratchet.js +6 -6
- package/dist/internal/protocol/pqxdh/pqxdh.d.ts +21 -18
- package/dist/internal/protocol/pqxdh/pqxdh.d.ts.map +1 -1
- package/dist/internal/protocol/pqxdh/pqxdh.js +48 -42
- package/dist/internal/protocol/pqxdh/pqxdh.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption-v2.js +5 -5
- package/dist/internal/protocol/sealed-sender/decryption-v2.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/decryption.js +11 -8
- package/dist/internal/protocol/sealed-sender/decryption.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/delivery-token.d.ts +2 -2
- package/dist/internal/protocol/sealed-sender/delivery-token.js +2 -2
- package/dist/internal/protocol/sealed-sender/encryption-v2.js +1 -1
- package/dist/internal/protocol/sealed-sender/encryption-v2.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/encryption.d.ts +2 -2
- package/dist/internal/protocol/sealed-sender/encryption.js +2 -2
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts +25 -23
- package/dist/internal/protocol/sealed-sender/proto/index.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/proto/index.js +32 -30
- package/dist/internal/protocol/sealed-sender/proto/index.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts +10 -9
- package/dist/internal/protocol/sealed-sender/trust-root.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/trust-root.js +10 -9
- package/dist/internal/protocol/sealed-sender/trust-root.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.d.ts +13 -14
- package/dist/internal/protocol/sealed-sender/types.d.ts.map +1 -1
- package/dist/internal/protocol/sealed-sender/types.js +7 -8
- package/dist/internal/protocol/sealed-sender/types.js.map +1 -1
- package/dist/internal/protocol/sealed-sender/v2-binary.d.ts +1 -1
- package/dist/internal/protocol/sealed-sender/v2-binary.js +2 -2
- package/dist/internal/protocol/sealed-sender/v2-binary.js.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.d.ts +16 -14
- package/dist/internal/protocol/sender-keys/manager.d.ts.map +1 -1
- package/dist/internal/protocol/sender-keys/manager.js +37 -34
- package/dist/internal/protocol/sender-keys/manager.js.map +1 -1
- package/dist/internal/protocol/spqr/braid-serialize.d.ts +6 -6
- package/dist/internal/protocol/spqr/braid-serialize.js +5 -5
- package/dist/internal/protocol/spqr/braid-serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/braid.d.ts +3 -3
- package/dist/internal/protocol/spqr/braid.js +7 -7
- package/dist/internal/protocol/spqr/braid.js.map +1 -1
- package/dist/internal/protocol/spqr/index.js +1 -1
- package/dist/internal/protocol/spqr/index.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.d.ts +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/chunk-domain.js +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/incremental-kem.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/kdf.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/kdf.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts +4 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js +4 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/arithmetic.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/noble-pq/index.js +2 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/progress.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts +15 -7
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js +15 -7
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/codec.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/galois/field.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.d.ts +3 -3
- package/dist/internal/protocol/spqr/ml-kem-braid/rs/polynomial.js +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.d.ts +7 -7
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js +11 -11
- package/dist/internal/protocol/spqr/ml-kem-braid/serialize.js.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.d.ts +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/state-machine.js +6 -6
- 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 +2 -2
- package/dist/internal/protocol/spqr/ml-kem-braid/types.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/ml-kem-braid/types.js.map +1 -1
- package/dist/internal/protocol/spqr/serialize.d.ts +12 -12
- package/dist/internal/protocol/spqr/serialize.js +5 -5
- package/dist/internal/protocol/spqr/spqr.d.ts +6 -6
- package/dist/internal/protocol/spqr/spqr.d.ts.map +1 -1
- package/dist/internal/protocol/spqr/spqr.js +47 -42
- package/dist/internal/protocol/spqr/spqr.js.map +1 -1
- package/dist/internal/protocol/spqr/validate.d.ts +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts +12 -12
- package/dist/internal/protocol/triple-ratchet/ratchet.d.ts.map +1 -1
- package/dist/internal/protocol/triple-ratchet/ratchet.js +11 -11
- package/dist/internal/protocol/triple-ratchet/ratchet.js.map +1 -1
- package/dist/internal/protocol/username/hash.d.ts.map +1 -1
- package/dist/internal/protocol/username/hash.js +6 -4
- package/dist/internal/protocol/username/hash.js.map +1 -1
- package/dist/internal/protocol/version.d.ts +3 -3
- package/dist/internal/protocol/version.js +1 -1
- package/dist/internal/protocol/x3dh/x3dh.d.ts +16 -16
- package/dist/internal/protocol/x3dh/x3dh.d.ts.map +1 -1
- package/dist/internal/protocol/x3dh/x3dh.js +15 -15
- package/dist/internal/protocol/x3dh/x3dh.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/attributes.d.ts +7 -7
- package/dist/internal/protocol/zk/credentials/attributes.js +7 -7
- package/dist/internal/protocol/zk/credentials/credentials.d.ts +1 -1
- package/dist/internal/protocol/zk/credentials/credentials.js +1 -1
- package/dist/internal/protocol/zk/credentials/endorsements.d.ts +11 -11
- package/dist/internal/protocol/zk/credentials/endorsements.js +14 -14
- package/dist/internal/protocol/zk/credentials/issuance.d.ts +5 -1
- package/dist/internal/protocol/zk/credentials/issuance.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/issuance.js +5 -1
- package/dist/internal/protocol/zk/credentials/issuance.js.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.d.ts +16 -16
- package/dist/internal/protocol/zk/credentials/presentation.d.ts.map +1 -1
- package/dist/internal/protocol/zk/credentials/presentation.js +18 -18
- package/dist/internal/protocol/zk/credentials/presentation.js.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts +22 -16
- package/dist/internal/protocol/zk/groups/auth-credential.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/auth-credential.js +19 -14
- package/dist/internal/protocol/zk/groups/auth-credential.js.map +1 -1
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.d.ts +4 -4
- package/dist/internal/protocol/zk/groups/client-zk-group-cipher.js +4 -4
- package/dist/internal/protocol/zk/groups/group-params.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/group-params.js +2 -2
- package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts +10 -9
- package/dist/internal/protocol/zk/groups/group-send-endorsement.d.ts.map +1 -1
- package/dist/internal/protocol/zk/groups/group-send-endorsement.js +9 -8
- package/dist/internal/protocol/zk/groups/group-send-endorsement.js.map +1 -1
- package/dist/internal/protocol/zk/groups/lizard.d.ts +1 -1
- package/dist/internal/protocol/zk/groups/lizard.js +4 -4
- package/dist/internal/protocol/zk/groups/lizard.js.map +1 -1
- package/dist/internal/protocol/zk/groups/profile-key-commitment.d.ts +3 -3
- package/dist/internal/protocol/zk/groups/profile-key-commitment.js +3 -3
- package/dist/internal/protocol/zk/groups/profile-key-credential.d.ts +11 -11
- package/dist/internal/protocol/zk/groups/profile-key-credential.js +7 -7
- package/dist/internal/protocol/zk/groups/profile-key-encryption.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-encryption.js +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-struct.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-struct.js +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-version.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/profile-key-version.js +2 -2
- package/dist/internal/protocol/zk/groups/server-params.d.ts +1 -1
- package/dist/internal/protocol/zk/groups/server-params.js +1 -1
- package/dist/internal/protocol/zk/groups/uid-encryption.d.ts +4 -4
- package/dist/internal/protocol/zk/groups/uid-encryption.js +4 -4
- package/dist/internal/protocol/zk/groups/uid-struct.d.ts +2 -2
- package/dist/internal/protocol/zk/groups/uid-struct.js +3 -3
- package/dist/internal/protocol/zk/groups/uid-struct.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/args.d.ts +3 -3
- package/dist/internal/protocol/zk/proofs/args.js +3 -3
- package/dist/internal/protocol/zk/proofs/sho-sha256.d.ts +3 -3
- package/dist/internal/protocol/zk/proofs/sho-sha256.js +3 -3
- package/dist/internal/protocol/zk/proofs/sho.d.ts +8 -7
- package/dist/internal/protocol/zk/proofs/sho.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/sho.js +8 -7
- package/dist/internal/protocol/zk/proofs/sho.js.map +1 -1
- package/dist/internal/protocol/zk/proofs/statement.d.ts +8 -6
- package/dist/internal/protocol/zk/proofs/statement.d.ts.map +1 -1
- package/dist/internal/protocol/zk/proofs/statement.js +8 -6
- package/dist/internal/protocol/zk/proofs/statement.js.map +1 -1
- package/dist/internal/sesame/manager.d.ts +23 -19
- package/dist/internal/sesame/manager.d.ts.map +1 -1
- package/dist/internal/sesame/manager.js +64 -54
- package/dist/internal/sesame/manager.js.map +1 -1
- package/dist/internal/sesame/types.d.ts +28 -27
- package/dist/internal/sesame/types.d.ts.map +1 -1
- package/dist/internal/sesame/types.js +2 -4
- package/dist/internal/sesame/types.js.map +1 -1
- package/dist/internal/sesame/validation.d.ts +2 -2
- package/dist/internal/sesame/validation.js +3 -3
- package/dist/internal/sesame/validation.js.map +1 -1
- package/dist/internal/session/builder.d.ts +8 -8
- package/dist/internal/session/builder.js +22 -22
- package/dist/internal/session/builder.js.map +1 -1
- package/dist/internal/session/cipher.d.ts +3 -3
- package/dist/internal/session/cipher.d.ts.map +1 -1
- package/dist/internal/session/cipher.js +51 -40
- package/dist/internal/session/cipher.js.map +1 -1
- package/dist/internal/session/decryption.js +11 -9
- package/dist/internal/session/decryption.js.map +1 -1
- package/dist/internal/session/factory.js +1 -1
- package/dist/internal/session/factory.js.map +1 -1
- package/dist/internal/session/handshake.d.ts +4 -4
- package/dist/internal/session/handshake.js +4 -4
- package/dist/internal/session/keys.d.ts +3 -4
- package/dist/internal/session/keys.d.ts.map +1 -1
- package/dist/internal/session/keys.js.map +1 -1
- package/dist/internal/session/ratchet.d.ts +8 -8
- package/dist/internal/session/ratchet.js +10 -10
- package/dist/internal/session/ratchet.js.map +1 -1
- package/dist/internal/session/session-resolver.d.ts +6 -6
- package/dist/internal/session/session-resolver.js +6 -6
- package/dist/internal/session/state.d.ts +12 -12
- package/dist/internal/session/state.d.ts.map +1 -1
- package/dist/internal/session/state.js +7 -7
- package/dist/internal/session/types.d.ts +20 -20
- package/dist/internal/session/types.d.ts.map +1 -1
- package/dist/internal/session/types.js +3 -3
- package/dist/internal/session/validation.d.ts +1 -1
- package/dist/internal/session/validation.js +4 -4
- package/dist/internal/session/validation.js.map +1 -1
- package/dist/keys/branded.d.ts +12 -12
- package/dist/keys/branded.js +3 -3
- package/dist/keys/generation.d.ts +4 -4
- package/dist/keys/generation.js +4 -4
- package/dist/keys/identity.d.ts +7 -7
- package/dist/keys/identity.d.ts.map +1 -1
- package/dist/keys/identity.js +7 -7
- package/dist/keys/identity.js.map +1 -1
- package/dist/keys/types.d.ts +16 -16
- package/dist/keys/types.d.ts.map +1 -1
- package/dist/layers.d.ts +1 -1
- package/dist/layers.js +1 -1
- package/dist/local/store/expo/adapter.d.ts +8 -8
- package/dist/local/store/expo/adapter.js +10 -10
- package/dist/local/store/expo/adapter.js.map +1 -1
- package/dist/local/store/expo/database-key.d.ts +7 -7
- package/dist/local/store/expo/database-key.js +7 -7
- package/dist/local/store/expo/key-storage.d.ts +1 -1
- package/dist/local/store/expo/key-storage.js +4 -4
- package/dist/local/store/expo/key-storage.js.map +1 -1
- package/dist/local/store/expo/models/kyber-prekey-used.d.ts +6 -6
- package/dist/local/store/expo/models/kyber-prekey-used.js +3 -3
- package/dist/local/store/expo/models/kyber-prekey.d.ts +1 -1
- package/dist/local/store/expo/models/kyber-prekey.js +1 -1
- package/dist/local/store/expo/models/message-record.d.ts +2 -2
- package/dist/local/store/expo/models/message-record.d.ts.map +1 -1
- package/dist/local/store/expo/models/message-record.js +1 -1
- package/dist/local/store/expo/models/message-record.js.map +1 -1
- package/dist/local/store/expo/models/sender-key.d.ts +11 -10
- package/dist/local/store/expo/models/sender-key.d.ts.map +1 -1
- package/dist/local/store/expo/models/sender-key.js +11 -10
- package/dist/local/store/expo/models/sender-key.js.map +1 -1
- package/dist/local/store/expo/schema.d.ts +2 -2
- package/dist/local/store/expo/schema.js +2 -2
- package/dist/local/store/expo/secure-store-options.d.ts +1 -1
- package/dist/local/store/memory/adapter.d.ts +2 -2
- package/dist/local/store/memory/adapter.js +12 -12
- package/dist/local/store/memory/adapter.js.map +1 -1
- package/dist/local/store/node/adapter.d.ts.map +1 -1
- package/dist/local/store/node/adapter.js +5 -4
- package/dist/local/store/node/adapter.js.map +1 -1
- package/dist/local/store/node/database-key.d.ts +8 -8
- package/dist/local/store/node/database-key.js +10 -10
- package/dist/local/store/node/database-key.js.map +1 -1
- package/dist/local/store/node/database.d.ts +5 -5
- package/dist/local/store/node/database.js +11 -11
- package/dist/local/store/node/database.js.map +1 -1
- package/dist/local/store/react-native/adapter.d.ts +6 -6
- package/dist/local/store/react-native/adapter.d.ts.map +1 -1
- package/dist/local/store/react-native/adapter.js +35 -32
- package/dist/local/store/react-native/adapter.js.map +1 -1
- package/dist/local/store/react-native/backend-conformance.d.ts +11 -10
- package/dist/local/store/react-native/backend-conformance.d.ts.map +1 -1
- package/dist/local/store/react-native/backend-conformance.js +13 -12
- package/dist/local/store/react-native/backend-conformance.js.map +1 -1
- package/dist/local/store/react-native/index.d.ts +1 -1
- package/dist/local/store/react-native/reference-backend.d.ts +14 -13
- package/dist/local/store/react-native/reference-backend.d.ts.map +1 -1
- package/dist/local/store/react-native/reference-backend.js +15 -14
- package/dist/local/store/react-native/reference-backend.js.map +1 -1
- package/dist/local/store/react-native/storage.d.ts +3 -3
- package/dist/local/store/web/adapter.d.ts +3 -3
- package/dist/local/store/web/adapter.d.ts.map +1 -1
- package/dist/local/store/web/adapter.js +30 -31
- package/dist/local/store/web/adapter.js.map +1 -1
- package/dist/local/store/web/index.d.ts +1 -1
- package/dist/local/vault/index.d.ts +2 -2
- package/dist/media/index.d.ts +11 -12
- package/dist/media/index.d.ts.map +1 -1
- package/dist/media/index.js +9 -10
- package/dist/media/index.js.map +1 -1
- package/dist/profile/contact-state.d.ts +1 -1
- package/dist/profile/contact-state.js +1 -1
- package/dist/profile/profile-key.d.ts +2 -2
- package/dist/profile/profile-key.js +7 -6
- package/dist/profile/profile-key.js.map +1 -1
- package/dist/remote/object-store/index.d.ts +1 -1
- package/dist/remote/object-store/s3/storage.d.ts +1 -1
- package/dist/remote/object-store/types.d.ts +4 -4
- package/dist/remote/object-store/types.d.ts.map +1 -1
- package/dist/remote/relay/convex/backend.d.ts +6 -6
- package/dist/remote/relay/convex/backend.d.ts.map +1 -1
- package/dist/remote/relay/convex/backend.js +4 -4
- package/dist/remote/relay/convex/backend.js.map +1 -1
- package/dist/remote/relay/convex/component/_generated/component.d.ts +2 -2
- package/dist/remote/relay/convex/component/_generated/component.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/accounts.d.ts +15 -13
- package/dist/remote/relay/convex/component/accounts.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/accounts.js +31 -28
- package/dist/remote/relay/convex/component/accounts.js.map +1 -1
- package/dist/remote/relay/convex/component/certificates.js +1 -1
- package/dist/remote/relay/convex/component/cleanup.js +7 -7
- package/dist/remote/relay/convex/component/cleanup.js.map +1 -1
- package/dist/remote/relay/convex/component/convex.config.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/convex.config.js +10 -8
- package/dist/remote/relay/convex/component/convex.config.js.map +1 -1
- package/dist/remote/relay/convex/component/devices.d.ts +21 -20
- package/dist/remote/relay/convex/component/devices.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/devices.js +24 -23
- package/dist/remote/relay/convex/component/devices.js.map +1 -1
- package/dist/remote/relay/convex/component/groups.js +6 -6
- package/dist/remote/relay/convex/component/groups.js.map +1 -1
- package/dist/remote/relay/convex/component/messages.d.ts +2 -2
- package/dist/remote/relay/convex/component/messages.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/messages.js +90 -83
- package/dist/remote/relay/convex/component/messages.js.map +1 -1
- package/dist/remote/relay/convex/component/provisioning.d.ts +3 -3
- package/dist/remote/relay/convex/component/provisioning.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/provisioning.js +17 -16
- package/dist/remote/relay/convex/component/provisioning.js.map +1 -1
- package/dist/remote/relay/convex/component/runtime.d.ts.map +1 -1
- package/dist/remote/relay/convex/component/runtime.js +4 -2
- package/dist/remote/relay/convex/component/runtime.js.map +1 -1
- package/dist/remote/relay/convex/component/schema.d.ts +2 -2
- package/dist/remote/relay/convex/component/schema.js +26 -25
- package/dist/remote/relay/convex/component/schema.js.map +1 -1
- package/dist/remote/relay/convex/group-server.d.ts +3 -3
- package/dist/remote/relay/convex/group-server.js +3 -3
- package/dist/remote/relay/convex/relay.d.ts +3 -3
- package/dist/remote/relay/convex/relay.d.ts.map +1 -1
- package/dist/remote/relay/convex/relay.js +18 -17
- package/dist/remote/relay/convex/relay.js.map +1 -1
- package/dist/remote/relay/convex/types.d.ts +7 -7
- package/dist/remote/relay/convex/types.js +4 -4
- package/dist/remote/relay/memory/adapter.js +9 -9
- package/dist/remote/relay/memory/adapter.js.map +1 -1
- package/dist/remote/relay/types.d.ts +27 -27
- package/dist/remote/relay/types.d.ts.map +1 -1
- package/dist/safety/fingerprint.d.ts +7 -6
- package/dist/safety/fingerprint.d.ts.map +1 -1
- package/dist/safety/fingerprint.js +5 -4
- package/dist/safety/fingerprint.js.map +1 -1
- package/dist/safety/index.d.ts +6 -5
- package/dist/safety/index.d.ts.map +1 -1
- package/dist/safety/index.js +7 -6
- package/dist/safety/index.js.map +1 -1
- package/dist/safety/protobuf.js +2 -2
- package/dist/safety/protobuf.js.map +1 -1
- package/dist/safety/url.d.ts +5 -5
- package/dist/safety/url.js +6 -6
- package/dist/types/address.d.ts +2 -2
- package/dist/types/address.js +2 -2
- package/dist/types/api.d.ts +78 -73
- package/dist/types/api.d.ts.map +1 -1
- package/dist/types/errors.d.ts +63 -403
- package/dist/types/errors.d.ts.map +1 -1
- package/dist/types/errors.js +62 -537
- package/dist/types/errors.js.map +1 -1
- package/dist/types/messages.d.ts +16 -16
- package/dist/types/messages.d.ts.map +1 -1
- package/dist/types/messages.js +7 -7
- package/dist/types/messages.js.map +1 -1
- package/dist/types/protocol-config.d.ts +52 -49
- package/dist/types/protocol-config.d.ts.map +1 -1
- package/dist/types/protocol-config.js +36 -34
- package/dist/types/protocol-config.js.map +1 -1
- package/dist/types/protocol-constants.d.ts +2 -2
- package/dist/types/protocol-constants.js +2 -2
- package/dist/types/session.d.ts +62 -61
- package/dist/types/session.d.ts.map +1 -1
- package/dist/types/session.js +13 -14
- package/dist/types/session.js.map +1 -1
- package/dist/types/trust.d.ts +8 -8
- package/dist/types/trust.js +3 -3
- package/dist/utils/retry.d.ts +2 -1
- package/dist/utils/retry.d.ts.map +1 -1
- package/dist/utils/retry.js +4 -5
- package/dist/utils/retry.js.map +1 -1
- package/docs/ASSURANCE.md +89 -75
- package/docs/CLIENT_COMPOSITION.md +22 -15
- package/docs/DEVIATIONS.md +507 -425
- package/docs/DOCUMENTATION_STANDARDS.md +52 -24
- package/docs/E2EE.md +45 -42
- package/docs/ERROR_HANDLING.md +107 -152
- package/docs/GETTING_STARTED.md +44 -26
- package/docs/INTERFACES.md +32 -18
- package/docs/PACKAGE_SURFACE.md +24 -21
- package/docs/PROTOCOL_POLICY.md +25 -13
- package/docs/RECIPES.md +13 -4
- package/docs/SECURITY.md +72 -60
- package/encoding/README.md +3 -2
- package/files/README.md +2 -1
- package/groups/README.md +5 -3
- package/hooks/README.md +2 -2
- package/keys/README.md +17 -14
- package/local/store/README.md +84 -67
- package/local/store/expo/README.md +19 -12
- package/local/store/memory/README.md +6 -3
- package/local/store/node/README.md +9 -6
- package/local/store/react-native/README.md +16 -12
- package/local/store/web/README.md +32 -26
- package/local/vault/README.md +5 -4
- package/media/README.md +8 -5
- package/package.json +4 -2
- package/profile/README.md +8 -7
- package/remote/README.md +26 -18
- package/remote/object-store/README.md +9 -4
- package/remote/object-store/convex-r2/README.md +5 -3
- package/remote/object-store/s3/README.md +11 -5
- package/remote/relay/README.md +2 -0
- package/remote/relay/convex/README.md +6 -5
- package/remote/relay/convex/component/README.md +154 -124
- package/remote/relay/memory/README.md +8 -5
- package/safety/README.md +2 -1
- package/sealed-sender/README.md +4 -2
- package/types/README.md +2 -1
- package/username/README.md +1 -0
- package/utils/README.md +5 -4
- package/zk/README.md +1 -0
package/docs/DEVIATIONS.md
CHANGED
|
@@ -7,47 +7,61 @@
|
|
|
7
7
|
## What compatibility means here
|
|
8
8
|
|
|
9
9
|
This SDK implements the same cryptographic core as the published Signal Protocol
|
|
10
|
-
specifications
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
10
|
+
specifications:
|
|
11
|
+
|
|
12
|
+
- X3DH/PQXDH key agreement
|
|
13
|
+
- the Double Ratchet
|
|
14
|
+
- the ML-KEM Braid post-quantum ratchet
|
|
15
|
+
- Sesame multi-device session management
|
|
16
|
+
- sealed sender
|
|
17
|
+
- the Signal Protocol's zero-knowledge group credential system
|
|
18
|
+
|
|
19
|
+
In many places it is faithful down to the byte. It uses the same KDF labels, the
|
|
20
|
+
same chain-key constants, the same protobuf field numbers, and the same
|
|
21
|
+
iteration counts.
|
|
15
22
|
|
|
16
23
|
It is **not wire-compatible with Signal Messenger or with `libsignal`**, and it
|
|
17
|
-
is not intended to be
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
24
|
+
is not intended to be:
|
|
25
|
+
|
|
26
|
+
- a Signal Messenger client cannot decrypt a message from this SDK
|
|
27
|
+
- the two systems cannot exchange identities
|
|
28
|
+
- a user cannot check a safety number from this SDK against the number Signal
|
|
29
|
+
Messenger shows
|
|
30
|
+
- neither side can migrate a session to the other
|
|
31
|
+
|
|
32
|
+
This is a distinct wire profile,
|
|
33
|
+
`IndependentProfileV1`. It shares the Signal Protocol's cryptographic design and
|
|
22
34
|
deliberately does not share its encoding.
|
|
23
35
|
|
|
24
36
|
That distinction matters in a specific way. Reading "implements X3DH and the
|
|
25
37
|
Double Ratchet" reasonably leads someone to expect interoperability. There is
|
|
26
|
-
none. Reading "safety numbers compatible with Signal Messenger"
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
38
|
+
none. Reading "safety numbers compatible with Signal Messenger" invites a second
|
|
39
|
+
expectation: that a user could verify a contact against the number Signal
|
|
40
|
+
Messenger shows. A user cannot. The two numbers come from different inputs and
|
|
41
|
+
will never match.
|
|
30
42
|
|
|
31
43
|
This document is the complete, honest account of where and why the profile
|
|
32
44
|
differs. Each entry names the implementing file, the specification section or
|
|
33
|
-
`libsignal` source it departs from, the engineering reason, and the cost.
|
|
34
|
-
deviation weakens an assurance that a reader of the specification
|
|
35
|
-
reasonably assume
|
|
45
|
+
`libsignal` source it departs from, the engineering reason, and the cost. A
|
|
46
|
+
deviation sometimes weakens an assurance that a reader of the specification
|
|
47
|
+
would reasonably assume. This document says so plainly rather than framing it as
|
|
48
|
+
a feature.
|
|
36
49
|
|
|
37
50
|
Deviations fall into three kinds:
|
|
38
51
|
|
|
39
|
-
- **Deviation
|
|
52
|
+
- **Deviation**: does something different from the specification or from
|
|
40
53
|
`libsignal`, deliberately.
|
|
41
|
-
- **Extension
|
|
42
|
-
- **Independent design
|
|
43
|
-
the SDK's own construction rather than a port of the corresponding
|
|
54
|
+
- **Extension**: adds a mechanism the specification does not describe.
|
|
55
|
+
- **Independent design**: shares a name and a goal with a Signal Protocol system.
|
|
56
|
+
It is the SDK's own construction rather than a port of the corresponding
|
|
57
|
+
`libsignal` system.
|
|
44
58
|
|
|
45
|
-
A fourth label, **faithful**, appears in the table
|
|
46
|
-
specification closely
|
|
47
|
-
|
|
59
|
+
A fourth label, **faithful**, appears in the table for an area that follows the
|
|
60
|
+
specification closely. Such a row is here only to delimit what the neighbouring
|
|
61
|
+
deviations do and do not touch.
|
|
48
62
|
|
|
49
63
|
Companion documents: [Protocol Policy](./PROTOCOL_POLICY.md) states which
|
|
50
|
-
protocol modes run and which fail closed
|
|
64
|
+
protocol modes run and which fail closed. This document states how the profile
|
|
51
65
|
differs from the specifications. [Security](./SECURITY.md) states the threat
|
|
52
66
|
model and what is out of scope.
|
|
53
67
|
|
|
@@ -84,8 +98,8 @@ model and what is out of scope.
|
|
|
84
98
|
### 1.1 Composite identity replaces the single Curve25519 key
|
|
85
99
|
|
|
86
100
|
`libsignal` represents an identity as one Curve25519 public key serialized as
|
|
87
|
-
`0x05 ‖ key
|
|
88
|
-
|
|
101
|
+
`0x05 ‖ key`, or 33 bytes ([`identity_key.rs:23-49`][ik]). One private key
|
|
102
|
+
serves both Diffie-Hellman and, via XEdDSA, signing.
|
|
89
103
|
|
|
90
104
|
This SDK stores a versioned tuple of two separate keys
|
|
91
105
|
(`keys/identity.ts:20-23`, `:66-72`):
|
|
@@ -100,12 +114,15 @@ This SDK stores a versioned tuple of two separate keys
|
|
|
100
114
|
length (`keys/identity.ts:75-96`).
|
|
101
115
|
|
|
102
116
|
**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
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
117
|
+
converting a Montgomery point to an Edwards point at signing time. It is also
|
|
118
|
+
non-standard:
|
|
119
|
+
|
|
120
|
+
- no vetted JavaScript implementation exists
|
|
121
|
+
- the conversion has sign-bit handling that is easy to get subtly wrong
|
|
122
|
+
- no general-purpose Ed25519 verifier can check the resulting signatures
|
|
123
|
+
|
|
124
|
+
An explicit Ed25519 key costs 32 bytes and one more key to manage. It buys
|
|
125
|
+
signatures that any RFC 8032 implementation can verify, and that auditors can
|
|
109
126
|
reason about without first reasoning about curve conversion.
|
|
110
127
|
|
|
111
128
|
**Cost.** Two keys to generate, store, rotate, and back up. A larger identity on
|
|
@@ -120,16 +137,17 @@ A commitment binds the tuple (`keys/identity.ts:98-100`):
|
|
|
120
137
|
SHA-256(UTF8("signal-protocol-js composite identity v1") || CompositeIdentityV1)
|
|
121
138
|
```
|
|
122
139
|
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
producer of stored identity bytes
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
single-key format has nothing
|
|
140
|
+
The SDK never trusts a commitment that arrives from a relay, cache, or caller.
|
|
141
|
+
It recomputes the commitment and compares it in constant time
|
|
142
|
+
(`keys/identity.ts:103-111`). Every producer of stored identity bytes goes
|
|
143
|
+
through a decode/re-encode round trip (`keys/identity.ts:154-161`). Two
|
|
144
|
+
encodings of the same key therefore cannot forge an identity-change event.
|
|
145
|
+
`libsignal` has no commitment concept, because a single-key format has nothing
|
|
146
|
+
to bind together.
|
|
129
147
|
|
|
130
148
|
**Not ported.** `libsignal`'s ACI↔PNI alternate-identity signature
|
|
131
149
|
([`identity_key.rs:61-70`][ik]) has no SDK equivalent. ACI and PNI are fully
|
|
132
|
-
independent identities here with independent trust histories
|
|
150
|
+
independent identities here with independent trust histories. Neither certifies
|
|
133
151
|
the other. An application that wants a user's two identities linked must
|
|
134
152
|
establish that link itself.
|
|
135
153
|
|
|
@@ -151,8 +169,8 @@ UTF8("signal-protocol-js prekey signature v1")
|
|
|
151
169
|
ML-KEM prekeys must carry their `0x0A` tag inside the signed bytes
|
|
152
170
|
(`keys/prekey-signature.ts:33-38`).
|
|
153
171
|
|
|
154
|
-
**Why.** A bare-key signature says only
|
|
155
|
-
bytes.
|
|
172
|
+
**Why.** A bare-key signature says only that the identity holder signed these 32
|
|
173
|
+
bytes. It does not say which algorithm the key is for, which key ID it occupies,
|
|
156
174
|
or which identity it belongs to. Binding all three defeats cross-algorithm
|
|
157
175
|
substitution (presenting an X25519 signature as an ML-KEM one) and cross-key-ID
|
|
158
176
|
substitution. This is strictly stronger than the specification requires.
|
|
@@ -166,21 +184,21 @@ messages (§7.2).
|
|
|
166
184
|
|
|
167
185
|
XEdDSA and VXEdDSA are not implemented, not stubbed, and not claimed anywhere in
|
|
168
186
|
this codebase. Where the frozen upstream specification snapshots mention them,
|
|
169
|
-
that is upstream text
|
|
170
|
-
ordinary Ed25519
|
|
187
|
+
that is upstream text. The SDK's own documentation consistently states that it
|
|
188
|
+
uses ordinary Ed25519 instead.
|
|
171
189
|
|
|
172
190
|
### 1.3 Safety numbers are not comparable to Signal Messenger's
|
|
173
191
|
|
|
174
|
-
State this without hedging
|
|
175
|
-
|
|
192
|
+
State this without hedging. A safety number from this SDK **will never match**
|
|
193
|
+
the safety number Signal Messenger shows for the same two users. A user cannot
|
|
176
194
|
verify a contact by reading a number out of one application and comparing it
|
|
177
195
|
against the other.
|
|
178
196
|
|
|
179
197
|
Three independent reasons, any one of which is sufficient.
|
|
180
198
|
|
|
181
|
-
**The user-facing number
|
|
182
|
-
`client.verify()` uses `generateCompositeSafetyNumber`
|
|
183
|
-
(`client/sessions.ts:326`, `:432-433`)
|
|
199
|
+
**The SDK computes the user-facing number over a composite commitment.**
|
|
200
|
+
The `client.verify()` method uses `generateCompositeSafetyNumber`
|
|
201
|
+
(`client/sessions.ts:326`, `:432-433`). Its per-party hash iterates over
|
|
184
202
|
`UTF8("signal-protocol-js composite safety number v1") ‖ type-tagged user ID ‖
|
|
185
203
|
SHA-256 identity commitment` (`safety/core.ts:48-50`, `:205-233`). None of that
|
|
186
204
|
input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
|
|
@@ -188,60 +206,65 @@ input exists in `libsignal`'s construction ([`fingerprint.rs:161-192`][fp]).
|
|
|
188
206
|
**The identity material differs.** Even the raw input is a 67-byte two-key tuple
|
|
189
207
|
rather than a 33-byte `0x05 ‖ X25519` key.
|
|
190
208
|
|
|
191
|
-
**
|
|
209
|
+
**A different rule orders the two halves.** This one applies even on the
|
|
192
210
|
SDK's low-level single-key path, which is otherwise byte-identical to
|
|
193
|
-
`libsignal`. The SDK orders by user identifier
|
|
194
|
-
(`safety/core.ts:177`)
|
|
195
|
-
themselves ([`fingerprint.rs:32-40`][fp]). Both rules
|
|
196
|
-
parties always agree with each other
|
|
197
|
-
roughly half the time the halves come out in
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
211
|
+
`libsignal`. The SDK orders by user identifier,
|
|
212
|
+
`localId.localeCompare(remoteId)` (`safety/core.ts:177`). `libsignal` orders by
|
|
213
|
+
the encoded digit strings themselves ([`fingerprint.rs:32-40`][fp]). Both rules
|
|
214
|
+
are symmetric, so the two parties always agree with each other. They do not
|
|
215
|
+
agree with Signal Messenger, and roughly half the time the halves come out in
|
|
216
|
+
the opposite order.
|
|
217
|
+
|
|
218
|
+
`localeCompare` is also locale-sensitive. Two devices with different default
|
|
219
|
+
locales can in principle disagree on how to order the same pair of user IDs.
|
|
220
|
+
|
|
221
|
+
Other parts *are* faithful. The iteration is byte-for-byte `libsignal`'s: 5200
|
|
203
222
|
iterations of SHA-512 over `0x0000 ‖ key ‖ id`, then `hash ‖ key`
|
|
204
|
-
(`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp])
|
|
205
|
-
encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party)
|
|
206
|
-
scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
|
|
223
|
+
(`safety/core.ts:138-143` vs [`fingerprint.rs:170-189`][fp]). So is the digit
|
|
224
|
+
encoding (six 5-byte big-endian chunks mod 100000, 30 digits per party). So is
|
|
225
|
+
the scannable-fingerprint protobuf layout (`safety/protobuf.ts:94-109`). The
|
|
207
226
|
cross-verification swap and constant-time comparison match as well.
|
|
208
227
|
|
|
209
228
|
The QR format version is the SDK's own: `3` for the composite path
|
|
210
229
|
(`safety/core.ts:46`), where `libsignal` knows only versions 1 and 2 and returns
|
|
211
|
-
`VersionMismatch` for anything else.
|
|
212
|
-
|
|
230
|
+
`VersionMismatch` for anything else. A distinct version in the same protobuf
|
|
231
|
+
namespace is the correct fail-closed choice. A Signal Messenger client rejects
|
|
213
232
|
the code rather than misreading it.
|
|
214
233
|
|
|
215
234
|
The SDK also offers an emoji fingerprint (`safety/core.ts:308-392`) and
|
|
216
235
|
verification deep links (`safety/url.ts`). Both are extensions with no
|
|
217
|
-
`libsignal` counterpart.
|
|
218
|
-
|
|
219
|
-
|
|
236
|
+
`libsignal` counterpart. The emoji form derives from one party's fingerprint
|
|
237
|
+
only. It therefore encodes roughly half of what the 60-digit number encodes.
|
|
238
|
+
Do not present it to users as an equal-strength alternative.
|
|
220
239
|
|
|
221
240
|
### 1.4 Registration ID range
|
|
222
241
|
|
|
223
|
-
|
|
242
|
+
The SDK generates registration IDs in the closed range `[1, 16383]`
|
|
224
243
|
(`keys/generation.ts:43-46`). The wire format reserves exactly 14 bits, and
|
|
225
244
|
`libsignal` rejects any ID where `id & 0x3FFF != id`
|
|
226
|
-
([`sealed_sender.rs:1508-1515`][ss])
|
|
245
|
+
([`sealed_sender.rs:1508-1515`][ss]). Its own helper generates `[1, 16380]`.
|
|
227
246
|
|
|
228
|
-
The upper bound is load-bearing rather than cosmetic. `16384` is
|
|
229
|
-
does not fit in 14 bits
|
|
230
|
-
masks rather than rejects
|
|
247
|
+
The upper bound is load-bearing rather than cosmetic. The value `16384` is
|
|
248
|
+
`0x4000` and does not fit in 14 bits. The SDK's multi-recipient sealed-sender
|
|
249
|
+
encoder masks rather than rejects
|
|
231
250
|
(`internal/protocol/sealed-sender/v2-binary.ts:170-171`), so an ID one above
|
|
232
|
-
the range would reach the wire as `0`. The generated range is therefore
|
|
233
|
-
|
|
251
|
+
the range would reach the wire as `0`. The generated range is therefore strictly
|
|
252
|
+
narrower than `libsignal`'s accepted range, and a test asserts that every
|
|
234
253
|
generated ID survives the mask unchanged.
|
|
235
254
|
|
|
236
255
|
---
|
|
237
256
|
|
|
238
257
|
## 2. X3DH and PQXDH
|
|
239
258
|
|
|
240
|
-
The key agreement is the most faithful area in the codebase.
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
`
|
|
259
|
+
The key agreement is the most faithful area in the codebase. These all match
|
|
260
|
+
`libsignal` exactly:
|
|
261
|
+
|
|
262
|
+
- the DH computation order
|
|
263
|
+
- the 32-byte `0xFF` discontinuity prefix
|
|
264
|
+
- the zero-filled HKDF salt
|
|
265
|
+
- the single-step derivation over the full concatenation
|
|
266
|
+
- the KEM shared secret appended last
|
|
267
|
+
- the 96-byte output split
|
|
245
268
|
|
|
246
269
|
- Initiator DH order `DH(IK_A,SPK_B)`, `DH(EK_A,IK_B)`, `DH(EK_A,SPK_B)`,
|
|
247
270
|
`DH(EK_A,OPK_B)`: `internal/protocol/pqxdh/pqxdh.ts:243-264` vs
|
|
@@ -252,18 +275,19 @@ shared secret (appended last), and the 96-byte output split all match
|
|
|
252
275
|
`internal/protocol/pqxdh/pqxdh.ts:365-374` vs [`pqxdh.rs:226-230`][pq]. Spec
|
|
253
276
|
PQXDH §3.3.
|
|
254
277
|
|
|
255
|
-
Two hardening extensions go beyond the specification at no interop cost:
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
278
|
+
Two hardening extensions go beyond the specification at no interop cost:
|
|
279
|
+
|
|
280
|
+
- the SDK validates every remote X25519 point before it computes any DH
|
|
281
|
+
(`internal/protocol/pqxdh/pqxdh.ts:219-227`)
|
|
282
|
+
- the SDK validates prekey bundles far more strictly than `libsignal` requires
|
|
283
|
+
(`internal/session/handshake.ts:107-138`)
|
|
260
284
|
|
|
261
285
|
### 2.1 The info strings name this application and this KEM
|
|
262
286
|
|
|
263
287
|
The SDK uses ML-KEM-1024 (FIPS 203) where `libsignal` uses round-3 Kyber1024,
|
|
264
288
|
tagged `0x0A` rather than `0x08` (`internal/crypto/pq/kyber.ts:79`). That much is
|
|
265
|
-
deliberate
|
|
266
|
-
single unambiguous tag
|
|
289
|
+
deliberate. The SDK prefers the standardized algorithm over the round-3 draft,
|
|
290
|
+
and a single unambiguous tag over a legacy fallback.
|
|
267
291
|
|
|
268
292
|
The info strings are the SDK's own (`types/protocol-config.ts:363-386`):
|
|
269
293
|
|
|
@@ -272,29 +296,28 @@ OpenE2EE_X25519_SHA-256_ML-KEM-1024 (PQXDH)
|
|
|
272
296
|
OpenE2EE (X3DH)
|
|
273
297
|
```
|
|
274
298
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
nothing appended.
|
|
299
|
+
The SDK sets both implementer-chosen parameters to name itself and the KEM it
|
|
300
|
+
runs. PQXDH §2.2 defines the info string as `info`, `curve`, `hash`, and `pqkem`
|
|
301
|
+
joined by `_`, with each representation implementer-chosen. PQXDH §2.1 defines
|
|
302
|
+
`info` as an application identifier of at least 8 bytes. X3DH §2.1 defines the
|
|
303
|
+
same `info` parameter, and §3.3 uses it as the HKDF info with nothing appended.
|
|
281
304
|
|
|
282
|
-
The SDK does not use `libsignal`'s labels
|
|
305
|
+
The SDK does not use `libsignal`'s labels, `WhisperText` and
|
|
283
306
|
`WhisperText_X25519_SHA-256_CRYSTALS-KYBER-1024` ([`pqxdh.rs:73-74`][pq]).
|
|
284
307
|
Inheriting them would be wrong on both parameters:
|
|
285
308
|
|
|
286
309
|
1. **`pqkem` would name a KEM the SDK does not run**, violating §2.2. That is
|
|
287
|
-
worse than a labelling error
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
310
|
+
worse than a labelling error. Two implementations feeding an identical label
|
|
311
|
+
derive *different* shared secrets. The KEM underneath differs, and nothing at
|
|
312
|
+
the KDF layer signals it. Domain separation is the one job the info string
|
|
313
|
+
has.
|
|
291
314
|
2. **`info` would name someone else's application.** The specifications ask
|
|
292
315
|
for an identifier of the application deriving the key. This SDK is not
|
|
293
316
|
Signal Messenger.
|
|
294
317
|
|
|
295
318
|
Choosing the SDK's own labels is a pre-1.0 format break against sessions
|
|
296
|
-
established under `libsignal`'s
|
|
297
|
-
|
|
319
|
+
established under `libsignal`'s. Those sessions derive a different `SK`, and
|
|
320
|
+
neither side can continue them. Nothing else about the derivation changes.
|
|
298
321
|
|
|
299
322
|
An application that needs `libsignal`'s known-answer vectors can still get them
|
|
300
323
|
by setting `protocolStrategy.keyExchangeInfoString` to the old label
|
|
@@ -319,50 +342,51 @@ HMAC-SHA256(mac_key,
|
|
|
319
342
|
```
|
|
320
343
|
|
|
321
344
|
**Why.** With a two-key identity, an `AD` over the DH key alone would leave the
|
|
322
|
-
Ed25519 signing component unbound
|
|
323
|
-
|
|
345
|
+
Ed25519 signing component unbound. That component authenticates every prekey the
|
|
346
|
+
peer will ever publish. Hashing the commitment covers both.
|
|
324
347
|
|
|
325
348
|
**Cost.** This is the single largest wire deviation in the message path. The
|
|
326
|
-
truncation to 8 bytes matches `libsignal`'s convention, and the construction is
|
|
327
|
-
and domain-separated,
|
|
328
|
-
message.
|
|
349
|
+
truncation to 8 bytes matches `libsignal`'s convention, and the construction is
|
|
350
|
+
sound and domain-separated. Even so, a Signal Messenger client and this SDK
|
|
351
|
+
cannot exchange a single message.
|
|
329
352
|
|
|
330
|
-
### 2.3
|
|
353
|
+
### 2.3 The SDK defers one-time prekey deletion
|
|
331
354
|
|
|
332
355
|
PQXDH §3.4 has Bob delete a used one-time prekey after successful decryption. The
|
|
333
356
|
SDK records a pending deletion (`internal/manager/manager.ts:940-952`) and
|
|
334
357
|
commits it only once a prekey message decrypts
|
|
335
|
-
(`internal/session/cipher.ts:1189-1200`). This is compliant in letter
|
|
336
|
-
the window in which the same first ciphertext
|
|
337
|
-
|
|
338
|
-
(`internal/session/cipher.ts:1519-1527`).
|
|
358
|
+
(`internal/session/cipher.ts:1189-1200`). This is compliant in letter. It also
|
|
359
|
+
widens the window in which an attacker can replay the same first ciphertext
|
|
360
|
+
before commit. The SDK refuses auto-recovery for duplicate and missing-prekey
|
|
361
|
+
conditions (`internal/session/cipher.ts:1519-1527`).
|
|
339
362
|
|
|
340
363
|
### 2.4 Ratchet initialization details
|
|
341
364
|
|
|
342
365
|
Two differences at the boundary between key agreement and the ratchet:
|
|
343
366
|
|
|
344
367
|
**Alice reuses her key-agreement ephemeral as her first ratchet key**
|
|
345
|
-
(`internal/session/builder.ts:159-171`). `libsignal` generates a
|
|
346
|
-
ratchet key distinct from the handshake ephemeral
|
|
347
|
-
the prekey message's base key and the
|
|
348
|
-
they are the same value. No
|
|
349
|
-
separation and it is
|
|
368
|
+
(`internal/session/builder.ts:159-171`). By contrast, `libsignal` generates a
|
|
369
|
+
fresh sending ratchet key, distinct from the handshake ephemeral
|
|
370
|
+
([`ratchet.rs:77-81`][rat]). In `libsignal` the prekey message's base key and the
|
|
371
|
+
first message's ratchet key therefore differ. Here they are the same value. No
|
|
372
|
+
concrete attack follows, but the reuse weakens key separation and it is
|
|
373
|
+
wire-visible.
|
|
350
374
|
|
|
351
375
|
**Bob initializes without a sending chain** (`internal/session/builder.ts:326-364`),
|
|
352
376
|
deriving chains on the first DH ratchet, where `libsignal` seeds a sending chain
|
|
353
377
|
immediately ([`ratchet.rs:137-172`][rat]). A side effect is that bytes 32–64 of
|
|
354
|
-
the 96-byte derivation
|
|
355
|
-
either side. The 96-byte split
|
|
356
|
-
root key and the SPQR key are load-bearing.
|
|
378
|
+
the 96-byte derivation, the initial chain key, never produce a message key on
|
|
379
|
+
either side. The SDK keeps the 96-byte split for shape compatibility, but only
|
|
380
|
+
the root key and the SPQR key are load-bearing.
|
|
357
381
|
|
|
358
|
-
### 2.5
|
|
382
|
+
### 2.5 The SDK keeps a gated classical fallback
|
|
359
383
|
|
|
360
|
-
`libsignal`
|
|
384
|
+
`libsignal` removed X3DH entirely and rejects pre-Kyber prekey messages
|
|
361
385
|
([`session.rs:105-112`][sess]). The SDK keeps the X3DH path reachable only via an
|
|
362
|
-
explicit opt-in
|
|
386
|
+
explicit opt-in. The default is fail-closed, and any PQXDH failure raises rather
|
|
363
387
|
than silently downgrading (`internal/session/handshake.ts:167-260`). This is a
|
|
364
|
-
downgrade surface that `libsignal`
|
|
365
|
-
[Protocol Policy](./PROTOCOL_POLICY.md).
|
|
388
|
+
downgrade surface that `libsignal` closed.
|
|
389
|
+
[Protocol Policy](./PROTOCOL_POLICY.md) documents it.
|
|
366
390
|
|
|
367
391
|
---
|
|
368
392
|
|
|
@@ -370,19 +394,24 @@ downgrade surface that `libsignal` has closed, and it is documented in
|
|
|
370
394
|
|
|
371
395
|
### 3.1 The ratchet core is faithful
|
|
372
396
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
`
|
|
376
|
-
|
|
377
|
-
`
|
|
378
|
-
(`internal/crypto/kdf/hkdf.ts:
|
|
379
|
-
|
|
380
|
-
`
|
|
397
|
+
These parts are byte-for-byte with `libsignal`:
|
|
398
|
+
|
|
399
|
+
- the `0x01`/`0x02` chain-key seeds (`internal/crypto/kdf/hkdf.ts:183-195` vs
|
|
400
|
+
[`keys.rs:148-149`][rk])
|
|
401
|
+
- the `WhisperMessageKeys` expansion to 80 bytes split 32/32/16
|
|
402
|
+
(`internal/crypto/kdf/hkdf.ts:215-243` vs [`keys.rs:100-118`][rk])
|
|
403
|
+
- the `WhisperRatchet` root-key step producing a 64-byte split
|
|
404
|
+
(`internal/crypto/kdf/hkdf.ts:141-161` vs [`keys.rs:199-218`][rk])
|
|
405
|
+
- the DH ratchet half-step ordering
|
|
406
|
+
- `MAX_RECEIVER_CHAINS = 5`
|
|
407
|
+
- AES-256-CBC with PKCS#7
|
|
408
|
+
- the `0x44` version byte
|
|
409
|
+
- 8-byte MAC truncation
|
|
381
410
|
|
|
382
411
|
Message framing matches too: `[version byte] ‖ protobuf ‖ [8-byte HMAC]` for
|
|
383
412
|
messages and `[version byte] ‖ protobuf` for prekey messages
|
|
384
413
|
(`internal/encoding/proto/envelope.ts:104-168`). What goes *into* the MAC does
|
|
385
|
-
not
|
|
414
|
+
not. See §2.2.
|
|
386
415
|
|
|
387
416
|
Protobuf fields 1–8 match [`wire.proto`][wp] exactly, including `libsignal`'s
|
|
388
417
|
non-obvious ordering where `registrationId` is field 5 and `signedPreKeyId` is
|
|
@@ -394,93 +423,97 @@ field 6.
|
|
|
394
423
|
have: `recipientIdentityType` on both message types, and `kemOneTimePreKeyId` /
|
|
395
424
|
`kemOneTimeCiphertext` on prekey messages
|
|
396
425
|
(`internal/encoding/proto/signal-message.ts:80`, `:226-228`). High numbering
|
|
397
|
-
avoids collision with future upstream fields. A Signal Messenger client
|
|
398
|
-
message and
|
|
426
|
+
avoids collision with future upstream fields. A Signal Messenger client parses
|
|
427
|
+
the message and ignores the added fields, which loses the identity-type
|
|
428
|
+
binding.
|
|
399
429
|
|
|
400
430
|
**Deviation.** `libsignal` binds addresses as a 17-byte fixed-width ServiceId plus
|
|
401
431
|
a 1-byte device ID ([`protocol.rs:246-260`][proto]). The SDK binds a
|
|
402
432
|
format-version byte, a varint-length-prefixed UTF-8 user ID, and a 4-byte
|
|
403
433
|
big-endian device ID (`internal/encoding/proto/signal-message.ts:84-92`). The
|
|
404
434
|
encoding is unambiguous, but it authenticates an application-defined identifier
|
|
405
|
-
rather than a Signal Messenger ACI or PNI
|
|
406
|
-
and an incompatible thing to put on the wire.
|
|
435
|
+
rather than a Signal Messenger ACI or PNI. That is the correct thing for this SDK
|
|
436
|
+
to bind, and an incompatible thing to put on the wire.
|
|
407
437
|
|
|
408
|
-
The SDK is also stricter than `libsignal` on decode
|
|
409
|
-
`libsignal` treats as optional for backward compatibility and
|
|
410
|
-
lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`).
|
|
411
|
-
and one more reason the formats cannot meet.
|
|
438
|
+
The SDK is also stricter than `libsignal` on decode. It requires fields that
|
|
439
|
+
`libsignal` treats as optional for backward compatibility, and it enforces exact
|
|
440
|
+
lengths (`internal/encoding/proto/signal-message.ts:332-340`, `:488-505`). This
|
|
441
|
+
is safer, and it is one more reason the formats cannot meet.
|
|
412
442
|
|
|
413
|
-
### 3.3 Skipped-key retention is
|
|
443
|
+
### 3.3 Skipped-key retention is much tighter than in libsignal
|
|
414
444
|
|
|
415
|
-
The constants match
|
|
416
|
-
(`internal/protocol/double-ratchet/ratchet.ts:194-227` vs
|
|
417
|
-
|
|
445
|
+
The constants match: `MAX_MESSAGE_KEYS = 2000` and `MAX_FORWARD_JUMPS = 25000`
|
|
446
|
+
(`internal/protocol/double-ratchet/ratchet.ts:194-227` vs
|
|
447
|
+
[`consts.rs:8-9`][consts]). The two implementations apply them differently, and
|
|
448
|
+
the difference is user-visible.
|
|
418
449
|
|
|
419
450
|
**The cap is global, not per-chain.** `libsignal` applies 2000 to each chain's key
|
|
420
|
-
vector ([`double_ratchet.rs:349-361`][dr])
|
|
421
|
-
system capacity
|
|
451
|
+
vector ([`double_ratchet.rs:349-361`][dr]). Five receiver chains therefore give a
|
|
452
|
+
true system capacity of 10,000 skipped keys. The SDK counts across all chains and
|
|
422
453
|
evicts when the total reaches 2000
|
|
423
454
|
(`internal/protocol/double-ratchet/chains.ts:478-513`). The effective capacity is
|
|
424
|
-
5× smaller, and traffic on a newer chain can evict keys
|
|
455
|
+
5× smaller, and traffic on a newer chain can evict keys that belong to an older
|
|
456
|
+
one.
|
|
425
457
|
|
|
426
|
-
**
|
|
427
|
-
entry (`internal/protocol/double-ratchet/chains.ts:414-463`)
|
|
428
|
-
evicts strictly by insertion position. `Date.now()` is not monotonic,
|
|
429
|
-
|
|
458
|
+
**Wall-clock timestamps drive eviction.** The SDK scans every chain for the
|
|
459
|
+
oldest entry (`internal/protocol/double-ratchet/chains.ts:414-463`). By contrast,
|
|
460
|
+
`libsignal` evicts strictly by insertion position. `Date.now()` is not monotonic,
|
|
461
|
+
so a clock adjustment makes the eviction order non-deterministic.
|
|
430
462
|
|
|
431
463
|
**Skipped keys expire after 7 days**
|
|
432
464
|
(`internal/protocol/double-ratchet/ratchet.ts:197`). `libsignal` has no
|
|
433
465
|
time-based expiry for message keys at all.
|
|
434
466
|
|
|
435
|
-
Taken together
|
|
436
|
-
undecryptable message and `libsignal`
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
storage hygiene
|
|
467
|
+
Taken together, these three differences create **message-delivery patterns where
|
|
468
|
+
this SDK reports an undecryptable message and `libsignal` decrypts it**. Two
|
|
469
|
+
recipients can lose messages that the specification's own limits keep. The first
|
|
470
|
+
is offline for more than a week. The second takes heavy traffic on a new chain
|
|
471
|
+
while older-chain messages are still in flight. The bounds are defensible as
|
|
472
|
+
storage hygiene. The consequence should not be a surprise.
|
|
441
473
|
|
|
442
|
-
Two related extensions
|
|
443
|
-
key from
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
(`internal/session/validation.ts:453-461`)
|
|
474
|
+
Two related extensions go with this. A `processedChains` map rejects messages
|
|
475
|
+
that bear a ratchet key from a retired chain
|
|
476
|
+
(`internal/protocol/double-ratchet/ratchet.ts:141-153`), which closes a replay gap
|
|
477
|
+
that `libsignal` handles only through its five-chain window. Self-sessions get a
|
|
478
|
+
finite 100,000-message skip limit (`internal/session/validation.ts:453-461`)
|
|
479
|
+
where `libsignal` uses `usize::MAX`.
|
|
447
480
|
|
|
448
481
|
### 3.4 Session archiving and serialization
|
|
449
482
|
|
|
450
|
-
The cap matches
|
|
483
|
+
The cap matches: 40 archived states, [`consts.rs:11`][consts]. The structure
|
|
451
484
|
differs. `libsignal` keeps an ordered list with strict insertion-order eviction
|
|
452
|
-
([`session.rs:787-830`][st])
|
|
485
|
+
([`session.rs:787-830`][st]). The SDK keeps a map keyed by base key and trims by
|
|
453
486
|
`lastUsedAt` (`types/session.ts:815-847`). Archiving a session whose base key
|
|
454
487
|
already exists overwrites rather than appends, so the effective history can be
|
|
455
488
|
shorter than 40.
|
|
456
489
|
|
|
457
|
-
`libsignal` clears unacknowledged prekey state before archiving a session
|
|
458
|
-
does not. Retired sessions therefore keep pending prekey references alive in
|
|
490
|
+
`libsignal` clears unacknowledged prekey state before archiving a session. The
|
|
491
|
+
SDK does not. Retired sessions therefore keep pending prekey references alive in
|
|
459
492
|
storage.
|
|
460
493
|
|
|
461
494
|
**Session records serialize as JSON, not protobuf** (`types/session.ts:1002-1028`).
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
495
|
+
The source states this as a simplicity and debuggability choice. Two consequences
|
|
496
|
+
are worth naming. No Signal Messenger client can read or write these stored
|
|
497
|
+
sessions. Key material also sits in immutable JavaScript strings that nothing can
|
|
498
|
+
zero, where `libsignal` can zero its byte vectors.
|
|
466
499
|
|
|
467
500
|
### 3.5 Padding
|
|
468
501
|
|
|
469
|
-
**Extension.**
|
|
470
|
-
padding
|
|
502
|
+
**Extension.** The SDK pads message plaintext to 160-byte buckets with ISO 7816-4
|
|
503
|
+
bit padding, which is a `0x80` terminator followed by zeros
|
|
471
504
|
(`internal/crypto/symmetric/padding.ts:19-60`). Unpadding scans backwards and
|
|
472
|
-
rejects malformed padding with a deliberately generic error
|
|
473
|
-
oracle.
|
|
505
|
+
rejects malformed padding with a deliberately generic error, which avoids a
|
|
506
|
+
padding oracle.
|
|
474
507
|
|
|
475
|
-
`libsignal` does not bucket-pad at this layer
|
|
476
|
-
applications.
|
|
477
|
-
|
|
508
|
+
`libsignal` does not bucket-pad at this layer. In Signal Messenger, that step
|
|
509
|
+
lives in the client applications. Padding in the library turns length hiding on
|
|
510
|
+
by default, instead of leaving it for each integrator to remember.
|
|
478
511
|
|
|
479
|
-
One imprecision
|
|
480
|
-
AES-CBC then applies PKCS#7, a full block
|
|
481
|
-
produces 160 padded bytes and 176 ciphertext bytes. Length is still
|
|
482
|
-
160-byte steps, so the hiding property holds
|
|
483
|
-
past each boundary rather than on it.
|
|
512
|
+
One imprecision follows. The padded plaintext is an exact multiple of 160, and
|
|
513
|
+
AES-CBC then applies PKCS#7, so every message gets a full extra block. A 5-byte
|
|
514
|
+
message produces 160 padded bytes and 176 ciphertext bytes. Length is still
|
|
515
|
+
quantized in 160-byte steps, so the hiding property holds. The ciphertext simply
|
|
516
|
+
sits 16 bytes past each boundary rather than on it.
|
|
484
517
|
|
|
485
518
|
---
|
|
486
519
|
|
|
@@ -496,8 +529,8 @@ independently and pinned against commit `fd32048`, which upstream tags
|
|
|
496
529
|
"Signal_PQCKA_V1_MLKEM768"` and the `:ekheader` / `:ciphertext` MAC inputs
|
|
497
530
|
(`internal/protocol/spqr/ml-kem-braid/kdf.ts:32-92`).
|
|
498
531
|
- **The Reed–Solomon erasure layer matches**: GF(2^16) with primitive polynomial
|
|
499
|
-
`0x1100b
|
|
500
|
-
|
|
532
|
+
`0x1100b`. Chunks are 32 bytes, with 16 polynomials and degree bound 35.
|
|
533
|
+
Reed–Solomon comes from `libsignal`. It is not an SDK addition.
|
|
501
534
|
- **The production wire framing is byte-compatible**:
|
|
502
535
|
`VERSION ‖ LEB128(epoch) ‖ LEB128(chain_index) ‖ MSG_TYPE ‖ [LEB128(chunk_index) ‖ CHUNK]`
|
|
503
536
|
(`internal/encoding/proto/pq-ratchet-serialize.ts`), matching `libsignal`'s
|
|
@@ -526,8 +559,8 @@ One divergence breaks interoperability completely. The SDK computes
|
|
|
526
559
|
hek = SHA3-256(ek_seed || ek_vector)
|
|
527
560
|
```
|
|
528
561
|
|
|
529
|
-
`libsignal`,
|
|
530
|
-
|
|
562
|
+
`libsignal`, through libcrux, builds the encapsulation key as `t̂ ‖ ρ` before
|
|
563
|
+
hashing. That is the reverse order.
|
|
531
564
|
|
|
532
565
|
The SDK follows the **normative text of the published ML-KEM Braid
|
|
533
566
|
specification**, which states seed-first ordering. `libsignal` follows FIPS 203,
|
|
@@ -535,21 +568,28 @@ which serializes vector-first. The specification and the reference implementatio
|
|
|
535
568
|
disagree, and the SDK chose the specification.
|
|
536
569
|
|
|
537
570
|
The value feeds the Fujisaki–Okamoto transform, so the consequences cascade:
|
|
538
|
-
|
|
539
|
-
different
|
|
540
|
-
|
|
541
|
-
|
|
571
|
+
|
|
572
|
+
- different header bytes, so `libsignal`'s header validation rejects the SDK's
|
|
573
|
+
output
|
|
574
|
+
- a different ciphertext
|
|
575
|
+
- a different shared secret
|
|
576
|
+
- a different epoch secret
|
|
577
|
+
- a different authenticator ratchet
|
|
578
|
+
|
|
579
|
+
**A braid session between this SDK and Signal Messenger's implementation cannot
|
|
580
|
+
complete a single epoch.**
|
|
542
581
|
|
|
543
582
|
Two further consequences a reader should not have to infer:
|
|
544
583
|
|
|
545
584
|
- **In braid mode the KEM is not FIPS 203 ML-KEM-768.** It is ML-KEM-768 with a
|
|
546
|
-
modified `hek` derivation. The
|
|
547
|
-
|
|
548
|
-
hold for this path. Direct (non-braid) mode uses stock
|
|
549
|
-
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
585
|
+
modified `hek` derivation. The change does not weaken the security argument,
|
|
586
|
+
because the hash input permutes the same material. A FIPS conformance claim
|
|
587
|
+
still does not hold for this path. Direct (non-braid) mode uses stock
|
|
588
|
+
ML-KEM-768.
|
|
589
|
+
- Elsewhere the SDK resolves the same spec-versus-code conflict in the *opposite*
|
|
590
|
+
direction. For `KDF_AUTH` it follows the `libsignal` Rust reference rather than
|
|
591
|
+
the written specification. Each choice is defensible on its own. Together they
|
|
592
|
+
are inconsistent about which artifact is authoritative.
|
|
553
593
|
|
|
554
594
|
The operand order is part of the public compatibility boundary stated in
|
|
555
595
|
[Protocol Policy](./PROTOCOL_POLICY.md). Changing it later would invalidate every
|
|
@@ -559,9 +599,10 @@ braid session persisted under the former ordering.
|
|
|
559
599
|
|
|
560
600
|
**Extension.** An opt-in direct mode (`protocol.braid: 'disabled'`) uses stock
|
|
561
601
|
ML-KEM-768 and adds wire message types `0x80`–`0x82`
|
|
562
|
-
(`internal/encoding/proto/pq-ratchet-serialize.ts:40-45`). `libsignal`'s parser
|
|
563
|
-
anything above `6`, so these are visible only within the SDK
|
|
564
|
-
range `libsignal` has not claimed. This mode has no Signal Protocol
|
|
602
|
+
(`internal/encoding/proto/pq-ratchet-serialize.ts:40-45`). `libsignal`'s parser
|
|
603
|
+
rejects anything above `6`, so these types are visible only within the SDK. They
|
|
604
|
+
occupy a byte range `libsignal` has not claimed. This mode has no Signal Protocol
|
|
605
|
+
analogue.
|
|
565
606
|
|
|
566
607
|
**Independent design.** Persisted SPQR state uses a flat message with 20 fields
|
|
567
608
|
where `libsignal` uses an 11-variant `oneof` over nested structures. Serialized SPQR
|
|
@@ -569,8 +610,8 @@ state is not portable in either direction.
|
|
|
569
610
|
|
|
570
611
|
**Deviation.** Skipped-key eviction in the SPQR chain triggers at the cap and
|
|
571
612
|
evicts by wall-clock timestamp, where `libsignal` triggers at `max_ooo × 11/10 + 1` and
|
|
572
|
-
evicts by message index. `libsignal`'s rule is deterministic and index-anchored
|
|
573
|
-
SDK's
|
|
613
|
+
evicts by message index. `libsignal`'s rule is deterministic and index-anchored.
|
|
614
|
+
The SDK's rule puts a clock dependency into ratchet state.
|
|
574
615
|
|
|
575
616
|
**Deviation.** The varint decoder is the stricter of the two. It rejects any
|
|
576
617
|
value above `uint64` (`internal/encoding/proto/pq-ratchet-serialize.ts:163-186`).
|
|
@@ -605,104 +646,113 @@ format, so this entry records the divergence rather than repairing it.
|
|
|
605
646
|
|
|
606
647
|
### 4.3 The Triple Ratchet is faithful
|
|
607
648
|
|
|
608
|
-
The post-quantum secret enters as the HKDF **salt** at message-key expansion
|
|
609
|
-
|
|
610
|
-
(`internal/session/cipher.ts:453-510`)
|
|
611
|
-
|
|
612
|
-
implementation.
|
|
649
|
+
The post-quantum secret enters as the HKDF **salt** at message-key expansion. The
|
|
650
|
+
classical message key is the IKM, and the label is `WhisperMessageKeys`
|
|
651
|
+
(`internal/session/cipher.ts:453-510`). [`triple_ratchet.rs`][tr] uses the same
|
|
652
|
+
combination order and the same label. Neither implementation braids the root key.
|
|
613
653
|
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
654
|
+
`internal/protocol/triple-ratchet/` holds a second, unused hybrid KDF under the
|
|
655
|
+
label `'Signal Triple Ratchet V1'`. The barrel exports it, but the message path
|
|
656
|
+
never calls it, and it does not match what the SDK puts on the wire. The PR that
|
|
657
|
+
accompanied this file records it as cleanup work.
|
|
618
658
|
|
|
619
659
|
---
|
|
620
660
|
|
|
621
661
|
## 5. Sesame
|
|
622
662
|
|
|
623
|
-
Sesame has no reference implementation to compare against
|
|
624
|
-
implement it
|
|
625
|
-
clients.
|
|
626
|
-
(revision 2) alone.
|
|
663
|
+
Sesame has no reference implementation to compare against. `libsignal` does not
|
|
664
|
+
implement it. Device and session management lives in the Signal Messenger service
|
|
665
|
+
and its clients. This section therefore measures the SDK against the pinned
|
|
666
|
+
specification text (revision 2) alone.
|
|
667
|
+
|
|
668
|
+
These parts are faithful:
|
|
669
|
+
|
|
670
|
+
- the user-record and device-record structure (§3.1)
|
|
671
|
+
- the per-device session fan-out on send, including the sender's own other
|
|
672
|
+
devices (§3.3)
|
|
673
|
+
- the bounded send loop (§3.3, §6.5)
|
|
674
|
+
- discarding all changes transactionally on error (§3.3, §3.4, §6.7)
|
|
675
|
+
- creating a session on receive only from an initiating message (§3.4)
|
|
627
676
|
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
bounded send loop (§3.3, §6.5), discard-all-changes-on-error handled
|
|
631
|
-
transactionally (§3.3, §3.4, §6.7), and creating a session on receive only from an
|
|
632
|
-
initiating message (§3.4). The per-user identity model is one of the two the
|
|
633
|
-
specification explicitly permits (§3.1).
|
|
677
|
+
The per-user identity model is one of the two models the specification permits
|
|
678
|
+
(§3.1).
|
|
634
679
|
|
|
635
|
-
### 5.1
|
|
680
|
+
### 5.1 The SDK removes deleted devices instead of marking them stale
|
|
636
681
|
|
|
637
|
-
§3.1 and §3.3 require a removed device's record
|
|
638
|
-
for MAXLATENCY
|
|
639
|
-
decrypt. The SDK removes the record immediately
|
|
682
|
+
§3.1 and §3.3 require an implementation to mark a removed device's record stale
|
|
683
|
+
and keep it for MAXLATENCY. Messages already in flight from that device then
|
|
684
|
+
still decrypt. The SDK removes the record immediately
|
|
640
685
|
(`internal/sesame/manager.ts:2098-2102`).
|
|
641
686
|
|
|
642
|
-
**
|
|
643
|
-
|
|
644
|
-
exists
|
|
645
|
-
|
|
687
|
+
**State the consequence plainly. A message that a device sent moments before its
|
|
688
|
+
removal becomes permanently undecryptable.** The specification's staleness window
|
|
689
|
+
exists to prevent exactly that. No other part of the codebase contradicts the
|
|
690
|
+
Sesame text this directly.
|
|
646
691
|
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
the
|
|
692
|
+
The SDK also reuses the word `stale` for a different concept: a device *list*
|
|
693
|
+
that needs refetching (`internal/sesame/types.ts:476-483`). The specification uses
|
|
694
|
+
the word for a deleted user or device.
|
|
650
695
|
|
|
651
696
|
### 5.2 Session expiry applies only to unacknowledged sessions
|
|
652
697
|
|
|
653
|
-
§4.2 is unconditional
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
698
|
+
§4.2 is unconditional. At MAXSEND past its timestamp, a session may no longer
|
|
699
|
+
encrypt. The SDK applies that bound only to sessions that never received a reply
|
|
700
|
+
(`internal/sesame/types.ts:175-199`). A session that received one message on its
|
|
701
|
+
first day stays a valid encryption session indefinitely.
|
|
657
702
|
|
|
658
|
-
The configuration field
|
|
659
|
-
|
|
660
|
-
(`internal/sesame/validation.ts:93-101`)
|
|
661
|
-
quantity
|
|
703
|
+
The configuration field carries the honest name `maxUnacknowledgedSessionAge`.
|
|
704
|
+
One gap follows. The §4.2 invariant check
|
|
705
|
+
(`internal/sesame/validation.ts:93-101`) still runs against that renamed
|
|
706
|
+
quantity. It therefore applies the specification's arithmetic to a value that no
|
|
662
707
|
longer carries the specification's meaning.
|
|
663
708
|
|
|
664
709
|
### 5.3 Device limit
|
|
665
710
|
|
|
666
|
-
|
|
667
|
-
`internal/sesame/manager.ts:285-290`
|
|
668
|
-
|
|
669
|
-
|
|
711
|
+
The SDK caps a user at 5 devices (`internal/sesame/types.ts:45-50`).
|
|
712
|
+
The file `internal/sesame/manager.ts:285-290` enforces the cap. The
|
|
713
|
+
specification's §6.5 recommends *a* limit without fixing one, and `libsignal`
|
|
714
|
+
permits device IDs up to 127. The cap is a
|
|
715
|
+
product decision. A source comment credits it to the Signal Protocol, which is
|
|
716
|
+
inaccurate.
|
|
670
717
|
|
|
671
718
|
### 5.4 Extensions: provisioning, transfer, device names
|
|
672
719
|
|
|
673
|
-
|
|
674
|
-
exist,
|
|
720
|
+
Sesame rev. 2 holds none of these. It says nothing about how a device comes to
|
|
721
|
+
exist, takes a name, or migrates.
|
|
675
722
|
|
|
676
723
|
**QR device provisioning** (`device/provisioning.ts`). Ephemeral X25519 ECDH →
|
|
677
724
|
HKDF → AES-256-GCM, with a `signalprotocol://link-device` QR scheme, strict prefix
|
|
678
725
|
and key validation, a 5-minute TTL, and rollback on both server and local failure.
|
|
679
|
-
The construction is sound.
|
|
680
|
-
|
|
681
|
-
|
|
726
|
+
The construction is sound. One property is worth naming. Nothing binds the
|
|
727
|
+
provisioning key to the primary device's long-term identity. The only
|
|
728
|
+
authentication for the channel is the out-of-band display of the QR code.
|
|
682
729
|
|
|
683
730
|
**Device transfer** (`device/transfer.ts`). Clones the identity private key and
|
|
684
|
-
live ratchet state to a new device. This is useful and it **
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
731
|
+
live ratchet state to a new device. This is useful, and it **breaks the invariant
|
|
732
|
+
that Sesame rests on**: one device record, one device, its own sessions. After a
|
|
733
|
+
transfer, two physical devices hold the same identity private key and the same
|
|
734
|
+
ratchet state for every peer.
|
|
735
|
+
|
|
736
|
+
A peer message that one device decrypts desynchronizes the other. The duplicated
|
|
737
|
+
ratchet state also weakens the
|
|
738
|
+
forward-secrecy guarantee that keeps the compromise of one endpoint within that
|
|
739
|
+
endpoint. Restore deliberately drops archived sessions, which discards the
|
|
740
|
+
convergence state that §3.4 needs.
|
|
692
741
|
|
|
693
742
|
**Encrypted device names** (`device/device-name-crypto.ts`). A three-field
|
|
694
|
-
protobuf
|
|
695
|
-
pattern, correctly constructed.
|
|
743
|
+
protobuf carries a synthetic IV that HMAC derives, with AES-256-CTR. That is the
|
|
744
|
+
standard SIV pattern, correctly constructed. The specification has no
|
|
745
|
+
counterpart.
|
|
696
746
|
|
|
697
|
-
**Identity-change gating.**
|
|
698
|
-
sets `pendingVerification` and blocks sending until the application
|
|
699
|
-
rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame
|
|
700
|
-
no such concept. This is a genuine improvement.
|
|
747
|
+
**Identity-change gating.** The SDK TOFU-pins an unseen identity. A changed
|
|
748
|
+
identity sets `pendingVerification` and blocks sending until the application
|
|
749
|
+
accepts the rotation (`internal/sesame/manager.ts:561-566`, `:1682-1714`). Sesame
|
|
750
|
+
rev. 2 has no such concept. This is a genuine improvement.
|
|
701
751
|
|
|
702
|
-
**Not implemented:** proof of possession.
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
752
|
+
**Not implemented:** proof of possession. Registration does not make the device
|
|
753
|
+
sign a server-issued nonce with its identity private key. Registration therefore
|
|
754
|
+
trusts the relay more than §6.3 assumes. A deployment that needs proof of
|
|
755
|
+
possession must add it at the application layer.
|
|
706
756
|
|
|
707
757
|
---
|
|
708
758
|
|
|
@@ -710,81 +760,91 @@ deployment that needs this must add it at the application layer.
|
|
|
710
760
|
|
|
711
761
|
### 6.1 Version 2 is faithful
|
|
712
762
|
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
763
|
+
These parts match `libsignal`:
|
|
764
|
+
|
|
765
|
+
- all four HKDF labels, byte for byte
|
|
766
|
+
- the KEM construction and its direction-swapped IKM orderings
|
|
767
|
+
- the authentication tag, which is the same 16-byte raw HKDF output
|
|
768
|
+
- AES-256-GCM-SIV with a zero nonce and no AAD
|
|
769
|
+
- the multi-recipient binary format ([`sealed_sender.rs:1023-1153`][ss],
|
|
770
|
+
`:1306-1360`): version bytes `0x22`/`0x23`, the varint count, and 17-byte
|
|
771
|
+
ServiceIds
|
|
772
|
+
- the packed device ID with its 14-bit registration ID and `0x3FFF` mask
|
|
773
|
+
|
|
774
|
+
Certificate validation order and semantics match as well. That includes the
|
|
775
|
+
trust-root loop, which does not short-circuit and therefore does not reveal which
|
|
776
|
+
root validated.
|
|
722
777
|
|
|
723
778
|
### 6.2 Version 1 diverges in three places
|
|
724
779
|
|
|
725
|
-
**The 96-byte HKDF output
|
|
726
|
-
`(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss])
|
|
727
|
-
derives `(cipher, mac, chain)`
|
|
780
|
+
**The SDK splits the 96-byte HKDF output in a different order.** `libsignal`
|
|
781
|
+
derives `(chain_key, cipher_key, mac_key)` ([`sealed_sender.rs:711-746`][ss]).
|
|
782
|
+
The SDK derives `(cipher, mac, chain)`
|
|
728
783
|
(`internal/protocol/sealed-sender/encryption.ts:164-166`). The construction is
|
|
729
|
-
self-consistent and secure
|
|
730
|
-
|
|
731
|
-
implementation divergence rather than a design decision
|
|
732
|
-
specification document records the same order, so the two
|
|
733
|
-
with each other.
|
|
784
|
+
self-consistent and secure, because the keys are independent HKDF output either
|
|
785
|
+
way. Every v1 key still sits in a different slot than `libsignal`'s. This is an
|
|
786
|
+
implementation divergence rather than a design decision. The SDK's own pinned
|
|
787
|
+
specification document records the same order, so the two agree with each other.
|
|
734
788
|
|
|
735
789
|
**Public keys in the v1 salt and in certificates omit the `0x05` type byte.**
|
|
736
|
-
`libsignal` uses the 33-byte serialized form
|
|
790
|
+
`libsignal` uses the 33-byte serialized form. The SDK uses raw 32 bytes and
|
|
737
791
|
enforces that length
|
|
738
|
-
(`internal/protocol/sealed-sender/certificate.ts:306-309`).
|
|
739
|
-
|
|
740
|
-
|
|
792
|
+
(`internal/protocol/sealed-sender/certificate.ts:306-309`). The SDK's own v2 path
|
|
793
|
+
*does* apply the `0x05` prefix, so the two sealed-sender versions disagree with
|
|
794
|
+
each other.
|
|
741
795
|
|
|
742
796
|
**The inner envelope is a hand-rolled varint format**
|
|
743
797
|
(`internal/protocol/sealed-sender/encryption.ts:46-86`) rather than the
|
|
744
|
-
`UnidentifiedSenderMessage.Message` protobuf. It
|
|
745
|
-
field `libsignal`
|
|
746
|
-
plaintext payloads ([`sealed_sender.rs:2055-2075`][ss])
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
798
|
+
`UnidentifiedSenderMessage.Message` protobuf. It still carries the message-type
|
|
799
|
+
field that `libsignal` dispatches on, which selects between prekey, regular,
|
|
800
|
+
sender-key, and plaintext payloads ([`sealed_sender.rs:2055-2075`][ss]). The
|
|
801
|
+
field is a leading byte holding `libsignal`'s enum values. The framing therefore
|
|
802
|
+
differs while the dispatch does not.
|
|
803
|
+
|
|
804
|
+
That field lets the unseal path restore the real message type. Without it the
|
|
805
|
+
path would rebuild the envelope with a fixed type, and a sealed group message
|
|
806
|
+
would not decrypt as a group message.
|
|
751
807
|
|
|
752
808
|
**`PLAINTEXT_CONTENT` (8) is a known wire value that this SDK rejects.**
|
|
753
809
|
`libsignal` uses it to carry a `DecryptionErrorMessage` when no session exists
|
|
754
|
-
to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]). This SDK
|
|
755
|
-
decryption-error signals over a dedicated relay channel
|
|
756
|
-
|
|
757
|
-
produces the type and no decrypt path consumes
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
810
|
+
to encrypt one under ([`sealed_sender.rs:2055-2075`][ss]). This SDK instead
|
|
811
|
+
delivers decryption-error signals over a dedicated relay channel. Sesame §4.1
|
|
812
|
+
defines that channel, and the SDK builds it from the `retryRequests` table and
|
|
813
|
+
`sendRetryRequest`. No send path produces the type, and no decrypt path consumes
|
|
814
|
+
it. The envelope parse therefore
|
|
815
|
+
rejects the value (`internal/protocol/sealed-sender/types.ts`) rather than map it
|
|
816
|
+
to an envelope type with no handler.
|
|
817
|
+
|
|
818
|
+
The enum keeps the member so the wire values stay a faithful record.
|
|
819
|
+
`envelopeTypeForContent` throws on it, so a new member without a route fails
|
|
820
|
+
loudly. A peer that sends one gets a clean parse failure, not a payload routed
|
|
821
|
+
into the pairwise ratchet.
|
|
822
|
+
|
|
823
|
+
Note the cost when you debug interop. The parsers throw a single generic error
|
|
824
|
+
for every malformed envelope. A peer implementation that legitimately sends
|
|
825
|
+
`PLAINTEXT_CONTENT` therefore fails with `Sealed sender verification failed`,
|
|
826
|
+
which is the same string a MAC mismatch produces. The uniformity is deliberate,
|
|
827
|
+
and the parse runs after authentication, so nothing here is an oracle. Watch for
|
|
828
|
+
one pattern: sealed messages from one peer stack fail with that error while
|
|
829
|
+
messages from this SDK succeed. Check the leading content-type byte before you
|
|
830
|
+
treat that as a cryptographic failure.
|
|
772
831
|
|
|
773
832
|
### 6.3 The delivery token follows `libsignal`, not an SDK invention
|
|
774
833
|
|
|
775
834
|
Despite the module name, `deriveAccessKey`
|
|
776
835
|
(`internal/protocol/sealed-sender/delivery-token.ts:52-91`) is `libsignal`'s
|
|
777
|
-
`ProfileKey::derive_access_key
|
|
778
|
-
nonce
|
|
779
|
-
publishes for that derivation.
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
836
|
+
`ProfileKey::derive_access_key`. It runs AES-256-GCM over 16 zero bytes with a
|
|
837
|
+
zero nonce and truncates to 16 bytes. It reproduces the values `libsignal`
|
|
838
|
+
publishes for that derivation.
|
|
839
|
+
|
|
840
|
+
The 16-byte value comes from the recipient's profile key. It proves to the relay
|
|
841
|
+
that the sender knows that profile key, which gates anonymous delivery to
|
|
842
|
+
contacts. It never enters the sealed-sender wire format. The sender presents it
|
|
843
|
+
out of band.
|
|
844
|
+
|
|
845
|
+
The SDK's own documentation once described a different, 12-byte HKDF
|
|
846
|
+
construction that no code implements. That description is wrong, and the PR that
|
|
847
|
+
accompanies this file corrects it.
|
|
788
848
|
|
|
789
849
|
Certificate signatures use Ed25519 rather than XEdDSA, per §1.2, so SDK
|
|
790
850
|
certificates cannot validate against a Signal Messenger trust root or vice versa. The
|
|
@@ -797,29 +857,33 @@ appropriate for a different trust root but worth noting.
|
|
|
797
857
|
|
|
798
858
|
### 7.1 Sender key message format
|
|
799
859
|
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
860
|
+
These parts match:
|
|
861
|
+
|
|
862
|
+
- protobuf field numbers and types, against [`wire.proto`][wp] exactly
|
|
863
|
+
- the `[version byte] ‖ protobuf ‖ [64-byte signature]` framing with version
|
|
864
|
+
`0x33`
|
|
865
|
+
- the `0x01`/`0x02` chain seeds and the `WhisperGroup` info string
|
|
866
|
+
- AES-256-CBC with the derived IV
|
|
867
|
+
- the capacity constants
|
|
804
868
|
|
|
805
869
|
Three things do not:
|
|
806
870
|
|
|
807
|
-
**`distributionUuid` carries a UTF-8 string, not 16 UUID bytes
|
|
871
|
+
**`distributionUuid` carries a UTF-8 string, not 16 UUID bytes**. The SDK writes
|
|
808
872
|
the 36-character textual form of a random UUIDv4
|
|
809
|
-
(`internal/protocol/sender-keys/manager.ts:279`, `:932`)
|
|
810
|
-
exactly the 16 raw bytes and rejects anything else on parse. The value is
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
873
|
+
(`internal/protocol/sender-keys/manager.ts:279`, `:932`). `libsignal` writes
|
|
874
|
+
exactly the 16 raw bytes and rejects anything else on parse. The value is the
|
|
875
|
+
same *kind* of thing `libsignal` uses, an opaque random identifier with no
|
|
876
|
+
relation to the group. The encoding still differs, so neither side can parse the
|
|
877
|
+
other's frames. One related point: `chain_id` is an FNV-1a hash of that string
|
|
814
878
|
rather than a random 31-bit value.
|
|
815
879
|
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
requires
|
|
880
|
+
The SDK once wrote `groupId:userId:deviceId:timestamp` here. That was a metadata
|
|
881
|
+
leak rather than a format deviation, because `distributionUuid` sits outside the
|
|
882
|
+
ciphertext. Every relay on the path could read the plaintext group and sender off
|
|
883
|
+
each message. The current code fixes it, and the sender-keys specification now
|
|
884
|
+
requires an opaque identifier.
|
|
821
885
|
|
|
822
|
-
**Signatures are Ed25519, not XEdDSA**, per §1.2
|
|
886
|
+
**Signatures are Ed25519, not XEdDSA**, per §1.2. `libsignal` also serializes the
|
|
823
887
|
signing key as 33 bytes where the SDK uses 32.
|
|
824
888
|
|
|
825
889
|
### 7.2 Message-key derivation omits HKDF-Extract
|
|
@@ -829,68 +893,74 @@ make the format look compatible.
|
|
|
829
893
|
|
|
830
894
|
`libsignal` derives sender message keys with
|
|
831
895
|
`Hkdf::<Sha256>::new(None, &seed).expand(b"WhisperGroup", 48)`
|
|
832
|
-
([`sender_keys.rs:36-38`][sk]). `Hkdf::new`
|
|
896
|
+
([`sender_keys.rs:36-38`][sk]). `Hkdf::new` runs HKDF-**Extract** first, as
|
|
833
897
|
`PRK = HMAC-SHA256(salt = zeros[32], seed)`. Only then does it expand.
|
|
834
898
|
|
|
835
899
|
The SDK calls `hkdfExpand(seed, info, 48)` directly
|
|
836
900
|
(`internal/protocol/sender-keys/manager.ts:1062-1066`), where `hkdfExpand`
|
|
837
901
|
(`internal/crypto/kdf/hkdf.ts:86-116`) is pure RFC 5869 Expand using the seed
|
|
838
|
-
itself as the PRK. The extract step
|
|
902
|
+
itself as the PRK. The SDK never runs the extract step.
|
|
839
903
|
|
|
840
904
|
The derived IV and cipher key therefore differ from `libsignal`'s for the same
|
|
841
|
-
chain key.
|
|
905
|
+
chain key. A numeric check confirms it, rather than inspection alone. For a chain
|
|
842
906
|
key of 32 repeated `0x42` bytes, the SDK derives IV
|
|
843
907
|
`2a56b9eb80b3c1ffebd97221b2175960` where `libsignal` derives
|
|
844
908
|
`890d51ea73e564722351dc0d5a09142c`.
|
|
845
909
|
|
|
846
|
-
This appears unintentional. It is not a weakness
|
|
847
|
-
uniformly random HMAC output is cryptographically
|
|
848
|
-
sender-keys note claims equivalence with `libsignal` at this step, and that
|
|
849
|
-
is incorrect.
|
|
910
|
+
This appears unintentional. It is not a weakness, because dropping Extract from a
|
|
911
|
+
uniformly random HMAC output is cryptographically sound. The repository's own
|
|
912
|
+
sender-keys note still claims equivalence with `libsignal` at this step, and that
|
|
913
|
+
claim is incorrect. This entry flags it for correction.
|
|
850
914
|
|
|
851
915
|
### 7.3 Groups are an independent design
|
|
852
916
|
|
|
853
917
|
The zero-knowledge primitives underneath are real and faithful (§7.4). The group
|
|
854
918
|
system built on them is not the Signal Private Group System.
|
|
855
919
|
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
`
|
|
920
|
+
These parts are faithful:
|
|
921
|
+
|
|
922
|
+
- role and access-control enum values, which match `libsignal`'s exactly
|
|
923
|
+
- group ID derivation from the master key
|
|
924
|
+
- the `open-e2ee:group:` identifier namespace, which the package owns
|
|
925
|
+
- authentication, which uses real zkgroup credentials
|
|
926
|
+
- member identifiers and profile keys, which the SDK encrypts into real
|
|
927
|
+
`UidCiphertext` and `ProfileKeyCiphertext` values
|
|
861
928
|
|
|
862
929
|
What differs, and it is structural:
|
|
863
930
|
|
|
864
|
-
**The enforcement contract is this SDK's own
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
931
|
+
**The enforcement contract is this SDK's own**. The client submits change actions
|
|
932
|
+
that carry zero-knowledge presentations, as it does in the Signal Private Group
|
|
933
|
+
System. The **server** then validates every action against the group's access
|
|
934
|
+
control before it signs and persists the accepted result.
|
|
935
|
+
|
|
936
|
+
The enforcement rules are the SDK's own S1–S14 contract rather than Signal
|
|
937
|
+
Messenger's server implementation. The shipped enforcing server
|
|
870
938
|
(`internal/groups/server-engine.ts`, with an installable Convex component)
|
|
871
|
-
implements that contract.
|
|
872
|
-
|
|
873
|
-
authorization
|
|
939
|
+
implements that contract. On every applied change, clients verify the server's
|
|
940
|
+
signature, the group binding, the strict version sequence, and the pre-state
|
|
941
|
+
authorization.
|
|
874
942
|
|
|
875
|
-
**Profile-key credential issuance is not blinded
|
|
943
|
+
**Profile-key credential issuance is not blinded**. The issuance endpoint
|
|
876
944
|
receives the raw 32-byte profile key, so the issuing server sees every user's
|
|
877
|
-
profile key in plaintext at issuance time. The Signal Private Group System
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
(`internal/protocol/zk/credentials/issuance.ts`) but
|
|
881
|
-
path
|
|
882
|
-
|
|
883
|
-
|
|
945
|
+
profile key in plaintext at issuance time. The Signal Private Group System issues
|
|
946
|
+
profile-key credentials over a *blinded* commitment, so its server never learns
|
|
947
|
+
the key. The blinding primitives exist in this codebase
|
|
948
|
+
(`internal/protocol/zk/credentials/issuance.ts`), but nothing wires them into
|
|
949
|
+
this path. Section 12.1 of the in-tree group specification carries the same
|
|
950
|
+
caveat.
|
|
951
|
+
|
|
952
|
+
Until blinded issuance ships, a deployer must assume that the issuance server
|
|
953
|
+
learns profile keys, and therefore profile names and avatars.
|
|
884
954
|
|
|
885
955
|
**Serialization is JSON**, not protobuf, both for group state
|
|
886
956
|
(`internal/groups/manager.ts:1229-1236`) and for the blob payloads inside the
|
|
887
|
-
AES-256-GCM-SIV envelope (`internal/groups/encrypted-state.ts:70-81`).
|
|
888
|
-
encrypted group title
|
|
957
|
+
AES-256-GCM-SIV envelope (`internal/groups/encrypted-state.ts:70-81`). Signal
|
|
958
|
+
Messenger cannot decrypt an encrypted group title or description, even with the
|
|
889
959
|
correct master key.
|
|
890
960
|
|
|
891
961
|
**Invite links** use `https://join.open-e2ee.dev/#` with a 49-byte raw payload
|
|
892
962
|
(`internal/groups/invite-link.ts:36`, `:78-85`), where `libsignal` uses
|
|
893
|
-
`https://signal.group/#` with a protobuf.
|
|
963
|
+
`https://signal.group/#` with a protobuf. The source labels this accurately as
|
|
894
964
|
the package's own format.
|
|
895
965
|
|
|
896
966
|
### 7.4 The zero-knowledge layer is a faithful port
|
|
@@ -899,22 +969,27 @@ Stated directly, because "zk" in a codebase often means something weaker: this i
|
|
|
899
969
|
a genuine zero-knowledge credential system, not HMAC tokens, not signatures, not a
|
|
900
970
|
placeholder.
|
|
901
971
|
|
|
902
|
-
`internal/protocol/zk/` implements the Sigma protocol over
|
|
903
|
-
Fiat–Shamir
|
|
904
|
-
`POKSHO_Ristretto_SHOHMACSHA256` exactly
|
|
905
|
-
MAC credential system
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
972
|
+
The directory `internal/protocol/zk/` implements the Sigma protocol over
|
|
973
|
+
Ristretto255 with Fiat–Shamir. It matches `poksho`'s protocol label
|
|
974
|
+
`POKSHO_Ristretto_SHOHMACSHA256` exactly. It also implements the
|
|
975
|
+
Chase–Perrin–Zaverucha algebraic MAC credential system, which matches
|
|
976
|
+
`zkcredential`'s five domain labels byte for byte. The Lizard encoding, the
|
|
977
|
+
`UidStruct` derivation, the `AuthCredentialWithPni` flow, and the redemption
|
|
978
|
+
window all match `libsignal`.
|
|
979
|
+
|
|
980
|
+
One test carries the strongest evidence. It asserts the 416-byte serialized
|
|
981
|
+
system parameters against a hex string taken from `libsignal`'s own Rust test,
|
|
982
|
+
and it passes.
|
|
983
|
+
|
|
984
|
+
One deviation remains. The SDK derives server secret parameters through four
|
|
985
|
+
separately labelled key derivations, where `libsignal` uses a single seeded
|
|
986
|
+
derivation (`internal/protocol/zk/groups/server-params.ts:43-54`). The same
|
|
987
|
+
randomness therefore yields different server keys.
|
|
988
|
+
|
|
989
|
+
That structural difference stands on its own. Separately, each deployment
|
|
990
|
+
generates its **own** random 32-byte seed, which puts the trust root with the
|
|
991
|
+
deploying operator rather than with Signal Messenger. No credential is
|
|
992
|
+
interchangeable with a Signal Messenger credential.
|
|
918
993
|
|
|
919
994
|
Credential serialization is also ad hoc and carries no version byte, where
|
|
920
995
|
`libsignal` uses a leading version byte. That is a forward-compatibility gap
|
|
@@ -924,49 +999,56 @@ rather than a security one.
|
|
|
924
999
|
|
|
925
1000
|
## Unverified and needs review
|
|
926
1001
|
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
- **
|
|
931
|
-
|
|
932
|
-
(`client/sealed-sender-ops.ts:263-265`)
|
|
933
|
-
Sesame layer re-derives the initiation state from the ciphertext.
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
- **
|
|
937
|
-
|
|
938
|
-
against the decrypted static key
|
|
939
|
-
`libsignal
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
1002
|
+
This review lists the following items rather than asserts them. It could not
|
|
1003
|
+
confirm any of them in source.
|
|
1004
|
+
|
|
1005
|
+
- **Does a sealed-sender-wrapped prekey message decrypt end to end?** The unseal
|
|
1006
|
+
path rebuilds the envelope with a fixed message type
|
|
1007
|
+
(`client/sealed-sender-ops.ts:263-265`). An adjacent comment suggests that the
|
|
1008
|
+
Sesame layer re-derives the initiation state from the ciphertext. This review
|
|
1009
|
+
traced neither that path nor the integration tests. First-contact sealed
|
|
1010
|
+
messages break if Sesame does not detect the state itself.
|
|
1011
|
+
- **Does anything downstream enforce the session-identity-key check?** The
|
|
1012
|
+
sealed-sender note requires it. The decrypt path compares the certificate's
|
|
1013
|
+
identity key against the decrypted static key. It does not consult the session
|
|
1014
|
+
store. In `libsignal`, the identity store carries the equivalent guarantee
|
|
1015
|
+
later.
|
|
1016
|
+
- **Is `@noble/post-quantum`'s ML-KEM-1024 byte-identical to libcrux's?** The
|
|
1017
|
+
repository claims pinned known-answer-test coverage. This review did not run
|
|
1018
|
+
those tests.
|
|
1019
|
+
- **Does the Lizard encoding match `libsignal`'s vectors?** The forward and
|
|
1020
|
+
inverse Elligator maps are hand-implemented in TypeScript. The structure and
|
|
1021
|
+
the labels are correct, and unit tests exist. This review did not diff the
|
|
1022
|
+
outputs against `libsignal`'s. A subtle error here silently corrupts every
|
|
1023
|
+
`UidStruct`.
|
|
1024
|
+
- **Do the SPQR state-machine transitions match?** State names, message types,
|
|
1025
|
+
and chunk counts match `libsignal`'s. This review did not diff the eleven-state
|
|
1026
|
+
transition table transition by transition.
|
|
1027
|
+
- **Does the SPQR decoder bound the stored points?** `libsignal` caps stored
|
|
1028
|
+
points per polynomial. This review found no equivalent bound in the SDK's
|
|
952
1029
|
decoder.
|
|
953
|
-
- **
|
|
954
|
-
|
|
955
|
-
succeed
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
1030
|
+
- **Does SPQR state roll back on an authentication failure**? By contrast,
|
|
1031
|
+
`libsignal` commits the new state only after the MAC and the decryption
|
|
1032
|
+
succeed. The SDK's receive
|
|
1033
|
+
path mutates state during decode, and this review did not trace the caller's
|
|
1034
|
+
rollback behaviour.
|
|
1035
|
+
- **Does an equivalent of `libsignal`'s `promote_matching_session` exist?**
|
|
1036
|
+
`libsignal` matches archived sessions on `(version, base key)`. The SDK keys
|
|
1037
|
+
its map on the base key alone.
|
|
960
1038
|
|
|
961
1039
|
---
|
|
962
1040
|
|
|
963
1041
|
## Reporting an error in this document
|
|
964
1042
|
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
1043
|
+
Email security@open-e2ee.dev or open an issue when something here is wrong. Three
|
|
1044
|
+
cases qualify:
|
|
1045
|
+
|
|
1046
|
+
- a citation that does not say what this document claims it says
|
|
1047
|
+
- a deviation that the code already fixed
|
|
1048
|
+
- a deviation that this document omits
|
|
1049
|
+
|
|
1050
|
+
A deviations document that drifts from the code is worse than no document at
|
|
1051
|
+
all, because it invites exactly the assumption it exists to prevent.
|
|
970
1052
|
|
|
971
1053
|
[ik]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/identity_key.rs
|
|
972
1054
|
[fp]: https://github.com/signalapp/libsignal/blob/main/rust/protocol/src/fingerprint.rs
|