gs2k wac provisioning adk application note€¦ · gs2k wac provisioning adk application note...

GS2K WAC Provisioning ADK Application Note

80560NT11590A Rev. 1.0 – 2015-10-07


80560NT11590A Rev. 1.0 of 48 2015-10-07

NOTICE

COPYRIGHTS

COMPUTER SOFTWARE COPYRIGHTS

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE

While reasonable efforts have been made to assure the accuracy of this document, Telit assumes no liability resulting from any inaccuracies or omissions in this document, or from use of the information obtained herein. The information in this document has been carefully checked and is believed to be reliable. However, no responsibility is assumed for inaccuracies or omissions. Telit reserves the right to make changes to any products described herein and reserves the right to revise this document and to make changes from time to time in content hereof with no obligation to notify any person of revisions or changes. Telit does not assume any liability arising out of the application or use of any product, software, or circuit described herein; neither does it convey license under its patent rights or the rights of others.

It is possible that this publication may contain references to, or information about Telit products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that Telit intends to announce such Telit products, programming, or services in your country.

This instruction manual and the Telit products described in this instruction manual may be, include or describe copyrighted Telit material, such as computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and its licensors certain exclusive rights for copyrighted material, including the exclusive right to copy, reproduce in any form, distribute and make derivative works of the copyrighted material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in the Telit products described in this instruction manual may not be copied, reproduced, distributed, merged or modified in any manner without the express written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit, as arises by operation of law in the sale of a product.

The Telit and 3rd Party supplied Software (SW) products described in this instruction manual may include copyrighted Telit and other 3rd Party supplied computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted computer programs, including the exclusive right to copy or reproduce in any form the copyrighted computer program. Accordingly, any copyrighted Telit or other 3rd Party supplied SW computer programs contained in the Telit products described in this instruction manual may not be copied (reverse engineered) or reproduced in any manner without the express written permission of Telit or the 3rd Party SW supplier. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit or other 3rd Party supplied SW, except for the normal non-exclusive, royalty free license to use that arises by operation of law in the sale of a product.


80560NT11590A Rev. 1.0 of 48 2015-10-07

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

II. Copyrighted Materials

III. High Risk Materials

IV. Trademarks

V. Third Party Rights

The software described in this document is the property of Telit and its licensors. It is furnished by express license agreement only and may be used only in accordance with the terms of such an agreement.

Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, without prior written permission of Telit

Components, units, or third-party products used in the product described herein are NOT fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control equipment in the following hazardous environments requiring fail-safe controls: the operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High Risk Activities.

TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners.

The software may include Third Party Right software. In this case you agree to comply with all terms and conditions imposed on you in respect of such separate software. In addition to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this License shall apply to the Third Party Right software.

TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE, INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY OR FITNESS FOR A PARTICULAR PURPOSE.

NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY, ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


80560NT11590A Rev. 1.0 of 48 2015-10-07

APPLICABILITY TABLE

Note: The features described in the present document are provided by the products equipped with the software versions equal or higher than the versions shown in the table. See also the Document History chapter.

PRODUCT

GS 2K based Modules

SW Version

5.2.x onwards


80560NT11590A Rev. 1.0 of 48 2015-10-07

Revision History

Version Date Remarks

1.0 Oct, 2015 Initial release


80560NT11590A Rev. 1.0 of 48 2015-10-07

Table of Contents

NOTICE……… ............................................................................................................................. 2

COPYRIGHTS …………………………………………………………………………………………..2

COMPUTER SOFTWARE COPYRIGHTS .................................................................................. 2

USAGE AND DISCLOSURE RESTRICTIONS ........................................................................... 3

APPLICABILITY TABLE ............................................................................................................. 4

CHAPTER 1. INTRODUCTION .................................................................................................. 9

1.1 SCOPE .............................................................................................................................9 1.2 OVERVIEW........................................................................................................................9 1.3 TERMINOLOGY ................................................................................................................10 1.4 STANDARDS AND CONCEPTS ...........................................................................................11

CHAPTER 2. FEATURES AND CAPABILITIES .................................................................... 12

CHAPTER 3. THEORY OF OPERATION ............................................................................... 13

CHAPTER 4. ARCHITECTURE .............................................................................................. 14

4.1 COMPONENTS ................................................................................................................16 4.1.1 Hardware ............................................................................................................ 16 4.1.2 Software ............................................................................................................. 17

