e2ee

Documentation

Overview

Package e2ee implements tyo-mq's end-to-end encrypted payload suite ecdh-es-p256-a256gcm (see E2EE.md in the tyo-mq repo): ephemeral-static ECDH on P-256 → HKDF-SHA256 → AES-256-GCM, with the cleartext routing (event, to, from) bound into the AAD so a sealed payload cannot be cut-and-pasted onto a different envelope.

This is the byte-for-byte contract shared by every tyo-mq client language; conformance is pinned by the committed vectors (tests/e2ee-vectors.json in the tyo-mq repo, mirrored here in testdata/).

Index

• Constants
• func AAD(event, to, from string) []byte
• func DeriveKey(sharedX []byte, kid string) ([]byte, error)
• func GenerateKeyPair() (priv, pub []byte, err error)
• func Open(myPriv []byte, enc *Enc, event, to, from, message string) ([]byte, error)
• func PublicKeyFromPrivate(priv []byte) ([]byte, error)
• type Enc
  • func Seal(recipientPub []byte, event, to, from string, plaintext []byte, kid string) (*Enc, string, error)

Constants

const ALG = "ecdh-es-p256-a256gcm"

ALG is the only suite currently defined.

Functions

func AAD

func AAD(event, to, from string) []byte

AAD builds the additional authenticated data binding a ciphertext to its cleartext routing. Bytes: event "\n" to "\n" from.

func DeriveKey

func DeriveKey(sharedX []byte, kid string) ([]byte, error)

DeriveKey turns the ECDH shared X-coordinate into the AES-256 key. HKDF-SHA256 (RFC 5869), empty salt, info = "tyo-mq-e2ee-v1:<alg>:<kid>". Inlined rather than depending on crypto/hkdf (Go 1.24+) so the module stays dependency-free on Go 1.22.

func GenerateKeyPair

func GenerateKeyPair() (priv, pub []byte, err error)

GenerateKeyPair returns a fresh P-256 keypair as raw bytes: a 32-byte private scalar and a 65-byte uncompressed public point.

func Open

func Open(myPriv []byte, enc *Enc, event, to, from, message string) ([]byte, error)

Open reverses Seal with the recipient's raw 32-byte private scalar. It returns the plaintext, or an error on a bad tag / AAD / key / envelope.

func PublicKeyFromPrivate

func PublicKeyFromPrivate(priv []byte) ([]byte, error)

PublicKeyFromPrivate derives the uncompressed public point from a raw 32-byte private scalar.

Types

type Enc

type Enc struct {
	V   int    `json:"v"`
	Alg string `json:"alg"`
	Epk string `json:"epk"` // base64 uncompressed P-256 point (65 bytes)
	IV  string `json:"iv"`  // base64 12-byte GCM nonce
	Kid string `json:"kid"` // recipient key id the sender encrypted to
}

Enc is the encryption envelope carried alongside the (now ciphertext) message field: {v, alg, epk, iv, kid}.

func Seal

func Seal(recipientPub []byte, event, to, from string, plaintext []byte, kid string) (*Enc, string, error)

Seal encrypts plaintext to the recipient's static public key (65-byte uncompressed P-256 point). It returns the enc envelope and the base64 ciphertext||tag that replaces the message field on the wire.