NAME

Protocol::HAP::SetupCode - the rules of the HomeKit setup code

SYNOPSIS

use Protocol::HAP::SetupCode qw(normalize_setup_code validate_setup_code);

# Normalize a setup code (remove dashes and spaces)
my $normalized = normalize_setup_code('9876-5432');  # Returns '98765432'
my $normalized = normalize_setup_code('9876 5432');  # Returns '98765432'
my $normalized = normalize_setup_code('98765432');   # Returns '98765432'

# Validate a setup code
if (validate_setup_code('9876-5432')) {
    print "Valid setup code\n";
}

if (!validate_setup_code('1234-5678')) {
    print "Invalid setup code (sequential pattern)\n";
}

DESCRIPTION

This module handles HAP setup codes: the 8-digit numeric codes that pairing uses. The specification calls them setup codes [HAP-Pairing §2], so no name here uses the word it replaced.

The HAP specification says that dashes and spaces are format characters only. The module removes them before use. Thus 9876-5432 and 98765432 are the same setup code.

FUNCTIONS

normalize_setup_code($code)

This function removes the dashes and the spaces from a setup code. It returns the 8-digit numeric string.

my $normalized = normalize_setup_code('9876-5432');
# Returns: '98765432'

The function returns undef if the input format is not valid. A valid input has exactly 8 digits after normalization.

validate_setup_code($code)

This function does a check of a setup code against these HAP requirements:

• The code must have exactly 8 digits after the removal of the dashes and the spaces.

• The code must not be a trivial or sequential pattern.

The function returns 1 if the setup code is valid. It returns undef if the setup code is not valid.

if (validate_setup_code('9876-5432')) {
    # the setup code is valid
}

INVALID SETUP CODES

The HAP specification rejects these setup codes:

00000000  11111111  22222222  33333333  44444444
55555555  66666666  77777777  88888888  99999999
12345678  87654321

SEE ALSO

Protocol::HAP::SRP, Protocol::HAP::Pairing, openhapd.conf(5), spec/HAP-Pairing.md

STANDARDS

HomeKit Accessory Protocol Specification (Non-Commercial Version) Release R2, Section 5.6: Setup Code