4.2 TASKS ............................................................................................................................17 CHAPTER 5. EMBEDDED APPLICATION EXECUTION SEQUENCE ................................ 20

5.1 BOOT UP AND INITIALIZATIONS .........................................................................................20 5.2 INITIATION OF WAC PROVISIONING .................................................................................22

CHAPTER 6. NATIVE APPLICATION AND EXECUTION SEQUENCE .............................. 39

APPENDIX A WAC PROVISIONING IN S2W SDK PACKAGE .............................................. 42


80560NT11590A Rev. 1.0 of 48 2015-10-07

List of Figures

Table 1: Glossary of Terms ........................................................................................................10

Figure 1: Limited AP mode .........................................................................................................14

Figure 2: WAC Configuration Setup ...........................................................................................15

Figure 3: WAC Configuration Confirmation ................................................................................16

Table 2: Hardware Components ................................................................................................16

Table 3: Software Components ..................................................................................................17

Figure 4: Threads in WAC provisioning .....................................................................................17

Figure 5: Connection Establishment between the iDevice and WAC Accessory ......................22

Figure 6: Authentication Phase between the iDevice and WAC Accessory ..............................27

Figure 7: Configuration setup Phase between the iDevice and WAC Accessory .....................31

Figure 8: Confirmation Phase between the iDevice and WAC Accessory ................................34


80560NT11590A Rev. 1.0 of 48 2015-10-07

List of Tables

Table 1: Glossary of Terms ........................................................................................................10

Table 2: Hardware Components ................................................................................................16

Table 3: Software Components ..................................................................................................17


80560NT11590A Rev. 1.0 of 48 2015-10-07

Chapter 1. Introduction

1.1 SCOPE

This document provides an overview about the GainSpan GS2000® based WAC ( Wireless Accessory Configuration ) Provisioning Application Development Kit (ADK) and describes the software and hardware architecture, network topology, functional features, API’s, Application execution sequence of the Embedded and Mobile applications.

This document briefs about the architecture and provides with necessary information required to understand the WAC Provisioning ADK. This document assumes that the reader is generally familiar with GainSpan products, Internet Protocol (IP) networks, and the operation of 802.11 wireless devices.

1.2 OVERVIEW

GainSpan WAC Provisioning ADK is a development platform enabling customers to build products those can be easily provisioned by iOS devices.

This document is strictly compliant with the following software and hardware versions.

NOTE:

GainSpan SDK is mandatory for any development on WAC Provisioning ADK.


80560NT11590A Rev. 1.0 of 48 2015-10-07

1.3 TERMINOLOGY

The following table lists different terminologies used in this document.

Term Explanation

AP Access Point

API Application Programmer’s Interface

DIN Data Input

DOUT Data Output

IP Internet Protocol

SPI Serial Peripheral Interface

UART Universal Asynchronous Receiver/Transmitter

TCP Transmission Control Protocol

UDP User Datagram Protocol

HTTP Hypertext Transfer Protocol

WAC Wireless Accessory Configuration

Table 1: Glossary of Terms

NOTE:

The term ‘Task’ also means thread in this document.


80560NT11590A Rev. 1.0 of 48 2015-10-07

1.4 STANDARDS AND CONCEPTS

Standards

Generic standards:

• HTTP

• mDNS

•

ADK specific standard:

• WAC

Concepts

WAC stands for Wireless Accessory Configuration. This is an Apple developed technology for configuring MFi (Made for iDevices such as iPhone/iPod/iPad) devices. Apple Inc.'s MFi Program (Made for iPhone/iPod/iPad) is a licensing program for developers of hardware and software peripherals that work with Apple's iPod, iPad, and iPhone, the so-called iDevices.

https://en.wikipedia.org/wiki/Apple_Inc.

https://en.wikipedia.org/wiki/Peripheral

https://en.wikipedia.org/wiki/IPod

https://en.wikipedia.org/wiki/IPad

https://en.wikipedia.org/wiki/IPhone

https://en.wikipedia.org/wiki/IDevices


80560NT11590A Rev. 1.0 of 48 2015-10-07

Chapter 2. Features and Capabilities

This section provides the features and capabilities of GainSpan WAC Provisioning ADK.

Features:

• Multicast Domain Name System

• WAC provisioning

Capabilities:

• HTTP based provisioning


80560NT11590A Rev. 1.0 of 48 2015-10-07

Chapter 3. Theory of Operation

