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.
SEE ALSO
Protocol::HAP, Protocol::HAP::Store::Memory, Protocol::HAP::Store::File, Protocol::HAP::Pairing, spec/HAP-Pairing.md