NAME

Protocol::HAP::Store - the persistence contract of Protocol::HAP

DESCRIPTION

"Protocol::HAP" owns no files. Everything a paired accessory must remember goes through a store object that the host injects. Any object with the twelve methods below satisfies the contract. Protocol::HAP::Store::Memory is the reference implementation; Protocol::HAP::Store::File is the durable implementation over files.

THE INCREMENT RULE

The configuration number "c#" tells a controller that the accessory database changed. The mutating pairing methods - "save_pairing", "remove_pairing", and "remove_all_pairings" - increment the configuration number themselves.

This rule has no slack. A store that skips the increment hides pairing changes from controllers. An engine that adds an increment on top counts every change twice. Both break "c#", in opposite directions.

METHODS

load_accessory_keys()

Return the long-term identity as the list "($ltsk, $ltpk)": the Ed25519 secret and public key. Return the empty list when no identity is stored yet; the engine then generates one and saves it.

save_accessory_keys($ltsk, $ltpk)

Store the long-term identity. The secret key is the identity of the accessory: a durable store must never let it become readable by another user.

load_pairings()

Return every pairing as a hash reference keyed by controller id. Each value is a hash reference with "ltpk" (the controller's Ed25519 public key, raw bytes) and "permissions" (1 for an admin, 0 for a regular controller).

save_pairing($controller_id, $ltpk, $permissions)

Add or replace one pairing, then increment the configuration number. $permissions defaults to 1.

remove_pairing($controller_id)

Remove one pairing, then increment the configuration number. Removing an unknown id is not an error.

remove_all_pairings()

Remove every pairing, then increment the configuration number. This is the factory reset that follows the removal of the last admin.

get_config_number()

Return the configuration number. The value starts at 1 and only ever goes up: a controller that sees it go backwards drops the accessory and pairs again.

increment_config_number()

Add one to the configuration number and return the new value.

get_config_digest()

Return the stored digest of the accessory structure, or "undef" when none is stored. The engine compares it against the current structure to decide whether "c#" must move.

save_config_digest($digest)

Store the digest of the accessory structure.

get_auth_attempts()

Return the count of failed pairing attempts. Return 0 when none is stored. The limit of 100 failed attempts survives restarts through this counter.

set_auth_attempts($count)

Store the count of failed pairing attempts.