GainSpan’s WAC ADK allows a GainSpan module to be provisioned by an iOS device running

iOS7 or later with the GainSpan module acting as an Apple Wireless Accessory Configuration

(WAC)-compliant accessory.

It provides embedded firmware to be run on a GS2000-based module that connects the

GainSpan module to an Apple WAC chip via I2C to support the authentication needed to

provision a WAC accessory from an iOS device.


80560NT11590A Rev. 1.0 of 48 2015-10-07

Chapter 4. Architecture

The architecture of GainSpan WAC Provisioning ADK consists of three entities:

1. IPod Authentication Coprocessor (CP).

2. Accessory Controller (AC), the micro controller that is connected to the CP. In our case, it is GainSpan module.

3. iDevices such as iPod, iPad, iPhone.

•

Communication interfaces between the above three entities are as follows:

1. GainSpan module and CP will be connected via I2C interface.

2. GainSpan module and iDevices are connected via Wi-Fi interface.

NOTE:

The usage of GainSpan module and Accessory Controller is interchangeable in this document.

In WAC provisioning, the GainSpan module is in Limited AP mode.

Figure 1: Limited AP mode

On powering up the GainSpan board, the GainSpan Wi-Fi module comes up as Limited AP mode and starts the WAC HTTP Server. GainSpan module transmits Apple IE element in its beacons. iDevice displays all the devices those transmit Apple IE elements in beacons in Wi-Fi Setting page under Set up new device list category. User connects to GainSpan module by tapping on the names displayed under “SET UP NEW DEVICE” list. Tapping on this device starts the association and starts the WAC provisioning. In this process, iDevices sends mDNS request and GainSpan device provides mDSN response for WAC MFi (made for iPhone) service. Tapping on this service establishes the connection with WAC HTTP server, and exchanges the Wireless credentials of the new Access Point. GainSpan device saves these settings in the profile file and applies these saved settings in the next boot.

WAC Provisioning contains four phases:

1. Connection establishment Phase:

This explains about how iDevice associates and establishes the connection with WAC accessory.

2. Authentication Phase:


80560NT11590A Rev. 1.0 of 48 2015-10-07

This explains about authentication procedure and how configuration information is exchanged between the iDevice and WAC accessory.

3. Configuration Setup Phase:

This explains about the configuration data exchanged between the iDevice and WAC accessory.

4. Confirmation Phase:

This explains about how iDevice confirms the successful provisioning of WAC accessory with configuration setup.

The following figure shows the architecture of first three phases.

Figure 2: WAC Configuration Setup

1. Connection establishment Phase


80560NT11590A Rev. 1.0 of 48 2015-10-07

2. Authentication Phase

3. Configuration Setup Phase

The following figure shows the architecture of configuration confirmation phase.

Figure 3: WAC Configuration Confirmation

4.1 COMPONENTS

4.1.1 Hardware

GainSpan WAC provisioning ADK consists of following hardware components.

Component Description

GS2011 GainSpan module streams Video and Audio data over Wi-Fi.

WAC Chip This chip is responsible for generating the signature and providing X.509 certificate. These are used in Authentication process.

LED Power ON LED.

Table 2: Hardware Components


80560NT11590A Rev. 1.0 of 48 2015-10-07

4.1.2 Software

GainSpan WAC provisioning ADK uses the following software components.

Component Description

HTTP Server This component is responsible for creating HTTP server and accepting connections from the clients. It also serves the requests from the HTTP client. This server is responsible for serving files and URI’s.

WAC Engine WAC engine performs the following sequence of operation:

1. Creates Signature, and provides X509 certificate during Authentication.

2. Decrypts configuration data, saves it as a profile, and resets the system.

3. Confirms the successful provisioning of WAC accessory after system reset.

Table 3: Software Components

4.2 TASKS

The following task diagram show the major threads involved in WAC Provisioning ADK.

Figure 4: Threads in WAC provisioning


80560NT11590A Rev. 1.0 of 48 2015-10-07

1. WACServerEngine:

This thread has the priority of 17. State machines are implemented for handling WAC provisioning. This thread creates another thread called “HTTPServerListnerThread” as part of initialization. Following are the different states of the state machine.

1. Initialize:

• Initializes the I2C interface as master for communication with Authentication

chip.

• Prepares the beacon with Apple’s IE element.

• Creates the HTTP Server thread.

• Registers the mDNS service for MFi.

