corev1ref

Documentation

Overview

Package corev1ref is the reference implementation of the hotline core-v1 protocol primitives (protocol/core-v1/SPEC.md): the e1 E2E envelope (HKDF-SHA256 key derivation + XChaCha20-Poly1305 AEAD) and the signed control-plane header scheme (P-256 ECDSA / SHA-256, canonical string, mandatory low-S).

This package exists to generate and validate the golden fixtures under protocol/core-v1/fixtures/. It is normative for byte layout: WP1 (worker), WP2 (box) and WP3 (app) implementations MUST reproduce these bytes exactly. No production code imports it.

Index

• Constants
• func AAD(room, dir string) ([]byte, error)
• func AuthHash(roomAuth []byte) string
• func CanonicalString(method, path, timestamp, nonce string, body []byte) string
• func DecodeSecret(s string) ([]byte, error)
• func HighSTwin(sigB64 string) (string, error)
• func KeyFromScalar(dB64 string) (*ecdsa.PrivateKey, error)
• func Open(key []byte, n, c string, aad []byte) ([]byte, error)
• func ScalarB64(v *big.Int) string
• func Seal(key, nonce, aad, plaintext []byte) (n, c string, err error)
• func SignLowS(priv *ecdsa.PrivateKey, data []byte) (string, error)
• func VerifyLowS(pub *ecdsa.PublicKey, data []byte, sigB64 string) error
• type Keys
  • func DeriveKeys(secret []byte) (Keys, error)

Constants

const (
	InfoB2A      = "hotline-e2e-v1|b2a"
	InfoA2B      = "hotline-e2e-v1|a2b"
	InfoRoomAuth = "hotline-room-auth-v1"
)

Info labels (SPEC §2.3). The '|' is a literal byte in the label.

Functions

func AAD

func AAD(room, dir string) ([]byte, error)

AAD builds the additional authenticated data string for an e1 frame: ASCII "hotline/e1|<room>|<dir>", dir ∈ {"b2a","a2b"} (SPEC §2.2).

func AuthHash

func AuthHash(roomAuth []byte) string

AuthHash is base64url(SHA-256(room_auth)) — the only derivation-related value the core ever sees (SPEC §2.3, §3.2).

func CanonicalString

func CanonicalString(method, path, timestamp, nonce string, body []byte) string

CanonicalString joins the five signed fields with single '\n', no trailing newline: METHOD, path, timestamp (unix s decimal), nonce, base64url(SHA-256(exact body bytes)).

func DecodeSecret

func DecodeSecret(s string) ([]byte, error)

DecodeSecret base64url-decodes the 43-char pairing secret into its 32 raw bytes.

func HighSTwin

func HighSTwin(sigB64 string) (string, error)

HighSTwin returns the malleable high-S twin of a valid low-S signature (s' = n - s), used by fixtures to assert the reject path.

func KeyFromScalar

func KeyFromScalar(dB64 string) (*ecdsa.PrivateKey, error)

KeyFromScalar rebuilds a P-256 private key from a base64url 32-byte scalar (the fixture key), recomputing the public point.

func Open

func Open(key []byte, n, c string, aad []byte) ([]byte, error)

Open decrypts an e1 frame body (base64url n and c) back to the inner frame bytes. Any failure (bad encoding, wrong key, wrong AAD, tampered bytes) returns an error; per SPEC §2.2 the receiver drops the frame.

func ScalarB64

func ScalarB64(v *big.Int) string

ScalarB64 encodes a curve coordinate/scalar as base64url of its fixed 32-byte big-endian form (JWK x/y/d encoding).

func Seal

func Seal(key, nonce, aad, plaintext []byte) (n, c string, err error)

Seal encrypts one inner v2 frame (its exact UTF-8 JSON bytes) into an e1 frame body using XChaCha20-Poly1305 with the given 24-byte nonce and AAD. It returns the JSON values for "n" and "c" (base64url, no padding).

func SignLowS

func SignLowS(priv *ecdsa.PrivateKey, data []byte) (string, error)

SignLowS signs SHA-256(data) with ECDSA P-256 and returns base64url (no padding) of the 64-byte r||s signature with s normalized to low-S (s <= n/2), exactly as internal/app/pushsign.go signLowS.

func VerifyLowS

func VerifyLowS(pub *ecdsa.PublicKey, data []byte, sigB64 string) error

VerifyLowS verifies a base64url 64-byte r||s signature over SHA-256(data), rejecting high-S signatures (the core's verify rule: WebCrypto verify plus an explicit low-S check).

Types

type Keys

type Keys struct {
	KB2A     []byte // box→app content key
	KA2B     []byte // app→box content key
	RoomAuth []byte // future device-direct auth (§8.1); only its hash leaves the pair
}

Keys holds the three 32-byte HKDF outputs derived from the pairing secret.

func DeriveKeys

func DeriveKeys(secret []byte) (Keys, error)

DeriveKeys runs the three HKDF-SHA256 derivations of SPEC §2.3 over the raw 32-byte secret. salt = ASCII "hotline-e1" for all three; only info differs.