OpenHAP::PIN(3p) Perl Library Manual OpenHAP::PIN(3p)

OpenHAP::PIN - HomeKit Accessory Protocol PIN validation and normalization

    use OpenHAP::PIN qw(normalize_pin validate_pin);
    # Normalize PIN (strip dashes/spaces)
    my $normalized = normalize_pin('1234-5678');  # Returns '12345678'
    my $normalized = normalize_pin('1234 5678');  # Returns '12345678'
    my $normalized = normalize_pin('12345678');   # Returns '12345678'
    # Validate PIN
    if (validate_pin('1234-5678')) {
        print "Valid PIN\n";
    }
    if (!validate_pin('12345678')) {
        print "Invalid PIN (sequential pattern)\n";
    }

This module provides utilities for handling HomeKit Accessory Protocol (HAP) setup codes (PINs). PINs are 8-digit numeric codes used during the pairing process.

Per the HAP specification, dashes and spaces in PINs are formatting characters only and are stripped before use. The PIN "1234-5678" is equivalent to 12345678.

Normalizes a PIN by stripping dashes and spaces, returning the 8-digit numeric string.

    my $normalized = normalize_pin('1234-5678');
    # Returns: '12345678'

Returns "undef" if the input is not a valid format (not exactly 8 digits after normalization).

Validates a PIN meets HAP requirements:

  • Must be exactly 8 digits (after stripping dashes/spaces)
  • Must not be a trivial or sequential pattern

Returns 1 if valid, "undef" if invalid.

    if (validate_pin('1234-5678')) {
        # PIN is valid
    }

The following PINs are invalid per the HAP specification:

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

These patterns are too simple and pose a security risk.

PINs may be formatted with dashes for readability:

  • Format: "XXXX-XXXX" where X is a digit 0-9
  • Examples: "1234-5678", "9876-5432"
  • Dashes are optional and stripped during processing

The canonical format used in configuration files and displays is "XXXX-XXXX", but the underlying 8-digit number is what matters for validation and cryptographic operations.

  • Never use default or example PINs in production
  • Generate random PINs that are not trivial patterns
  • Store PINs securely with appropriate file permissions
  • Consider displaying PINs only on secure channels (local console)

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

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

2026-07-27 OpenBSD