• Changes the State to WaitingForAuthSetupMessage.

2. WaitingForAuthSetupMessage:

• Waits for HTTP data on an httpHeaderReadSemaphore. This semaphore is

released by HTTP server thread on successful reception of HTTP data.

• On reception of HTTP data from the HTTP server, thread state changes to

HandleAuthSetupMessage.

3. HandleAuthSetupMessage

• Generates shared secret using HTTP data.

• Forms HTTP response with Authentication related information.

• Sends HTTP 200 OK.

• Changes state to WaitingForConfigMessage.

4. WaitingForConfigMessage

• Waits on semaphore for next message from the HTTP client.

• Changes state to HandleConfigMessage once the configuration message from

the HTTP client is received.

5. HandleConfigMessage

• Decrypts the configuration message.

• Send 200 OK response.

• Posts to Application for applying configuration and for resetting the system.

NOTE:

Subsequent to this state, the system reboots, starts in station mode, and then connects to the Access Point configured in the previous steps. Now, start the WAC Server engine with Initial state as “WaitingForConfiguredMessage”.

6. WaitingForConfiguredMessage

• Creates the HTTP Server thread.

• Registers the mDNS service for MFi.

• Waits for HTTP message from the HTTP Client

• Changes the State to WaitingForAuthSetupMessage once message is

received.

7. HandleConfiguredMessage


80560NT11590A Rev. 1.0 of 48 2015-10-07

• Checks if the URI is ‘/configured’. If yes, then sends the 200 OK response.

• Waits on semaphore “httpServerStoppedSemaphore” for HTTP client to be terminated.

• Stops the HTTP server thread.

• Changes the State to Complete.

8. Complete

• Sends the event to application, to start the WAC engine thread.

2. HTTPServerListnerThread:

This thread is blocked to accept system call for a new connection from the HTTP client and is initialized with two semaphores and one call back function.

• Both the semaphores are for handling HTTP client where one semaphore is for data reception from HTTP client and another is for Connection Termination form the HTTP client.

• Above semaphores are released from the call back function.

• On reception on any data from the HTTP client, this thread will post an event to call back, where call back releases the associated semaphore.


80560NT11590A Rev. 1.0 of 48 2015-10-07

Chapter 5. Embedded Application Execution Sequence

This section describes the complete application flow of WAC Provisioning ADK in detail along with code snippets and sniffer logs.

5.1 BOOT UP AND INITIALIZATIONS

When GEO ADK board is powered up, first AppMainCtx_ThreadEntry () [MAIN task] is started by boot rom code.

AppMainCtx_ThreadEntry (), performs all required initializations and waits on a ‘message queue’ to handle systems events.

1. GainSpan module initializations o Initializes WIF message system o Initializes WIF System Control Message Handler o Initializes Soft Timer o Initializes File system o Gives boot request to WLAN o Initializes Default configuration o Initializes WDD Message Handler o Initializes NW stack o Initializes WPA Supplicant o Checks and waits for first time calibration to complete o Starts NCM (for L2 and L3 connections)

2. Handles System Events o All the system events are handled by App_MsgProcess. o These events are posted by different threads to the AppMainCtx_ThreadEntry

through AppMainCtx_TaskNotify method. o Following are all the events defined in App_events.h

App_events.h

typedef enum APP_EVENTS

{

*

*

APP_EVENT_NCM_EXECUTE,

APP_EVENT_MDNS_EXECUTE,

*

*

APP_EVENT_MAX = 80,

} APP_EVENTS_T;

3. On successful establishment of L2, L3 processing, Network Connection Manager (NCM) is initiated under “AppS2w_NcmL3ConnProcess”. In Limited AP mode, it starts AppS2w_WacStart and starts three servers.

▪ Starts three servers

▪ Creates and starts WAC engine thread.


80560NT11590A Rev. 1.0 of 48 2015-10-07

S2w_ncm.c

PUBLIC VOID

AppS2w_NcmL3ConnProcess(APP_NW_INTERFACE_T *pInterface,

GSN_NCM_CTX_T * pNcm)

{

switch ( msg.msgId )

{

*

*

*

if(( S2W_WLANDATA_MODE_AP == pInterface->macIfType) ||

(1 == pAppRtcLtchInfo->wacCtx.isWacConfigured))

{

AppS2w_WacStart(pInterface);

}

*

*

*

}

}

o Starting WAC engine:

App_sm.c:

