APPLE CONFIDENTIAL

Abstract

This document describes the Apple Wireless Accessory Configuration (WAC) POSIX source code release. It is intended for developers who are planning to port the Wireless Accessory Configuration project to their platform. This document covers the project contents, an overview of the porting procedure, relevant API details and sample implementations.

Glossary

WAC

Apple Wireless Accessory Configuration

Accessory

Device being configured

AP

Wireless Access Point [REF4]

IE

802.11 Information Element

Apple Device IE

IE defined by Apple for use in discovering accessories via Wi-Fi

POSIX

Portable Operating System Interface [REF3]

Bonjour

Apple’s zero-configuration network discovery technology [REF1]

mDNSResponder

Open Source Bonjour implementation [REF2]

TXT Record

DNS record for additional metadata associated with a DNS service

MFi

Apple’s Made for iPhone/iPod/iPad licensing program

MFi-SAP

MFi Secure Association Protocol

1. Project Contents

1.1. Directory Structure Overview

.
├── Documentation
│   └── index.html
├── External
│   ├── Curve25519
│   │   ├── curve25519-donna-c64.c
│   │   ├── curve25519-donna-test.c
│   │   ├── curve25519-donna.c
│   │   └── curve25519-donna.h
│   └── GladmanAES
│       ├── aes.h
│       ├── aes_modes.c
│       ├── aes_via_ace.h
│       ├── aescrypt.c
│       ├── aeskey.c
│       ├── aesopt.h
│       ├── aestab.c
│       ├── aestab.h
│       ├── brg_endian.h
│       ├── brg_types.h
│       ├── gcm.c
│       ├── gcm.h
│       ├── gf128mul.c
│       ├── gf128mul.h
│       ├── gf_mul_lo.h
│       └── mode_hdr.h
├── Makefile
├── Platform
│   ├── Platform.include.mk
│   ├── PlatformApplyConfiguration.h
│   ├── PlatformBonjour.h
│   ├── PlatformLogging.h
│   ├── PlatformMFiAuth.h
│   ├── PlatformRandomNumber.h
│   └── PlatformSoftwareAccessPoint.h
├── README.txt
├── Sources
│   ├── Common.h
│   ├── WACBonjour.c
│   ├── WACBonjour.h
│   ├── WACLogging.h
│   ├── WACServer.c
│   ├── WACServerAPI.h
│   ├── WACServerVersion.h
│   └── WACTLV.h
└── Support
    ├── AESUtils.c
    ├── AESUtils.h
    ├── AppleDeviceIE.c
    ├── AppleDeviceIE.h
    ├── Debug.h
    ├── HTTPServer.c
    ├── HTTPServer.h
    ├── HTTPUtils.c
    ├── HTTPUtils.h
    ├── MFiSAPServer.c
    ├── MFiSAPServer.h
    ├── SHAUtils.c
    ├── SHAUtils.h
    ├── SecurityUtils.c
    ├── SecurityUtils.h
    ├── SocketUtils.c
    ├── SocketUtils.h
    ├── StringUtils.c
    ├── StringUtils.h
    ├── TLVUtils.c
    ├── TLVUtils.h
    ├── TimeUtils.c
    ├── TimeUtils.h
    ├── URLUtils.c
    └── URLUtils.h

1.2. Directory Structure Details

Documentation/

Directory containing documentation

Makefile

WAC Makefile

Sources/

Directory containing the Apple WAC source files

Sources/WACServerAPI.h

The main header file and interface into the WAC source files

Support/

Directory containing supporting source files for the WAC project

External/

Directory containing external projects

Platform/

Directory containing the platform specific headers

2. Porting Overview

NOTE:
The developer should only modify and/or add source in the Platform directory.

  1. Setup a platform specific toolchain

    Set up the compiler, linker, and any other tools needed to compile the source code for the intended target platform.

  2. Port Bonjour

    WAC requires the Bonjour stack to operate. Please refer to the Bonjour page of Apple’s Developer portal [REF2] for more information on porting Bonjour to your platform.

  3. Update platform include makefile

    Update the example Platform.include.mk file to provide information regarding the toolchain, library paths, include paths etc. Refer to the Platform.include.mk file in the Platform directory for more details.

  4. Complete the implementation of the platform interfaces required by Wireless Accessory Configuration

    Implement the interfaces required by WAC on top of the OS/Platform specific APIs of the target. Relevant comments, functions and examples have been tagged with PLATFORM_TO_DO keyword.

  5. Build Wireless Accessory Configuration and the platform implementation

    Build WAC and the platform implementation for the target platform using the make command below. This will compile and link the WAC code with the platform implementation.

make platform_makefile=<path_to_Platform.include.mk>

NOTE:
WAC must run in its own process on your target platform.

3. Interfaces

This section lists the various interfaces required/provided by the Wireless Accessory Configuration source code.

3.1. Interfaces Overview

Table 1. Called from developer code into WAC source
Interface Header Documentation Header File Purpose

WAC Server Interface

WACServerAPI.h

APIs called by the platform application to control the WAC Server

Table 2. Called from WAC source into developer code
Interface Header File Purpose

Software Access Point Interface

PlatformSoftwareAccessPoint.h

APIs called by WAC to setup the platform’s Software Access Point

Apply Configuration Interface

PlatformApplyConfiguration.h

APIs called by WAC to apply the received configuration information

Random Number Interface

PlatformRandomNumber.h

