# What Are the Requirements for Hardware IDs in IPATool’s Signing Process

> Discover IPATool signing requirements for hardware IDs. Learn about the 1-20 byte range for non-empty byte slices to avoid signer initialization errors.

- Repository: [Majd/ipatool](https://github.com/majd/ipatool)
- Tags: deep-dive
- Published: 2026-09-06

---

**Hardware IDs in IPATool must contain between 1 and 20 bytes as a non-empty `[]byte` slice, and any value outside this range triggers immediate validation errors during SAP signer initialization.**

IPATool enforces strict constraints on hardware identifiers during its SAP (Secure Asset Protection) signing flow to ensure compatibility with Apple’s protocols. According to the `majd/ipatool` source code, the **hardware ID** functions as a unique machine fingerprint—such as a MAC address or UUID—that must conform to specific size boundaries before cryptographic operations proceed.

## Hardware ID Size Constraints

The signing process validates hardware identifiers against three core requirements checked at multiple stages of the pipeline.

### Minimum and Maximum Length Boundaries

The **hardware ID** must contain **at least 1 byte and at most 20 bytes**. The validator rejects empty (`nil` or zero-length) slices and returns an error if the size exceeds the 20-byte ceiling. This constraint prevents malformed identifiers from reaching the SAP guest environment during store agent creation.

### Binary Data Format Requirements

Identifiers are passed as raw byte slices (`[]byte`). While the underlying data can represent any unique hardware fingerprint—MAC addresses, UUIDs, or custom system hashes—the binary payload must respect the 1-20 byte limit regardless of its semantic meaning.

## Where Validation Occurs in the Source Code

IPATool implements redundant validation checks across separate packages to fail fast on invalid input.

### SAP Signer Configuration in [`signer.go`](https://github.com/majd/ipatool/blob/main/signer.go)

When constructing a new signer, the `Config` struct’s `HardwareID` field undergoes immediate scrutiny. In [`internal/sap/signer.go`](https://github.com/majd/ipatool/blob/main/internal/sap/signer.go), the constructor verifies the byte slice length and returns the error **“SAP hardware ID must contain between 1 and 20 bytes”** if the constraint is violated.

### Machine Block Creation in [`machine.go`](https://github.com/majd/ipatool/blob/main/machine.go)

Before embedding the identifier into a SAP protocol block, the helper function `hardwareBlock` in [`internal/sap/machine/machine.go`](https://github.com/majd/ipatool/blob/main/internal/sap/machine/machine.go) performs a secondary validation. This function returns **“hardware ID must contain between 1 and 20 bytes”** (lines 609-616), ensuring the ID remains valid throughout the machine information exchange sequence.

### App Store Machine ID Parsing

The file [`pkg/appstore/machine_id.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/machine_id.go) enforces identical length limits when parsing MAC-address strings for App Store-related operations, maintaining consistency across the codebase’s hardware identification logic.

## Code Examples: Valid and Invalid Hardware IDs

The following examples demonstrate compliant and non-compliant hardware ID configurations using the SAP signer.

A valid 6-byte MAC-style identifier passes validation:

```go
// Example: constructing a valid hardware ID (MAC-address style)
hwID := []byte{0x00, 0x11, 0x22, 0xaa, 0xbb, 0xcc} // 6 bytes → valid

cfg := sap.Config{
    Version:    1,
    HardwareID: hwID,
    // ... other fields ...
}

// Creating a signer will succeed because hwID satisfies the length rule.
signer, err := sap.NewSigner(cfg)
if err != nil {
    log.Fatalf("invalid hardware ID: %v", err)
}

```

An identifier exceeding 20 bytes triggers the validation error:

```go
// Example: triggering the validation error (too long)
hwID := make([]byte, 21) // 21 bytes → exceeds the maximum

cfg := sap.Config{
    Version:    1,
    HardwareID: hwID,
}

_, err := sap.NewSigner(cfg)
if err != nil {
    // Prints: SAP hardware ID must contain between 1 and 20 bytes
    fmt.Println(err)
}

```

## Summary

- **Hardware IDs** must be 1-20 bytes in length; empty or oversized values are rejected.
- Validation occurs in [`internal/sap/signer.go`](https://github.com/majd/ipatool/blob/main/internal/sap/signer.go) during signer creation and in [`internal/sap/machine/machine.go`](https://github.com/majd/ipatool/blob/main/internal/sap/machine/machine.go) via the `hardwareBlock` helper.
- The **binary format** accepts any `[]byte` payload (MAC, UUID, etc.) within the size constraints.
- Invalid IDs generate specific error messages: “SAP hardware ID must contain between 1 and 20 bytes” or “hardware ID must contain between 1 and 20 bytes”.

## Frequently Asked Questions

### What is the exact byte length limit for hardware IDs in IPATool?

The hardware ID must contain **between 1 and 20 bytes** inclusive. Values shorter than 1 byte (empty or nil) or longer than 20 bytes cause immediate validation failures with explicit error messages.

### What error message appears when the hardware ID is invalid?

The SAP signer returns **“SAP hardware ID must contain between 1 and 20 bytes”** when the `Config.HardwareID` field violates size constraints. The machine block validator returns **“hardware ID must contain between 1 and 20 bytes”** during protocol block assembly.

### Can I use a MAC address as the hardware ID?

Yes. MAC addresses (typically 6 bytes) satisfy the 1-20 byte requirement. The [`pkg/appstore/machine_id.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/machine_id.go) file specifically handles MAC-address parsing for App Store operations, confirming this format is valid for the signing process.

### At what stage does IPATool validate the hardware ID?

Validation occurs **early and redundantly**: first during `sap.NewSigner()` initialization in [`internal/sap/signer.go`](https://github.com/majd/ipatool/blob/main/internal/sap/signer.go), and again before SAP protocol transmission via the `hardwareBlock` function in [`internal/sap/machine/machine.go`](https://github.com/majd/ipatool/blob/main/internal/sap/machine/machine.go). This fail-fast approach prevents invalid identifiers from reaching downstream store agent operations.