UINT8 AppS2w_WacStart (APP_NW_INTERFACE_T *pInterface)

{

*

*

retval = GsnWac_EngineInit(pInterface->wacCtx,

&(PAppRtcLatchMemInfo->wacCtx),

&pInterface->mdns,

pInterface->pltfrmParams);

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

5.2 INITIATION OF WAC PROVISIONING

1. Connection establishment Phase:

Following diagram shows the connection establishment sequence between the iDevice and WAC accessory.

Figure 5: Connection Establishment between the iDevice and WAC Accessory

Steps involved in connection establishment are as follows:

1. WAC accessory (GainSpan Module + Authentication Co-Processor) comes up as Limited AP and initiates WAC Engine.

2. WAC engine performs the following steps: a) Adds Apple’s IE in beacon frames b) Probes response frame.


80560NT11590A Rev. 1.0 of 48 2015-10-07

3. GainSpan module starts the HTTP server, waits for client to be connected, and registers the mDNS-service with “wac_service._mfi-config._tcp.local”

Gsn_wac.c

GSN_STATUS

GsnWac_EngineInit(GSN_WAC_CTX_T * inContext,

GSN_WAC_RTC_CTX_T* wacRtcCtx,

GSN_MDNS_T *pMdns,

GSN_WAC_PLATFORM_PARAMS_T * platParams)

{

*

*

*

GsnWac_WddCtxSet(inContext->wddCtx);

GsnWac_MdnsCtxSet(pMdns,wacRtcCtx->isWacConfigured,

inContext->wacContext->platformParams->macAddress);

return WACServerStart(inContext->wacContext,(void*)GsnWACCallBackFn);

*

*

*

}

PlatformSoftwareAccessPoint_GEPS_Stub.c:

OSStatus GsnWac_SWAPStart( const uint8_t *inIE, size_t inIELen )

