NAME

Protocol::HAP - HomeKit Accessory Protocol library

SYNOPSIS

    use Protocol::HAP;
    my $logger = Protocol::HAP->null_logger;

DESCRIPTION

"Protocol::HAP" is the HomeKit Accessory Protocol as a host-neutral library. It holds the complete protocol: the TLV8 codec, the setup-code rules, the crypto primitives, SRP-6a, the pairing and session state machines, the accessory data model, the sans-IO accessory-server engine, and a controller.

The library is self-contained. It uses core Perl plus four declared CPAN modules: Crypt::Ed25519, Crypt::Curve25519, Crypt::KeyDerivation, and Crypt::AuthEnc::ChaCha20Poly1305. The crypto modules load lazily, on first use.

The engine is sans-IO. It consumes bytes and emits bytes. The host owns sockets, timers, logging, and persistence. Three documented exceptions exist: "Protocol::HAP::Crypto" reads /dev/urandom, "Protocol::HAP::Controller" is a blocking convenience client that owns its socket, and "Protocol::HAP::Store::File" writes the store contract to files. None of the three is the engine, which is the class the sans-IO rule describes.

HOST CONTRACTS

A host injects its environment through five constructor arguments.

logger: An object with "debug", "info", "warning", and "error" methods that take printf-style arguments. The default is the null logger from this module. An object passes its logger to the objects it creates itself.
store: An object with the twelve persistence methods that Protocol/HAP/Store.pod documents. "Protocol::HAP::Store::Memory" is the reference implementation, and "Protocol::HAP::Store::File" is the durable one.
output: A code reference "sub ($session, $bytes)". The engine sends every write through it: responses and EVENT notifications alike.
after and cancel: Code references for one-shot timers, used for event coalescing. They are optional: without them, the host calls "flush_events" itself.
on_pairing_changed: An optional code reference "sub ($paired)". The engine calls it when the paired state flips, so the host can re-advertise its mDNS TXT record.

METHODS

Protocol::HAP->null_logger

This method returns the shared null logger. The null logger answers the four logger methods and drops every message.

FUNCTIONS

uuid_to_short($uuid)

This function converts a full UUID to the short form for JSON. It returns a short hex string for Apple-defined UUIDs and the full UUID for custom ones. The data model and the server share this one copy of the rule.

device_id($ltpk)

This function returns the MAC-format device id of an accessory: the first six bytes of the long-term public key, as uppercase colon-separated hex. The server advertises it and pair-setup signs over it.

MODULES

Protocol::HAP::TLV - TLV8 codec
Protocol::HAP::SetupCode - setup-code normalization and rules
Protocol::HAP::Crypto - randomness and crypto primitives
Protocol::HAP::SRP - SRP-6a exchange
Protocol::HAP::Accessory - accessory data model
Protocol::HAP::Service - service data model
Protocol::HAP::Characteristic - characteristic data model
Protocol::HAP::Bridge - bridge accessory
Protocol::HAP::Pairing - pair-setup and pair-verify state machines
Protocol::HAP::Session - per-connection state and the AEAD frame codec
Protocol::HAP::Store::Memory - the reference store implementation
Protocol::HAP::Store::File - the durable store over files
Protocol::HAP::HTTP - the HTTP/1.1 subset codec, EVENT/1.0 builder
Protocol::HAP::Server - the sans-IO accessory-server engine
Protocol::HAP::Controller - the blocking controller client

The store contract itself lives in Protocol/HAP/Store.pod. The controller role of SRP lives beside the accessory role, as "Protocol::HAP::SRP::Client" in the same file.