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.

SEE ALSO

spec/HAP.md