GS2K WAC Provisioning ADK Application Note NT11590A Rev

Transcription

1 GS2K WAC Provisioning ADK Application Note 80560NT11590A Rev

2 SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE 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. COPYRIGHTS 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. COMPUTER SOFTWARE COPYRIGHTS 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 NT11590A Rev. 1.0 Page 2 of

3 USAGE AND DISCLOSURE RESTRICTIONS I. License Agreements 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. II. III. Copyrighted Materials 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 IV. High Risk Materials 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. Trademarks TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners. V. Third Party Rights 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 NT11590A Rev. 1.0 Page 3 of

4 APPLICABILITY TABLE PRODUCT GS 2K based Modules SW Version 5.2.x onwards 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 NT11590A Rev. 1.0 Page 4 of

5 Revision History Version Date Remarks 1.0 Oct, 2015 Initial release 80560NT11590A Rev. 1.0 Page 5 of

6 Table of Contents NOTICE... 2 COPYRIGHTS..2 COMPUTER SOFTWARE COPYRIGHTS... 2 USAGE AND DISCLOSURE RESTRICTIONS... 3 APPLICABILITY TABLE... 4 CHAPTER 1. INTRODUCTION SCOPE OVERVIEW TERMINOLOGY STANDARDS AND CONCEPTS...11 CHAPTER 2. FEATURES AND CAPABILITIES CHAPTER 3. THEORY OF OPERATION CHAPTER 4. ARCHITECTURE COMPONENTS Hardware Software TASKS...17 CHAPTER 5. EMBEDDED APPLICATION EXECUTION SEQUENCE BOOT UP AND INITIALIZATIONS INITIATION OF WAC PROVISIONING...22 CHAPTER 6. NATIVE APPLICATION AND EXECUTION SEQUENCE APPENDIX A WAC PROVISIONING IN S2W SDK PACKAGE NT11590A Rev. 1.0 Page 6 of

7 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 NT11590A Rev. 1.0 Page 7 of

8 List of Tables Table 1: Glossary of Terms...10 Table 2: Hardware Components...16 Table 3: Software Components NT11590A Rev. 1.0 Page 8 of

9 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 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 NT11590A Rev. 1.0 Page 9 of

10 1.3 TERMINOLOGY The following table lists different terminologies used in this document. Term AP API DIN DOUT IP SPI UART TCP UDP HTTP WAC Explanation Access Point Application Programmer s Interface Data Input Data Output Internet Protocol Serial Peripheral Interface Universal Asynchronous Receiver/Transmitter Transmission Control Protocol User Datagram Protocol Hypertext Transfer Protocol Wireless Accessory Configuration Table 1: Glossary of Terms NOTE: The term Task also means thread in this document NT11590A Rev. 1.0 Page 10 of

11 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 NT11590A Rev. 1.0 Page 11 of

12 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 Page 12 of

13 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 NT11590A Rev. 1.0 Page 13 of

14 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 Page 14 of

15 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. 1. Connection establishment Phase Figure 2: WAC Configuration Setup 80560NT11590A Rev. 1.0 Page 15 of

16 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 Hardware GainSpan WAC provisioning ADK consists of following hardware components. Component GS2011 WAC Chip LED Description GainSpan module streams Video and Audio data over Wi- Fi. This chip is responsible for generating the signature and providing X.509 certificate. These are used in Authentication process. Power ON LED. Table 2: Hardware Components 80560NT11590A Rev. 1.0 Page 16 of

17 4.1.2 Software GainSpan WAC provisioning ADK uses the following software components. Component HTTP Server WAC Engine Description 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 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 Page 17 of

18 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 Page 18 of

19 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 NT11590A Rev. 1.0 Page 19 of

20 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 o o o o o o o o o o Initializes WIF message system Initializes WIF System Control Message Handler Initializes Soft Timer Initializes File system Gives boot request to WLAN Initializes Default configuration Initializes WDD Message Handler Initializes NW stack Initializes WPA Supplicant Checks and waits for first time calibration to complete Starts NCM (for L2 and L3 connections) 2. Handles System Events o o o All the system events are handled by App_MsgProcess. These events are posted by different threads to the AppMainCtx_ThreadEntry through AppMainCtx_TaskNotify method. 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 NT11590A Rev. 1.0 Page 20 of

21 S2w_ncm.c o 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); } } } 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 Page 21 of

22 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 NT11590A Rev. 1.0 Page 22 of

23 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 Page 23 of

24 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 (_mficonfig._tcp.local) NT11590A Rev. 1.0 Page 24 of

25 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 NT11590A Rev. 1.0 Page 25 of

26 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 Page 26 of

27 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 Page 27 of

28 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 Page 28 of

29 } 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 Page 29 of

30 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 NT11590A Rev. 1.0 Page 30 of

31 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 Page 31 of

32 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 incontext, _WACState_t instate ) { err = HTTPHeaderMatchURL( incontext->httpheader, kwacurlconfig ); if ( incontext->callback ) incontext->callback( incontext, WACCallbackMessage_ConfigStart ); instate = estate_handleconfigmessage; } 80560NT11590A Rev. 1.0 Page 32 of

33 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 incontext, _WACState_t instate ) { err = RemoveWACBonjourService( incontext ); err = MFiSAP_Decrypt( incontext->mfisapref, incontext->httpheader->extradataptr, incontext->httpheader->extradatalen, decryptedconfigdata ); } err = CreateSimpleHTTPOKMessage( &httpresponse, &httpresponselen ); err = HTTPServerSend( incontext->httpserver, httpresponse, 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 NT11590A Rev. 1.0 Page 33 of

34 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 Page 34 of

35 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: NT11590A Rev. 1.0 Page 35 of

36 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 Page 36 of

37 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 NT11590A Rev. 1.0 Page 37 of

38 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 incontext, _WACState_t instate ) { err = CreateSimpleHTTPOKMessage( &httpresponse, &httpresponselen ); err = HTTPServerSend( incontext->httpserver, httpresponse, httpresponselen ); err = HTTPServerShutdownSocket( incontext->httpserver ); sem_wait( &incontext->httpserverstoppedsemaphore ); } instate = estate_complete; 80560NT11590A Rev. 1.0 Page 38 of

39 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= , , 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 NT11590A Rev. 1.0 Page 39 of

40 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 NT11590A Rev. 1.0 Page 40 of

41 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 NT11590A Rev. 1.0 Page 41 of

42 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 Page 42 of

43 The following window is displayed. Go to following folder:..\sdk\adk\wac\lib, and then select wac.a 80560NT11590A Rev. 1.0 Page 43 of

44 80560NT11590A Rev. 1.0 Page 44 of

45 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 NT11590A Rev. 1.0 Page 45 of

46 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= , , at+bdata=1 at+ncmauto=1,1,0,0 at&w NT11590A Rev. 1.0 Page 46 of

47 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 NT11590A Rev. 1.0 Page 47 of

48