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
Directory containing documentation |
|
WAC Makefile |
|
Directory containing the Apple WAC source files |
|
The main header file and interface into the WAC source files |
|
Directory containing supporting source files for the WAC project |
|
Directory containing external projects |
|
Directory containing the platform specific headers |
2. Porting Overview
-
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.
-
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.
-
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.
-
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_DOkeyword. -
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>
3. Interfaces
This section lists the various interfaces required/provided by the Wireless Accessory Configuration source code.
3.1. Interfaces Overview
| Interface Header Documentation | Header File | Purpose |
|---|---|---|
APIs called by the platform application to control the WAC Server |
| Interface | Header File | Purpose |
|---|---|---|
APIs called by WAC to setup the platform’s Software Access Point |
||
APIs called by WAC to apply the received configuration information |
||
APIs called by WAC for random numbers |
||
APIs called by WAC to control bonjour on the platform |
||
APIs called by WAC for MFi SAP purposes |
||
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.
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.
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
-
[REF0] Apple Developer,
http://developer.apple.com/ -
[REF1] Bonjour - Apple Developer,
http://developer.apple.com/bonjour/ -
[REF2] mDNSResponder open source releases,
http://www.opensource.apple.com/tarballs/mDNSResponder/ -
[REF3] POSIX - Portable Operating System Interface,
http://en.wikipedia.org/wiki/POSIX -
[REF4] Wireless Access Point,
http://en.wikipedia.org/wiki/Wireless_access_point -
[REF5] Software Access Point,
http://en.wikipedia.org/wiki/SoftAP -
[REF6] GladmanAES,
http://gladman.plushost.co.uk/oldsite/AES/ -
[REF7] Curve25519-donna,
https://code.google.com/p/curve25519-donna/ -
[REF8] UTF-8,
http://en.wikipedia.org/wiki/UTF-8