Documentation
¶
Overview ¶
Package libsignal is a pure-Go implementation of the Signal client protocol core, wire-compatible with signalapp/libsignal.
The implementation contains no cgo, C, or Rust: it is built entirely on the Go standard library and a small set of pure-Go cryptography dependencies. It targets the client-side protocol surface (curve and KEM primitives, wire messages, the Double Ratchet session, group sender keys, sealed sender, and fingerprints). Server-only and out-of-scope domains (zkgroup, usernames, key transparency, SVR, device transfer, media, and message backup) are not implemented; see the README scope matrix for the authoritative list.
Compatibility staging ¶
Wire compatibility is asserted against a pinned upstream tag rather than a moving target. Until the Sparse Post-Quantum Ratchet (SPQR) phase lands, compatibility claims are bounded to the libsignal v0.91.0 protocol surface; once SPQR is ported the compat harness is re-pinned to the current upstream mainline. This staging and its rationale are recorded in decisions/0001-spqr-staged-compat.md.
License ¶
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file at the repository root.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package accountkeys implements Signal account-level key derivations.
|
Package accountkeys implements Signal account-level key derivations. |
|
Package address provides types identifying an individual Signal client instance: service IDs (ACI/PNI), device IDs, and protocol addresses.
|
Package address provides types identifying an individual Signal client instance: service IDs (ACI/PNI), device IDs, and protocol addresses. |
|
Package aes256gcmsiv exposes the module's AES-256-GCM-SIV (RFC 8452), the AEAD sealed sender v2 uses, for callers outside the module such as libsignal's Aes256GcmSiv binding.
|
Package aes256gcmsiv exposes the module's AES-256-GCM-SIV (RFC 8452), the AEAD sealed sender v2 uses, for callers outside the module such as libsignal's Aes256GcmSiv binding. |
|
attest
|
|
|
dcap
Package dcap parses and verifies Intel SGX DCAP attestation evidence, ported from rust/attest/src/dcap and cert_chain.rs at libsignal v0.102.2.
|
Package dcap parses and verifies Intel SGX DCAP attestation evidence, ported from rust/attest/src/dcap and cert_chain.rs at libsignal v0.102.2. |
|
enclave
Package enclave opens a Noise channel to a remote SGX enclave whose attestation names the enclave's public key, as libsignal v0.102.2 rust/attest/src/enclave.rs, sgx_session.rs and cds2.rs do, plus the bridge's SgxClientState (bridge/shared/types/src/sgx_session.rs).
|
Package enclave opens a Noise channel to a remote SGX enclave whose attestation names the enclave's public key, as libsignal v0.102.2 rust/attest/src/enclave.rs, sgx_session.rs and cds2.rs do, plus the bridge's SgxClientState (bridge/shared/types/src/sgx_session.rs). |
|
hsmenclave
Package hsmenclave opens a Noise channel to trusted code running in an HSM, as libsignal v0.102.2 rust/attest/src/hsm_enclave.rs does, wrapped in the bridge's HsmEnclaveClient (bridge/shared/types/src/hsm_enclave.rs).
|
Package hsmenclave opens a Noise channel to trusted code running in an HSM, as libsignal v0.102.2 rust/attest/src/hsm_enclave.rs does, wrapped in the bridge's HsmEnclaveClient (bridge/shared/types/src/hsm_enclave.rs). |
|
internal/testhook
Package testhook holds the test-only switches of the attest packages, the counterpart of upstream's cfg(any(test, feature = "test-util")).
|
Package testhook holds the test-only switches of the attest packages, the counterpart of upstream's cfg(any(test, feature = "test-util")). |
|
Package curve implements the Curve25519 (Djb) key types used by the Signal protocol: X25519 key agreement and the 33-byte serialized public-key wire format.
|
Package curve implements the Curve25519 (Djb) key types used by the Signal protocol: X25519 key agreement and the 33-byte serialized public-key wire format. |
|
Package devicetransfer makes the key and certificate a device offers while transferring an account to a new device, as libsignal v0.102.2 rust/device-transfer does through the bridge's DeviceTransfer_GeneratePrivateKey and DeviceTransfer_GenerateCertificate.
|
Package devicetransfer makes the key and certificate a device offers while transferring an account to a new device, as libsignal v0.102.2 rust/device-transfer does through the bridge's DeviceTransfer_GeneratePrivateKey and DeviceTransfer_GenerateCertificate. |
|
Package fingerprint implements Signal's safety-number fingerprints: the numeric DisplayableFingerprint (a 60-digit human-comparable string) and the ScannableFingerprint (a protobuf for QR-code comparison).
|
Package fingerprint implements Signal's safety-number fingerprints: the numeric DisplayableFingerprint (a 60-digit human-comparable string) and the ScannableFingerprint (a protobuf for QR-code comparison). |
|
Package groups implements Signal's sender-key (group messaging) state: the per-sender SenderKeyState/SenderKeyRecord and the sender-key distribution message (SKDM) create/process flow.
|
Package groups implements Signal's sender-key (group messaging) state: the per-sender SenderKeyState/SenderKeyRecord and the sender-key distribution message (SKDM) create/process flow. |
|
Package identity holds the identity-key operations of rust/protocol/src/identity_key.rs that go beyond a plain curve key pair: the IdentityKeyPairStructure serialization, alternate-identity (PNI) signatures, and the same-account check the session layer uses for note-to-self sessions.
|
Package identity holds the identity-key operations of rust/protocol/src/identity_key.rs that go beyond a plain curve key pair: the IdentityKeyPairStructure serialization, alternate-identity (PNI) signatures, and the same-account check the session layer uses for note-to-self sessions. |
|
internal
|
|
|
crypto
Package crypto provides thin, allocation-conscious wrappers over the Go standard library's symmetric primitives, with an error taxonomy and semantics mirroring upstream signalapp/libsignal (rust/crypto and rust/protocol/src/crypto.rs).
|
Package crypto provides thin, allocation-conscious wrappers over the Go standard library's symmetric primitives, with an error taxonomy and semantics mirroring upstream signalapp/libsignal (rust/crypto and rust/protocol/src/crypto.rs). |
|
crypto/gcmsiv
Package gcmsiv implements AES-256-GCM-SIV, the nonce-misuse-resistant AEAD of RFC 8452.
|
Package gcmsiv implements AES-256-GCM-SIV, the nonce-misuse-resistant AEAD of RFC 8452. |
|
mlkem768incr
Package mlkem768incr implements the INCREMENTAL ML-KEM-768 key encapsulation used by Signal's Sparse Post-Quantum Ratchet (SPQR), as a pure-Go port (no cgo) of the libcrux-ml-kem 0.0.8 `incremental` API that SPQR v1.5.1 depends on.
|
Package mlkem768incr implements the INCREMENTAL ML-KEM-768 key encapsulation used by Signal's Sparse Post-Quantum Ratchet (SPQR), as a pure-Go port (no cgo) of the libcrux-ml-kem 0.0.8 `incremental` API that SPQR v1.5.1 depends on. |
|
ristrettolizard
Package ristrettolizard implements Signal's reversible Ristretto encodings.
|
Package ristrettolizard implements Signal's reversible Ristretto encodings. |
|
spqr/chunked
Package chunked implements the SPQR chunked-transport erasure code: a GF(2^16) Reed-Solomon-style fountain code (gf.go + polynomial.go) that ships a message as a stream of fixed 32-byte chunks reconstructible from any sufficient subset.
|
Package chunked implements the SPQR chunked-transport erasure code: a GF(2^16) Reed-Solomon-style fountain code (gf.go + polynomial.go) that ships a message as a stream of fixed 32-byte chunks reconstructible from any sufficient subset. |
|
upstream
Package upstream records the upstream monorepo domains that this fork tracks.
|
Package upstream records the upstream monorepo domains that this fork tracks. |
|
zkgroupserver
Package zkgroupserver supplies server operations for compatibility tests only.
|
Package zkgroupserver supplies server operations for compatibility tests only. |
|
Package kem implements key encapsulation mechanisms (KEMs) for the Signal protocol.
|
Package kem implements key encapsulation mechanisms (KEMs) for the Signal protocol. |
|
Package messagebackup reports the local evidence boundary for Signal message-backup-adjacent derivations.
|
Package messagebackup reports the local evidence boundary for Signal message-backup-adjacent derivations. |
|
Package noise implements the two Noise handshakes libsignal uses to open an encrypted channel to an SGX enclave (CDSI, SVR2), compatible with rust/attest/src/client_connection.rs at libsignal v0.102.2, which drives the snow 0.10.0 crate:
|
Package noise implements the two Noise handshakes libsignal uses to open an encrypted channel to an SGX enclave (CDSI, SVR2), compatible with rust/attest/src/client_connection.rs at libsignal v0.102.2, which drives the snow 0.10.0 crate: |
|
Package poksho implements libsignal's Ristretto Schnorr proof system and SHO hash constructions, compatible with rust/poksho at libsignal v0.102.2.
|
Package poksho implements libsignal's Ristretto Schnorr proof system and SHO hash constructions, compatible with rust/poksho at libsignal v0.102.2. |
|
Package proofreport exposes conservative Signal proof and backup coverage metadata for downstream readiness checks.
|
Package proofreport exposes conservative Signal proof and backup coverage metadata for downstream readiness checks. |
|
Package proto contains the Signal protocol wire, storage, service, sealed sender, and fingerprint message definitions, ported verbatim (field numbers and types) from upstream libsignal's rust/protocol/src/proto/*.proto.
|
Package proto contains the Signal protocol wire, storage, service, sealed sender, and fingerprint message definitions, ported verbatim (field numbers and types) from upstream libsignal's rust/protocol/src/proto/*.proto. |
|
Package protocol implements the Signal wire message types: the versioned, length-checked binary encodings of SignalMessage, PreKeySignalMessage, and the group/plaintext message forms.
|
Package protocol implements the Signal wire message types: the versioned, length-checked binary encodings of SignalMessage, PreKeySignalMessage, and the group/plaintext message forms. |
|
Package ratchet implements the Double Ratchet key schedule: the chain-key step, message-key derivation, root-key/DH ratchet step, and the PQXDH master secret.
|
Package ratchet implements the Double Ratchet key schedule: the chain-key step, message-key derivation, root-key/DH ratchet step, and the PQXDH master secret. |
|
Package sealedsender implements Signal's sealed sender certificates and message content (the UnidentifiedSenderMessageContent, "USMC"), a pure-Go port of rust/protocol/src/sealed_sender.rs validated against upstream libsignal v0.91.0.
|
Package sealedsender implements Signal's sealed sender certificates and message content (the UnidentifiedSenderMessageContent, "USMC"), a pure-Go port of rust/protocol/src/sealed_sender.rs validated against upstream libsignal v0.91.0. |
|
Package session models the Double Ratchet session state and the PQXDH establishment + message cipher: SessionState (a thin wrapper over the generated proto.SessionStructure), SessionRecord (the current state plus a bounded list of archived states), ProcessPreKeyBundle / InitializeBobSession (handshake), and Encrypt / Decrypt (the message cipher).
|
Package session models the Double Ratchet session state and the PQXDH establishment + message cipher: SessionState (a thin wrapper over the generated proto.SessionStructure), SessionRecord (the current state plus a bounded list of archived states), ProcessPreKeyBundle / InitializeBobSession (handshake), and Encrypt / Decrypt (the message cipher). |
|
Package spqr implements Signal's Sparse Post-Quantum Ratchet (SPQR), the Stage-2 post-quantum layer that augments the Double Ratchet with chunked ML-KEM-768 key agreement.
|
Package spqr implements Signal's Sparse Post-Quantum Ratchet (SPQR), the Stage-2 post-quantum layer that augments the Double Ratchet with chunked ML-KEM-768 key agreement. |
|
Package stores defines the storage interfaces the Signal protocol drives against — the identity, pre-key, signed-pre-key, Kyber-pre-key, session, and sender-key stores — and is a pure-Go port of rust/protocol/src/storage/traits.rs.
|
Package stores defines the storage interfaces the Signal protocol drives against — the identity, pre-key, signed-pre-key, Kyber-pre-key, session, and sender-key stores — and is a pure-Go port of rust/protocol/src/storage/traits.rs. |
|
inmem
Package inmem provides in-memory implementations of the storage interfaces in the stores package.
|
Package inmem provides in-memory implementations of the storage interfaces in the stores package. |
|
Package svr reports the local evidence boundary for Signal SVR and SVR2.
|
Package svr reports the local evidence boundary for Signal SVR and SVR2. |
|
Package svrb reports the local evidence boundary for Signal SVRB.
|
Package svrb reports the local evidence boundary for Signal SVRB. |
|
Package usernames implements Signal username validation and username links.
|
Package usernames implements Signal username validation and username links. |
|
Package zkcredential implements attribute-based anonymous credentials and endorsements compatible with rust/zkcredential at libsignal v0.102.2.
|
Package zkcredential implements attribute-based anonymous credentials and endorsements compatible with rust/zkcredential at libsignal v0.102.2. |
|
Package zkgroup implements the client group and profile APIs of libsignal v0.102.2.
|
Package zkgroup implements the client group and profile APIs of libsignal v0.102.2. |
|
zkcrypto
Package zkcrypto implements the attribute encryption and legacy credential primitives of libsignal v0.102.2.
|
Package zkcrypto implements the attribute encryption and legacy credential primitives of libsignal v0.102.2. |