APIs called by WAC for random numbers

Bonjour Interface

PlatformBonjour.h

APIs called by WAC to control bonjour on the platform

Apple Authentication Coprocessor Interface

PlatformMFiAuth.h

APIs called by WAC for MFi SAP purposes

POSIX Interface

POSIX compliant APIs called by WAC for OS, network & standard library purposes

3.2. Interface Details

3.2.1. Software Access Point Interface

The Software Access Point interface is responsible for controlling the platform’s access point functionality, namely, starting and stopping the interface and its dependencies. The platform Software Access Point implementation must include a DHCP server so that the client device can join the accessory’s AP and send the configuration information to the accessory.

3.2.2. Apply Configuration Interface

The Apply Configuration interface is responsible for conveying the new configuration information received from the WAC client. The following configuration information can be received:

  • The SSID of the Wi-Fi network to join

  • The passcode of the Wi-Fi network to join

  • The new accessory name

  • The new accessory AirPlay play password

These values should be stored in persistent memory and used for the accessory’s configuration until the accessory’s configuration is reset.

NOTES:

  • The platform must not reboot when switching from software access point mode to station mode.

  • The platform must be capable of joining link local IPv4 networks.

  • The platform must be capable of joining IPv6 networks.

  • The platform must be capable of joining link local IPv6 networks.

  • The platform must be compatible with UTF-8 strings. [REF8]

3.2.3. Random Number Interface

Random numbers are used for the cryptographic key exchange. All random numbers are requested through a single API which must generate cryptographic random numbers (e.g. can’t use ANSI rand(), POSIX random(), etc.). If there is not enough entropy to satisfy the request, it must block until sufficient entropy is available.

3.2.4. Bonjour Interface

The Bonjour interface allows the WAC source to inform the platform when it needs to use mDNSResponder. If the WAC source asks that the platform start mDNSResponder and it is already running, then it should return with success. Similarly if the WAC source asks that the platform stop mDNSResponder but other threads and/or processes are using it, the platform should keep it alive and return success.

3.2.5. Apple Authentication Coprocessor Interface

All Wireless Accessory Configuration accessories are required to have an Apple Authentication Coprocessor so that the client may authenticate and set up an encrypted communication channel with the accessory. The authentication and encryption protocol is provided as portable code that should work on any platform, however, access to the Apple Authentication Coprocessor is different for each platform. The functions containted in this interface need to be implemented to provide access to the Apple Authentication Coprocessor.

Tips for interacting with the Apple Authentication Coprocessor
It is important to implement a robust error detection and retry scheme when interacting with the coprocessor over the I2C interface. See the following sections of the Apple Authentication Coprocessor documentation for more information:

  • NACK Responses Replace Clock Stretching

  • Automatic Sleep State Entry and Exit

3.2.6. POSIX Interface

Refer to the list of Project Dependencies for details on what POSIX interfaces are used.

3.3. List of Project Dependencies

DNSServiceRefDeallocate( )
DNSServiceRegister( )
PlatformApplyAirPlayPlayPassword( )
PlatformApplyName( )
PlatformCryptoStrongRandomBytes( )
PlatformInitializemDNSResponder( )
PlatformJoinDestinationWiFiNetwork( )
PlatformMFiAuthCopyCertificate( )
PlatformMFiAuthCreateSignature( )
PlatformMFiAuthFinalize( )
PlatformMFiAuthInitialize( )
PlatformMayStopmDNSResponder( )
PlatformSoftwareAccessPointStart( )
PlatformSoftwareAccessPointStop( )
TXTRecordCreate( )
TXTRecordDeallocate( )
TXTRecordGetBytesPtr( )
TXTRecordGetLength( )
TXTRecordSetValue( )
accept( )
bind( )
calloc( )
close( )
exit( )
fcntl( )
free( )
getsockname( )
listen( )
main( )
malloc( )
memcmp( )
memcpy( )
memmove( )
perror( )
pipe( )
printf( )
puts( )
read( )
select( )
socket( )
strlen( )
strnlen( )
write( )
sem_init( )
sem_destroy( )
sem_wait( )
sem_post( )

4. External Source

Some of the following open source projects have been included in the WAC source release. Any modifications to the source are described in the following sections.

4.1. Bonjour

Bonjour [REF1] is Apple’s implementation of zero-configuration networking which enables automatic discovery of devices and services on a local network using industry standard IP protocols. WAC uses Bonjour for its accessory discovery purposes and links to the libdns library. The developer should port mDNSResponder (Apple’s bonjour implementaion), which is available as Open Source, to the accessory platform.

4.2. GladmanAES

The WAC Source Release contains a modified version (External/GladmanAES/) of the GladmanAES [REF6] Open Source project for its encryption/decryption purposes. The following modifications have been made to the project to better suit the needs of WAC:

  • Added support for in-place encrypt/decrypt.

  • Added support for working without ACE support.

  • Fixes for endian detection.

  • Fixes for compiling on different compilers, 64-bit, etc.

  • Fixes for warnings.

4.3. Curve25519

The WAC Source Release contains a modified version (External/Curve25519/) of the Curve25519 [REF7] Open Source project for its Public Key purposes. The following modifications have been made to the Open Source release of Curve25519 to better suit the needs of WAC:

  • Added default basepoint.

  • Fixes for misaligned access.

  • Fixes for compiling on different compilers, 64-bit, etc.

  • Fixes for warnings.

5. References