{

*

*

GsnWdd_VendorSpecificIeSet(wddContext,(UINT8 *)inIE,inIELen,

GSN_WIF_WLAN_VS_IE_FRAME_TYPE_BEAC);

GsnWdd_VendorSpecificIeSet(wddContext,(UINT8 *)inIE,inIELen,

GSN_WIF_WLAN_VS_IE_FRAME_TYPE_PRB_RSP);

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

4. iDevices starts displaying the WAC accessory under Wi-Fi Settings as a “SET UP NEW DEVICE”.

5. On tapping on WAC accessory, iDevice starts the association procedure. 6. On Successful association of iDevice to the WAC accessory, iDevice starts the mDNS

query for four services. But out of four services, one is related to WAC accessory (_mfi-config._tcp.local).


80560NT11590A Rev. 1.0 of 48 2015-10-07

7. WAC accessory responds with mDNS response. This response contains information about the WAC service.

Service: wac_service Protocol: _mfi-config Name: _tcp.local Port: 5000 Seed value: 1

NOTE:

Seed value is important as it is used in Confirmation Phase.


80560NT11590A Rev. 1.0 of 48 2015-10-07

PlatformBonjour_GEPS_Stub.c:

GsnWac_MdnsSrvcReg()

{

*

*

*

UINT8 proto[] = "_tcp";

UINT8 domain[] = "local";

sprintf(deviceId, "deviceid=%02x:%02x:%02x:%02x:%02x:%02x",

macAddress[0],macAddress[1],macAddress[2],macAddress[3],macAddress[4

],macAddress[5]);

keyValAppService[0] = (UINT8 *)deviceId;

keyValAppService2[0] = (UINT8 *)deviceId;

sprintf((char *)GepsMdnsSvcSrv, "wac_service");

pParam.srvceName = (UINT8 *)GepsMdnsSvcSrv;

pParam.srvceSubType = NULL;

pParam.srvceProto = proto;

pParam.domain = domain;

UINT8 srvcType[] = "_mfi-config";

pParam.srvceType = srvcType;

pParam.port = 5000;

pParam.ttl = 4300;

GsnMdns_ServiceDeRegister(mdnsContext,&deRegParam);

retVal = GsnMdns_ServiceRegister(mdnsContext,&pParam);

*

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

8. After receiving the mDNS response, iDevice connects to the WAC server. WAC server is an HTTP server that accepts information form the iDevices.

static OSStatus _HandleState_Initialize( WACContext_t * const inContext,

_WACState_t *inState )

{

*

*

err = HTTPServerCreate( "WACPreConfigListener",

(void*)_HandleHTTPServerCallback,

(void*)inContext,

inContext->httpServer );

err = HTTPServerStart( inContext->httpServer );

*

*}

2. Authentication Phase:

The following diagram shows the Authentication procedure between the iDevice, and WAC Accessory (GainSpan Module and Authentication Coprocessors).

Figure 6: Authentication Phase between the iDevice and WAC Accessory


80560NT11590A Rev. 1.0 of 48 2015-10-07

Steps involved for Authentication Phase are as follows: 1. WAC accessory is a combination of Accessory controller (GainSpan module) and

Authentication co-processor (Apple’s WAC Chip). 2. As part of TCP communication, first iDevice performs HTTP Post of 33 bytes of data on URI

“/auth-setup”. This data contains one Byte of Authentication protocol version, and 32 bytes of Public key.

static OSStatus _HandleState_WaitingForAuthSetupMessage( WACContext_t *

const

inContext,

_WACState_t *inState

)

{

*

*

sem_wait( &inContext->httpHeaderReadSemaphore );

err = HTTPHeaderMatchURL( inContext->httpHeader, kWACURLAuth );

*inState = eState_HandleAuthSetupMessage;

*

*

}

WACServer.c:

static OSStatus _HandleState_HandleAuthSetupMessage( WACContext_t * const

inContext, _WACState_t *inState )

{

*

*

err = MFiSAP_Exchange( inContext->mfiSAPRef,

(uint8_t*)inContext->httpHeader-

>extraDataPtr,

inContext->httpHeader->extraDataLen,

&mfiSAPResponseDataPtr,

&mfiSAPResponseDataLen,

&mfiSAPComplete );

err = CreateSimpleHTTPMessage( kMIMEType_Binary,

mfiSAPResponseDataPtr,


80560NT11590A Rev. 1.0 of 48 2015-10-07

mfiSAPResponseDataLen,

&httpResponse, &httpResponseLen );

err = HTTPServerSend( inContext->httpServer, httpResponse,

httpResponseLen );

*

*

}

2. The Public key for iDevice received in the above step is used for creating the Shared Secret. Authentication message creation involves the following steps: MFiSAPServer.c

OSStatus

MFiSAP_Exchange( MFiSAPRef inRef, const uint8_t * inInputPtr,

size_t inInputLen, uint8_t ** outOutputPtr,

size_t * outOutputLen, Boolean * outDone )

{

*

*

err = __MFiSAP_Exchange_ServerM1( inRef, inInputPtr, inInputLen,

outOutputPtr, outOutputLen );

*

*

}

MFiSAPServer.c:

static OSStatus

__MFiSAP_Exchange_ServerM1(

MFiSAPRef inRef,

const uint8_t * inInputPtr,

size_t inInputLen,

uint8_t ** outOutputPtr,

size_t * outOutputLen )

{

*

*

err = PlatformRandomBytes( ourPrivateKey, sizeof( ourPrivateKey ) );

curve25519_donna( ourPublicKey, ourPrivateKey, NULL );

curve25519_donna( inRef->sharedSecret, ourPrivateKey,

clientECDHPublicKey );

SHA1_Init( &sha1Context );

SHA1_Update( &sha1Context, ourPublicKey, sizeof( ourPublicKey ) );

SHA1_Update( &sha1Context, clientECDHPublicKey, kMFiSAP_ECDHKeyLen );

SHA1_Final( digest, &sha1Context );

err = PlatformMFiAuthCreateSignature( digest, sizeof( digest ),

&signaturePtr, &signatureLen

);

err = PlatformMFiAuthCopyCertificate( &certificatePtr,

&certificateLen );

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

a) Creation of Shared Secret:

• Create the 32 Byte of random number. This will be used as Secret key.

• Create the 32 bytes of Public Key for WAC Accessory using curve25519()

method.

• Create the Shared Secret Key using Secret Key and Public Key for WAC

Accessory using curve25519().

• Create the AES-Master Key using SHA1 from the Shared Secret Key.

• Create the AES-IV Key using SHA1 from the Shared Secret Key

• Create the Hash or Digest using Public Key for WAC Accessory and

Public Key For iDevice.

• Send the I2C request to Authentication chip for computing Signature from

the Hash.

• This Signature is encrypted with AES-Master Key and AES-IV.

• Send I2C request to Authentication chip for Certificate.

b) Create the response frame in Type Length Value (TLV) format with the following

information.

• Public key for WAC Accessory, Authentication chip Certificate, and Encrypted Signature.

4. Send HTTP response of 200 OK with above created message. This message is in encrypted format.


80560NT11590A Rev. 1.0 of 48 2015-10-07

3. Configuration Setup Phase: This phase explains about the communication between the iDevice and WAC accessory. All the data exchanged between these two devices in this phase will be encrypted. At the end of this phase, WAC accessory will be reset, for setting the new configuration information.

Figure 7: Configuration setup Phase between the iDevice and WAC Accessory


80560NT11590A Rev. 1.0 of 48 2015-10-07

Steps involved for Configuration Setup Phase are as follows: 1. iDevice creates the Configuration Information Packet in TLV ( Type Length Value) format.

The data contains following information.

• Name of the Accessory identified with 0x08.

• SSID identified with 0x0C

• PSK identified with 0x0B

• Airplay password identified with 0x09

This message is encrypted with Shared Secret Key, and then sent to the WAC accessory.

2. On reception of HTTP Post, WAC accessory checks the URL. WACServer.c:

static OSStatus _HandleState_WaitingForConfigMessage( WACContext_t * const


{

*

*

err = HTTPHeaderMatchURL( inContext->httpHeader, kWACURLConfig );

if ( inContext->callback ) inContext->callback( inContext,

WACCallbackMessage_ConfigStart );

*inState = eState_HandleConfigMessage;

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

If the URL is not '/config', then discard the message and wait for next HTTP POST. If the URL is '/config', then stop mDNS service, decrypt the message, and save it in the profile. Create HTTP Response with 200 OK. WACServer.c:

static OSStatus _HandleState_HandleConfigMessage( WACContext_t * const


{

*

*

err = RemoveWACBonjourService( inContext );

err = MFiSAP_Decrypt( inContext->mfiSAPRef,

inContext->httpHeader->extraDataPtr,

inContext->httpHeader->extraDataLen,

decryptedConfigData );

err = CreateSimpleHTTPOKMessage( &httpResponse, &httpResponseLen );


httpResponseLen );

*

*

}

3. WAC accessory waits for FIN from the iDevice as soon as FIN is received and closes the

server. 4. WAC accessory saves the configuration in Profile, sets the Mode as station, and releases

the System RESET.


80560NT11590A Rev. 1.0 of 48 2015-10-07

4. Confirmation Phase:

This phase explains about the communication between the iDevice and WAC accessory upon successful setting of configuration.

Figure 8: Confirmation Phase between the iDevice and WAC Accessory


80560NT11590A Rev. 1.0 of 48 2015-10-07

Steps involved for Confirmation procedures are as follows:

1. WAC accessory (GainSpan Module + Authentication Co-processor) comes up as

Station mode, and initiates WAC Engine.

2. Start the HTTP server and wait for client to be connected. Register the mDNS-service

with “wac_service._mfi-config._tcp.local”.

3. On successful association with the configured AP, and iDevice to the WAC accessory;

iDevice starts the mDNS query for 4 services. But out of 4 services one is related to

WAC accessory ( _mfi-config._tcp.local)

4. WAC accessory responds with mDNS response. This response contains information

about the WAC service.

• Service: wac_service

• Protocol: _mfi-config

• Name: _tcp.local

• Port: 5000

• Seed value: 2


80560NT11590A Rev. 1.0 of 48 2015-10-07

WACServer.c:

static OSStatus _HandleState_WaitingForConfiguredMessage( WACContext_t *

const inContext, _WACState_t *inState )

{

*

*

err = _CreateAppleDeviceIEFromPlatformParameters(

inContext->platformParams,

&ie, &ieLen );

err = HTTPServerStart( inContext->httpServer );

sem_wait( &inContext->httpHeaderReadSemaphore );

err = HTTPHeaderMatchURL( inContext->httpHeader, kWACURLConfigured );

*inState = eState_HandleConfiguredMessage;

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

5. After receiving the mDNS response, iDevice connects to the WAC server which is an

HTTP server that accepts the information form iDevices. iDevice performs the HTTP

Post on URI “/configured”.

6. On reception of HTTP Post, WAC accessory checks the URL.

• If the URL is not '/configured, then discard the message and wait for next HTTP POST.

• If the URL is '/configured, then create HTTP response with 200 OK.


80560NT11590A Rev. 1.0 of 48 2015-10-07

WAC accessory waits for FIN from the iDevice. As soon as FIN is received, it closes its WAC server, and closes the WAC Engine.

static OSStatus _HandleState_HandleConfiguredMessage( WACContext_t * const


{

*

*

err = CreateSimpleHTTPOKMessage( &httpResponse, &httpResponseLen );


httpResponseLen );

err = HTTPServerShutdownSocket( inContext->httpServer );

sem_wait( &inContext->httpServerStoppedSemaphore );

*inState = eState_Complete;

*

*

}


80560NT11590A Rev. 1.0 of 48 2015-10-07

Chapter 6. Native Application and Execution Sequence

This section describes how mobile application works along with WAC Provisioning ADK. There is no specific mobile application for WAC provisioning. All Apple devices will have these settings enabled in its settings page.

Steps performed for the demo:

1. Flash the GainSpan module with WAC provisioning enabled binary. The demo uses Serial to WiFi Application as an example.

2. Execute the following commands to configure the GainSpan module for enabling WAC provisioning.

at+nmac=?

at+wm=2

at+wauto=2,wac-demo,,6

at+apconf=1

at+wauth=0

at+wsec=0

at+nset=192.168.8.1,255.255.255.0,192.168.8.1

at+bdata=1

at+ncmauto=1,1,0,0

at&w0

3. After this setup, GainSpan module starts sending beacons with Apple IE element.

4. Go to setting page -> Wi-Fi settings under “SETUP NEW DEVICE” the GainSpan device will be seen.


80560NT11590A Rev. 1.0 of 48 2015-10-07

5. Tapping on this Accessory starts the association process and then starts querying Apple service using mDNS. Accessory name will be displayed on this page; iDevice will get this name using mDNS.

6. Tapping on Next will start the Authentication process and Configuration information

exchange.


80560NT11590A Rev. 1.0 of 48 2015-10-07

7. GainSpan module applies the configuration setup and resets the system. In the next boot up, it waits for connecting to a new Access Point using configuration information. I-Device waits for GainSpan module to come in i-Device’s connected network.

8. On successful association of GainSpan accessory with configured Access Point,

success message is sent to the i-Device.


80560NT11590A Rev. 1.0 of 48 2015-10-07

Appendix A WAC Provisioning in S2W SDK Package

Perform the following steps to enable WAC provisioning in S2W SDK package:

Step 1: Add the “wac.a” library to the Project.

Right click on project file Add Click Add Files


80560NT11590A Rev. 1.0 of 48 2015-10-07

The following window is displayed.

Go to following folder: ..\SDK\adk\wac\lib , and then select wac.a


80560NT11590A Rev. 1.0 of 48 2015-10-07


80560NT11590A Rev. 1.0 of 48 2015-10-07

Step2: Add following macros under Defined symbols.

• ADK_WAC_ENABLED

• S2W_WAC_SUPPORT

• TARGET_RT_LITTLE_ENDIAN

• WAC_GEPS

NOTE:

The features that are not required are removed or disabled.


80560NT11590A Rev. 1.0 of 48 2015-10-07

Following flags are not related to WAC provisioning and can be removed from the workspace:

S2W_GSLINK

S2W_GSLINK_RAW

S2W_GSLINK_XML

S2W_GSLINK_XMLNESTED_PARSER

S2W_RF_TEST

S2W_CONCURRENT_MODE

S2W_ADC_SUPPORT

S2W_P2P_ENABLE

S2W_COAP_SUPPORT

Test commands:

Once the WAC features is enabled and as soon as the NCM is started, WAC provisioning is automatically enabled. There is no command to be start WAC provisioning (there will be commands for starting the WAC provisioning in future).

at+nmac=?

at+wm=2

at+wauto=2,wac-demo,,6

at+apconf=1

at+wauth=0

at+wsec=0

at+nset=192.168.8.1,255.255.255.0,192.168.8.1

at+bdata=1

at+ncmauto=1,1,0,0

at&w0


80560NT11590A Rev. 1.0 of 48 2015-10-07

How can we confirm WAC is enabled?

If WAC provisioning is enabled, the following message is seen in Tera Term after NCM Connection is successful.

This can also be checked using Wireshark sniffer or Apple devices. Before checking, make sure

that NCM auto commands display the above highlighted text in the Tera Term log.

gs2k wac provisioning adk application note€¦ · gs2k wac provisioning adk application note...

Documents