Documentation
¶
Overview ¶
Package matrixolm implements the Olm and Megolm primitives Matrix end-to-end encryption needs, built on the standard library.
It follows the same construction upstream Apprise uses, which in turn follows the Megolm specification and libolm. Matching the construction is what makes the bytes on the wire match: real Matrix clients have to decrypt what we send, so the format is not ours to choose.
Index ¶
- func CanonicalJSON(value any) ([]byte, error)
- func DecodeBase64(value string) ([]byte, error)
- func EncodeBase64(data []byte) string
- func MarshalEvent(payload any) ([]byte, error)
- func VerifySignature(publicKeyBase64 string, message []byte, signatureBase64 string) bool
- type Account
- func (a *Account) DeviceKeys(userID, deviceID string) (map[string]any, error)
- func (a *Account) GenerateOneTimeKeys(userID, deviceID string, count int) (map[string]any, error)
- func (a *Account) IdentityKey() string
- func (a *Account) NewOutboundSession(theirIdentityKey, theirOneTimeKey string) (*OlmSession, error)
- func (a *Account) PrivateKeys() (identity, signing []byte)
- func (a *Account) Sign(data []byte) string
- func (a *Account) SigningKey() string
- type MegolmSession
- type OlmMessage
- type OlmSession
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanonicalJSON ¶
CanonicalJSON returns the sorted-key, whitespace-free encoding Matrix signs.
func DecodeBase64 ¶
DecodeBase64 accepts padded, unpadded and URL-safe base64, matching the leniency of other Matrix implementations.
func EncodeBase64 ¶
EncodeBase64 returns the unpadded base64 Matrix uses on the wire.
func MarshalEvent ¶
MarshalEvent serializes an event payload the way upstream does before encrypting it: a space after every colon and comma, and member order taken from the value rather than sorted. Pass a struct, whose field order encoding/json preserves; a map would be re-ordered and produce a ciphertext upstream never would.
func VerifySignature ¶
VerifySignature checks an Ed25519 signature written the way Matrix writes them: unpadded base64 over a public key in the same encoding.
This is what stops a homeserver handing us a device key of its choosing to encrypt to, so a malformed key or signature has to read as "not verified" rather than being skipped over.
Types ¶
type Account ¶
type Account struct {
// contains filtered or unexported fields
}
Account is the device identity: a Curve25519 key that other devices encrypt to, and an Ed25519 key that signs everything this device publishes.
func NewAccountFromKeys ¶
NewAccountFromKeys restores an account from stored raw private keys, so a notifier does not register a new device on every send.
func (*Account) DeviceKeys ¶
DeviceKeys builds the signed device key object for POST /keys/upload.
func (*Account) GenerateOneTimeKeys ¶
GenerateOneTimeKeys tops the pool up to count keys and returns the signed one_time_keys object for POST /keys/upload.
func (*Account) IdentityKey ¶
IdentityKey is the Curve25519 public key other devices encrypt to.
func (*Account) NewOutboundSession ¶
func (a *Account) NewOutboundSession(theirIdentityKey, theirOneTimeKey string) (*OlmSession, error)
NewOutboundSession performs the triple Diffie-Hellman handshake against a recipient's published identity key and a claimed one-time key.
func (*Account) PrivateKeys ¶
PrivateKeys returns the raw private key material for persistence.
func (*Account) SigningKey ¶
SigningKey is the Ed25519 public key that verifies this device's signatures.
type MegolmSession ¶
type MegolmSession struct {
// contains filtered or unexported fields
}
MegolmSession encrypts room events. The ratchet advances after every message, and recipients cannot decrypt anything sent before the session key they hold, so SessionKey must be captured before the first Encrypt.
func NewMegolmSession ¶
func NewMegolmSession() (*MegolmSession, error)
NewMegolmSession starts a session with a random ratchet.
func NewMegolmSessionFromState ¶
func NewMegolmSessionFromState(ratchet [4][]byte, counter uint32, signingPriv []byte) (*MegolmSession, error)
NewMegolmSessionFromState restores a session, which is what allows a sender to keep using one session across sends rather than re-sharing keys.
func (*MegolmSession) Encrypt ¶
func (s *MegolmSession) Encrypt(plaintext []byte) (string, error)
Encrypt returns the base64 Megolm ciphertext for a room event payload: version byte, protobuf body, truncated HMAC, then an Ed25519 signature.
The plaintext is encrypted verbatim, so callers must serialize the event exactly as upstream does or the ciphertext will not match it byte for byte. Upstream uses Python's json.dumps defaults, which put a space after every colon and comma and preserve the order the payload was built in. See MarshalEvent.
func (*MegolmSession) SessionID ¶
func (s *MegolmSession) SessionID() string
SessionID is the base64 Ed25519 public key identifying this session.
func (*MegolmSession) SessionKey ¶
func (s *MegolmSession) SessionKey() string
SessionKey is what recipients need to decrypt, shared over Olm in an m.room_key event. The trailing signature lets them confirm it came from the device that published the matching Ed25519 key.
type OlmMessage ¶
OlmMessage is the ciphertext entry of an m.olm.v1.curve25519-aes-sha2 event.
type OlmSession ¶
type OlmSession struct {
// contains filtered or unexported fields
}
OlmSession is a single-use outbound Olm session. It exists to hand one recipient device the Megolm room key, which is all a notifier ever needs to send, so it only produces pre-key (type 0) messages.
func (*OlmSession) Encrypt ¶
func (s *OlmSession) Encrypt(plaintext []byte) (OlmMessage, error)
Encrypt produces a pre-key message carrying plaintext, advancing the chain ratchet once.
func (*OlmSession) TheirIdentityKey ¶
func (s *OlmSession) TheirIdentityKey() string
TheirIdentityKey is the recipient device's Curve25519 key, which the event is addressed to.
Source Files