Providing Mobile Broadband Metadata

Providing Mobile Broadband Metadata May 31, 2012 Abstract This paper provides information about how network operators can provide information to Win...
Author: Rosa Elliott
1 downloads 1 Views 521KB Size
Providing Mobile Broadband Metadata May 31, 2012

Abstract

This paper provides information about how network operators can provide information to Windows in order to extend the connectivity experience. The various types of metadata and their purpose are explained. Key features include the ability for operators to provide branding, a plan purchase experience, and operator provisioning data to Windows. The reader should be familiar with the Windows Mobile Broadband Platform and basic Metro style app development concepts. This information applies to the following operating systems: Windows 8 Release Preview

References and resources discussed here are listed at the end of this paper. The current version of this paper is maintained on the Web at: Providing Mobile Broadband Metadata

Disclaimer Disclaimer: This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to prereleased product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 2

Document History Date Change February 28, 2012 First publication May 31, 2012 Updating with information about operation identification data, the submission and maintenance process, service metadata, account provisioning metadata, SMS parsing, signatures, and troubleshooting provisioning failures.

Contents Introduction to Mobile Broadband Metadata................................................................ 3 1 APN Database......................................................................................................... 4 1.1 Overview......................................................................................................... 4 1.2 Contents.......................................................................................................... 4 1.3 Submission and Maintenance......................................................................... 5 2 Service Metadata....................................................................................................6 2.1 Service Metadata Introduction....................................................................... 6 2.2 Contents.......................................................................................................... 6 2.3 Service Metadata Submission......................................................................... 8 2.4 Service Metadata Maintenance Implications................................................. 8 3 Account Provisioning Metadata............................................................................. 9 3.1 Introduction.................................................................................................... 9 3.2 Contents........................................................................................................ 10 3.2.1 Global.................................................................................................... 10 3.2.2 Mobile Broadband Information............................................................ 10 3.2.3 Wi-Fi Information.................................................................................. 11 3.2.4 Plan Information................................................................................... 15 3.2.5 Refresh.................................................................................................. 16 3.2.6 SMS Parsing...........................................................................................17 3.2.7 Signature............................................................................................... 18 3.3 Common Scenarios........................................................................................19 3.3.1 Finding the Account Provisioning schema............................................ 19 3.3.2 Applying Provisioning XML to the PC.................................................... 19 3.3.3 Provision the machine to connect automatically to a Mobile Broadband network..............................................................................................20 3.3.4 Provision the machine to connect automatically to a Wi-Fi network...20 3.3.5 Provision the machine to connect automatically to a WISPr-enabled hotspot 21 3.3.6 Sending activation to the Mobile Broadband device............................23 3.3.7 Forcing the Mobile Broadband device to reregister/reconnect to the network after provisioning completes................................................................. 24 3.3.8 Updating data usage statistics for a connection profile....................... 24 3.3.9 Update data usage via an SMS message...............................................25 3.4 Troubleshooting Provisioning Failures..........................................................25 3.4.1 Results from the Provisioning API......................................................... 25 3.4.2 Identifying partial provisioning failures................................................ 25 3.4.3 Event Logs............................................................................................. 26 May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 3

Resources...................................................................................................................... 26

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 4

Introduction to Mobile Broadband Metadata Windows uses metadata information from operators to customize various aspects of the Windows 8 experience. These include providing branding for the Windows connection manager, integrating the mobile operator app with the Windows connection manager, providing updated information for the APN connectivity database, and providing data to provision the PC. Windows includes three sources of metadata: •

APN Database – The APN Database contains pre-provisioned data that is required to connect to the operator's network for the first time. It is part of Windows and is updated via Windows Update. The APN Database is always available on the PC.



Service Metadata – Information required for subscription purchase and operator branding. The operator provides this information as part of the service metadata package. It is stored on the Windows Metadata and Internet Services (WMIS) and downloaded after mobile broadband hardware detection using any available Internet connection. This metadata can also be preinstalled onto a PC by the OEM.



Account Provisioning Metadata – Information generated after a subscription purchase, including Wi-Fi credentials and plan information. Provided by the operator to Windows after payment validation, this metadata can be updated using the Provisioning-Refresh mechanism.

The following diagram shows how the different sources of metadata are related to each other and how they are serviced.

Figure 1 - Overview of Windows 8 mobile broadband metadata system

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 5

1 APN Database 1.1 Overview The APN Database enables a simple first-time connectivity experience for consumers, particularly if connecting to the operator network without the mobile operator application already installed on the PC. Upon device recognition, the PC may need to be provisioned to connect to the appropriate operator network. The APN Database, included as a part of Windows, contains the necessary information needed to connect to the mobile broadband network, allowing Windows to connect automatically with minimal user input. The database maintains APN and Access Strings for different mobile network operators, enabling a user’s connection to the operator’s network prior to acquiring any additional software or metadata (for example, without the need to have the mobile operator app installed). In addition to provisioning information, the database also includes a URL to the account experience website. After automatically connecting to the operator’s network, the provided URL opens in the default browser, where the user can purchase a subscription or one-time access.

1.2 Contents To connect to a mobile broadband network, the user is typically required to provide the following information: •

In GSM networks, Access Point Name (APN) such as "data.contoso.com"



In CDMA networks, an Access String that includes a special dial code such as "#777" or a NAI (Network Access Identifier) such as "[email protected]"



The user’s credentials (username and password) for the network connection

Windows maintains a database of APNs and Access Strings for different mobile network operators. This database contains the information needed to connect to the operator’s mobile broadband network and allows Windows to connect to this network with minimal user input. The Operator submits relevant data to Windows and Windows services the database using Windows Update. Specifically, the APN Database includes: •



Operator Identification Data o

GSM Operators can submit database entry(s) for the IMSI or ICCID ranges that their network uses. If the operator is an MVNO, they can specify one or more ranges of IMSIs or SIM ICC IDs that they have leased from an MNO.

o

For CDMA, operators can have a new database entry for each Provider ID or Name.

o

To better understand how MVNOs should be identified, see Matching Service Metadata for MVNO Scenarios.

List of Purchase APNs/Access String May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 6



o

For GSM, a list of APNs with username and password used for purchasing the subscription.

o

For CDMA, this can be a list of NAIs that are used for purchasing the subscription.

List of Internet Connect APNs/ Access String o

For GSM, a list of APNs with username and password used for connecting to the Internet.

o

For CDMA, this can be a list of NAIs that are used for connecting to Internet.



Account Experience URL: URL for first-time purchase Account Experience website.



Certificate Data: Certificate information for Account Provisioning Metadata. This includes Certificate Issuer Name and Subject Name, and is used to verify that Account Provisioning provided by a purchase website comes from the operator’s authorized web service.

1.3 Submission and Maintenance The following steps describe the high-level process for creating an APN Database entry for Windows: 1. A developer from the operator fills out an Excel file that includes the elements required for the APN Database. Operators also fill out a bug template that is provided. 2. The partner logs into the Windows Dev Center – Hardware Dashboard. They then file a new bug using the Windows Dev Center – Hardware Dashboard bug filing tool. This bug must have the Excel file attached to it and must have the bug template pasted into the description section of the bug. 3.

On a regular schedule, APN database update bugs are triaged and an updated database is produced.

4.

This updated database is provided to the operators who have submitted updates for that update cycle to verify.

5.

Operators who submitted an update for that update cycle have a set amount time to sign off on the updated database.

6.

The database is maintained and updated through Windows Update.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 7

The following diagram shows how the APN Database in Windows is updated.

Operator

Windows Hardware Dev. Center

Windows Update

Windows 8 APN DB

Figure 2. How the APN Database in Windows is updated

More information about how to submit APN database bugs will be made available after Windows 8 Release Preview.

2

Service Metadata

2.1 Service Metadata Introduction Creating and submitting a service metadata package allows operators to create a deeply integrated experience with Windows. When Windows detects mobile broadband hardware that matches the operator’s service metadata package, it automatically downloads the service metadata and the specified mobile operator app. For more information about the service metadata, see Service Metadata Package Schema Reference for Windows 8.

2.2 Contents The following summary describes some of the most interesting fields that are contained and defined inside a service metadata package: •

Hardware IDs: GSM Operators can submit a metadata package that describes the IMSI or ICCID ranges that they want their service metadata package to match against. If the operator is an MVNO, they can specify one or more ranges of IMSIs or SIM ICC IDs that they have leased from an MNO. CDMA operators can submit a package using Provider ID (SID/NID) or Provider Name. For more information about planning your HWID ranges for MNO and MVNO scenarios, see Matching Service Metadata for MVNO Scenarios.



Service number: The unique ID for the mobile broadband service provider. This GUID is also used to identify the operator when using Account Provisioning Metadata. If you update the device metadata package, this GUID must remain the same.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 8



Operator logo logo: A custom logo appears in Windows Connection Manager UI next to your network entry. The logo is hidden when the user is on a roaming network. Icon requirements: Required sizes in 3 color depths: Format: .ICO Icon Icon: 256x256:32bit+Alpha(compressed) Sizes Sizes: 48x48:32bit+Alpha 24x24:32bit+Alpha 48x48:8bit256 24x24:8bit256 48x48:4bit16 24x24:4bit16 32x32:32bit+Alpha 16x16:32bit+Alpha 32x32:8bit256 16x16:8bit256 32x32:4bit16 16x16:4bit16



Mobile operator app: A Metro style device app that is automatically downloaded and applied to the PC. This app can provide key experiences such as plan purchase, data usage, help and support, as well as highlighting value-added services from the operator.



MB Purchase Profile: Purchase profile that is used for establishing limited connectivity for purchasing a subscription. More information about Windows Mobile Broadband Profiles is located at Mobile Broadband Profile Schema Reference.

o

GSM Operators who have only one “Purchase APN” for all subscribers can use the service metadata to provision that to the PC. If the operator has multiple Purchase APNs, they should use Account Provisioning Metadata (described in the following section) to set the appropriate purchase APN. Or, they can do nothing and instead use the entries that are stored in the inbox APN database to provide APN connectivity information.



MB Internet profile profile: Every mobile broadband subscription can have one default profile that is used to connect to the home network operator. The Windows Connection Manager uses this profile for auto-connecting to the network. More information about Windows Mobile Broadband Profiles is located at Mobile Broadband Profile Schema Reference.

o

GSM operators who have only one “Internet APN” for all subscribers can use the service metadata to provision the PC. If the operator has multiple Internet APNs, they should use Account Provisioning Metadata, described in the following section, to set the appropriate internet APN. Or, they can do nothing and instead use the entries that are stored in the inbox APN database to provide APN connectivity information.



Certificate data data: Certificate information for Provisioning. This includes Certificate Issuer Name and Subject Name. This information is used to ensure that account provisioning operations initiated by a website are issued by a trusted operator.



Custom operator name: The mobile broadband device typically provides the operator name and Windows shows that name in the Connection Manager. The operator can override this name by specifying a custom name in May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 9

metadata. This name only shows up if the user is on a home network and is not on a roaming network. The roaming network name is displayed based on information from the device. •

Device notification handler: In general, an app must be run by the user at least once before it can register work items with the System Event broker. However, mobile operator apps may need to receive important events before the user can run the app. The operator can specify the device notification handler in service metadata and Windows will register for some critical events. For more information about SMS notifications, see Mobile Operator Notifications and System Events.



List of privileged apps with access to mobile broadband restricted interfaces interfaces: Mobile Broadband APIs and interfaces (including Account Provisioning and SMS) are restricted and only available to mobile operator apps. A list of privileged apps that have access to these privileged APIs can be specified in the service metadata package. Privileged apps can be debugging or test apps and are not required to be distributed through the Windows Store.

2.3 Service Metadata Submission For more information about how to submit service metadata packages to the Windows Hardware Dev Center Dashboard, see Submitting a Metro style Device App for Mobile Broadband.

2.4 Service Metadata Maintenance Implications It is important to keep metadata packages up to date in terms of how they are described and which IMSI and ICCID or CDMA provider name or SID values they match against. This may require the MNO or MVNO to implement a new workflow that is part of SIM or device acquisition in order to keep track of new orders of SIMs and the MNO or MVNO those ICCIDs or IMSIs are being provided to. The Windows Hardware Developer Center Dashboard provides the submission channel to submit updates to your service metadata. It is also a best practice to avoid making frequent changes to your service metadata by reserving ICCID or IMSI ranges (or CDMA SIM/Provider name) for the MNO and MVNO ahead of time so that when new SIMs (or CDMA devices) are procured, they are already accounted for in your service metadata package. The service metadata and the mobile operator app (which is managed through the Windows Store) can have different update and servicing schedules. App updates appear in the Store tile on the Start screen; the user decides when to update their apps. Metadata is silently applied based on internal Windows logic (typically every 8 days) when Windows asks WMIS if it has any metadata updates. Users may react to the app update notification and update their apps to the latest version. This may cause issues if the updated service metadata has already been applied but the user is still using an older version of the app. One strategy is for the app to identify what version it is and, if needed, remind the user that the Store has an

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 10

update waiting for them. This may help to get users to the latest version of the app so they are more likely to have the latest metadata and latest app.

3

Account Provisioning Metadata

3.1 Introduction Provisioning refers to configuring a Windows PC with the information required to connect to an operator network. Typically, this is performed after mobile broadband subscription purchase. Windows accepts an XML-based provisioning file from the operator. The Provisioning API takes the XML from the operator Account Experience, either through the local Metro style app or through a purchase website, and applies the information to Windows components. The following diagram illustrates the contents and hierarchy of the provisioning XML file. For more information about Provisioning schema, see CarrierControlSchema schema. Carrier GUID Global Subscriber ID

Mobile Broadband

e F l i

Internet Profile

Metering Information

Purchase Profile

Metering Information

Device Activation

Actions(Re-connect, ReRegister) or Data Metering Information

Hotspots

WLAN Profiles WISPR Credentials

P

o r

o v s i

X

M

L

n i

g

URL for update

Credentials

Refresh

Trusted Signing Certificates

XML-DSig Signature

Time until update (timed)

SMS Parsing Rules

Notification Signature Key (triggered)

Figure 3. Provisioning XML file hierarchy

3.2 Contents The provisioning metadata includes the following fields.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 11

3.2.1 Global The global section is required in every provisioning file. Required elements in this section are: •

Carrier: A GUID that uniquely identifies the organization that authored the file. If you are a mobile operator building a mobile operator app, you must use the GUID that you specified in the Service Number field of ServiceInfo.xml. ServiceInfo.xml is part of the service metadata package. For schema information, see Service Metadata Package Schema Reference for Windows 8 . If you created your service metadata using the Mobile Broadband Metadata Authoring Wizard, use the same GUID as you specified in the Service Number field (see Describe your service in the Mobile Broadband Metadata Authoring Wizard ). If the GUID for Service Number in the ServiceInfo.xml file does not match the GUID specified here, then Account Provisioning Metadata operations will fail. If you are not creating a mobile operator app, then you may generate a GUID for your organization’s use. In either case, you should always use the same GUID on all provisioning files that your organization issues.



SubscriberID: A string that uniquely identifies the customer within your organization. If you are a mobile operator, this should be the IMSI or ICCID ranges for GSM operators or the provider ID or provider name for CDMA operators. If you are not a mobile operator, you may choose any sufficiently unique string.

3.2.2 Mobile Broadband Information •

MB Internet Profile Profile: Every mobile broadband subscription can have one default profile that is used to connect to the home network operator. Windows Connection Manager uses this profile for auto-connecting to the network. The format of this section parallels that of Windows Mobile Broadband Profiles, located at Mobile Broadband Profile Schema Reference.



MB Purchase Profile: Information needed to connect to the operator’s network in order to purchase a new subscription.

Contoso MBN Contoso Mobile Broadband Contoso MBN contoso.com mbfoo mbbar

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 12



In addition to the information contained in the mobile broadband profiles above, provisioning XML can be applied either by the mobile operator app or by the operator website to perform actions such as: •

Device activation: After the operator completes the activation process on the back end, the PC might need to follow certain instructions before connecting to the network. The Provisioning Engine uses the activation instructions received in the device activation element. If no value is specified, then no client action is required. Available actions include:

o

Re-connect: Disconnect and connect to the operator network.

o

Re-register: Disconnect and register to the operator network. •

Data Data: Data or instructions that operators want to send to the device to activate the connection. The Provisioning Engine passes this data “as is” to the device. For CDMA, this can include instructions such as “*228” to start an OTA Programming Session and reconnect to the network.

More information about device activation is contained in section 3.3.6.

3.2.3 Wi-Fi Information This section enables you to provide any number of Wi-Fi network profiles for Windows to use. The format of the section is similar to the XML schema used by the Windows Native WLAN API. Note that one profile can contain multiple SSIDs provided that all other settings are the same. If different networks vary in other ways (authentication method, encryption settings, plan, and so on), you will need to create additional profiles. One additional node to note in this section is the “Associated Plan.” This allows Windows to associate the WLAN profile with a plan described in the Plans section. The plan allows you to inform Windows of the metering state of the network and influence the behavior of Windows while connected to the network. When you specify the WLAN section, you must also specify all profiles that should be configured on the PC. If those profiles reference a data plan, the Plans section must also be included. The behavior while processing this section is: •

If the PC has a profile that is no longer specified, it will be deleted.



If you specify a profile, it will be updated or created.



An empty WLAN section will delete all profiles



Omitting the WLAN section will leave the WLAN profiles on the machine unchanged

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 13

3.2.3.1 Unencrypted network, no automatic authentication

This profile configures Windows to connect to an open network. •

If this network contains a captive portal, the browser is launched on connection to the network.



If the network does not contain a captive portal, the user is connected with no further action.

Contoso WiFi Contoso WiFi open none false

3.2.3.2 Unencrypted network, WISPr authentication

This profile configures Windows to connect to an open network and expect to use WISPr authentication: •

If this network contains a WISPr-capable captive portal, the specified user name and password is submitted to the specified authentication server.



If the captive portal is not capable of WISPr, the browser is launched on connection to the network.



If the network does not contain a captive portal, the user is connected with no further action.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 14

Contoso WiFi Contoso WiFi open none false WisprUser1 password1 www.mycaptiveportal.com

3.2.3.3 Encrypted network, EAP-SIM authentication This profile configures Windows to connect to an encrypted network using a SIM as the authentication type, such as a Hotspot 2.0 network. Hotspot 2.0 defines such a network to use WPA2-Enterprise with EAP-SIM authentication.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 15

Contoso WiFi Contoso WiFi WPA2 AES true 18 0 0 311

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 16

Unencrypted network, app-based authentication This profile configures Windows to connect to an open network and expect to use WISPr authentication in cooperation with your Metro style app. •

If the network contains a captive portal, your app is launched in the background to provide WISPr credentials. The credentials will then be submitted to the specified authentication server.



If the captive portal is not capable of WISPr, the browser is launched on connection to the network.



If the network does not contain a captive portal, the user is connected with no further action.

More details on how your Metro style app can participate in the hotspot authentication experience is provided in a later section. Contoso WiFi Contoso WiFi open none false YourAppIdGoesHere www.mycaptiveportal.com

3.2.4 Plan Information Each Mobile Broadband and Hotspot profile references a plan. Multiple profiles may reference the same plan. Plans are then described in a separate top-level section. The Plan is divided into two sections—Description and Usage. Description contains the elements that generally change with low frequency over a customer’s subscription period. Usage contains those elements that change with higher May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 17

frequency. This allows you to initially provide profiles and descriptions in a larger provisioning file, and then subsequently provide smaller provisioning files containing only the customer’s current usage. This information is used to affect the behavior of Windows directly, and is provided to applications to tailor their behavior to the network. This information can be made available to third-party applications via the Network Information APIs. 3.2.4.1 Description

The description contains details about a customer’s plan, including: •

Plan Type – The type of billing relationship the customer has with the operator: •

Unrestricted – Usage does not incur additional cost



Fixed – The user is allotted a certain amount of usage for a fixed cost



Variable – The user pays based on usage



ExemptSecurityUpdates – A Boolean, specifying whether Security Updates count toward the customer’s usage



DataLimitInMegabytes – The user’s allotted usage, if Plan Type is Fixed.



PlanReset – Date on which the user’s allotment terminates, either by resetting the Usage to zero, or by termination of the user’s plan



BandwidthInKbps – The user’s connection speed as allowed by the network; may reflect the norm for their plan, or a lower rate currently imposed by the carrier due to congestion or excessive use (maximum of 2 Gbps)



MaxTransferFile Size in Mbytes Mbytes: An integer, expressing the size of an individual download that a compliant application should permit over a metered connection without explicit user approval of the connection being used.

3.2.4.2 Usage

The usage section contains frequently updated details about the network and the customer’s usage relative to his or her plan allotment. This contains following information: •

UsageInMegaBytes UsageInMegaBytes: The user’s most recent data usage.



OverDataLimit OverDataLimit: A Boolean, reflecting whether the user has passed his or her allotted usage (if Plan Type is Fixed).



Congestion Congestion: A Boolean, reflecting whether a lower connection speed than usual is being imposed due to excessive usage. The Congested flag indicates that the network is currently experiencing (or expects to experience) heavy load, and lower-priority transfers should be deferred until another time if possible. Use this flag to indicate concepts such as “peak hours,” or to respond to an overloaded hotspot.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 18

3.2.5 Refresh With Refresh, operators can push updated settings to the PC as required, either due to network changes or for technical support. Windows attempts periodic refresh using information provided by the operator or Provisioning API. Refresh can be triggered by SMS notification from the operator. To enable Refresh, operators have to provide the following information in the provisioning XML: •

Trusted Certificates – A list of certificate thumbprints whose signatures are trusted on future provisioning files.



DelayInDays – The (integer) number of days before which a refresh will not be attempted.



RefreshURL – The HTTPS URL to obtain the latest copy of this user’s provisioning file.



Username & Password – Optional credentials to be presented using HTTPAuth when retrieving the re-provisioning file. This information must be encrypted when stored.



AllowedSender AllowedSender: List of phone numbers of those who can send SMS messages to update system configuration.

Alternatively, the mobile operator app can provide a new provisioning file at any time based on communication between the app and the operator’s back end. 30 https://www.contoso.com/refresh foo bar

3.2.6 SMS Parsing The rules to identify a text message and extract information may be provisioned as part of the provisioning XML file. Operator SMS messages can be used to update data usage statistics or to trigger a refresh of provisioning information. For more information on SMS notifications, see Mobile Operator Notifications and System Events. Each rule contains the following information: •

Silent: Specifies whether the message should be restricted to the mobile operator app. If true, only the mobile operator app receives messages that match this expression. If false, other privileged SMS-capable apps also receive this message.



Allowed sender: Specifies the reserved sender address that the notification is allowed to arrive from. (This number must match the sender number received in the SMS message exactly, including the international format).



Pattern: The regular expression to use to identify and optionally extract the data fields from the text message.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 19



Locale: The locale that should be used to interpret locale-sensitive information such as numeric values. For example, “1.5 GB” in English-United States is represented as “1,5 GB” in German. The locale is specified as an RFC 4646 name, such as “en-US” (U.S. English) or “hi” (Hindi).



Fields and groups: Each match-group in the regular expression pattern is tied to a named field. This association is used to extract and transform the data into a usable value; for example, the first match-group can be tied to the ‘Usage’ field, the second match-group can be tied to the UsageDataLimit field. This indicates that the first value is the current usage information, while the second value is the maximum allowed usage.

Note Note: To match all messages from a sender, use pattern [^]*. You have used (\d+(?:[.]\d+)?)(\w+) of (\d+(?:[.]\d+)?)(\w+) of your plan which resets on ((?:\d|:)+)[.] en-US

3.2.6.1 Security of SMS Messages

Because Operator SMS Messages influence Windows behavior, there is a need to make sure only trusted SMS messages are consumed. Security is maintained by restricting the sender address. This assumes that the operator network’s SMS Gateway ensures that messages from restricted senders cannot be spoofed.

3.2.7 Signature Because provisioning modifies system settings that persist after the user has exited or even uninstalled the app, a stricter measure of verification is required than for most APIs. This verification is provided by a combination of operator-specific hardware (the SIM), cryptographic signatures, and user confirmation. Table 1. Provisioning requirements SIM present? Source of provisioning

Signature requirement

User confirmation requirement

Yes, MB provider

None

None

Mobile operator app

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 20

SIM present?

Source of provisioning

Signature requirement

User confirmation requirement

Yes, MB provider

Operator web site

Certificate must:

None

No, Wi-Fi provider

Mobile operator app or web site



Chain back to trusted root CA



Be associated with mobile broadband hardware in APN database or experience metadata

Certificate must: •

Chain back to trusted root CA



Be marked for Extended Validation

User prompted to confirm the first time the certificate is used; none thereafter

3.3 Common Scenarios 3.3.1 Finding the Account Provisioning schema XSD schemas are available under %SYSTEMROOT%\schemas\provisioning on any computer running Windows 8 Release Preview.

3.3.2 Applying Provisioning XML to the PC From the mobile operator app: 1) Instantiate a ProvisioningAgent instance (using Windows.Networking.NetworkOperators.ProvisioningAgent.CreateFromNetw orkAccountId). 2) Call IProvisioningAgent::ProvisionFromXmlAsync, passing in the unsigned provisioning XML document. The asynchronous operation will complete and the results of the provisioning operation are returned. From a Metro style app other than the mobile operator app : 1) Generate a signed Account Provisioning XML document. 2) Instantiate a ProvisioningAgent instance (using the default constructor). 3) Call IProvisioningAgent::ProvisionFromXmlAsync, passing in the signed XML document.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 21

The asynchronous operation completes and the results of the provisioning operation are returned. From a website: 1) Generate a signed Account Provisioning XML document. 2) Call window.external.msProvisionNetworks, passing in the signed XML document. The operation completes and the results of the provisioning operation are returned. If the provisioning xml is malformed or invalid according to the provisioning schema, an event is logged. The payload of the event indicates why the parse/schema validation operation failed. This event is logged under the following channel and is viewable using the Event Viewer:

Applications and Services Logs\Microsoft\Windows\NetworkProvisioning\Operational

3.3.3 Provision the machine to connect automatically to a Mobile Broadband network Define a provisioning xml document with a section as follows. {00000000-1111-2222-3333-444444444444} 1234567890 Profile Name The Description Contoso apn username password

Not all of the tags under are required. See the provisioning xml schema reference for more details.

3.3.4 Provision the machine to connect automatically to a Wi-Fi network Define a provisioning xml document with a section as follows.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 22

{00000000-1111-2222-3333-444444444444} 1234567890 My Wifi Hotspot wifihotspot1 open none false

The tags under define how to connect to the network, including any necessary EAP configuration. All elements under the MSM element in the WLAN_profile schema are supported. See the provisioning XML schema reference for more details.

3.3.5 Provision the machine to connect automatically to a WISPr-enabled hotspot There are two ways to enable hotspot authentication: 1) Declare credentials directly using the directive.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 23

... Contoso WiFi Contoso WiFi open none false Alice secret hotspot.contoso.com ...

2) Redirect to an app for authentication using the directive.

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 24

... Contoso WiFi Contoso WiFi open none false Alice hotspot.contoso.com ...

Supplying direct credentials is the preferred method because redirecting to another application has power and complexity implications.

3.3.6 Sending activation to the Mobile Broadband device An arbitrary binary blob (contained inside the CarrierSpecificData tag) can be Base64encoded and sent to the device using the ProvisioningAgent. This is achieved using the Activation/ServiceActivate directive in the provisioning XML. {00000000-1111-2222-3333-444444444444} 1234567890 YXJiaXRyYXJ5ZGF0YQ==

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 25

This is equivalent to invoking the IMbnVendorSpecificOperation::SetVendorSpecific method of the Mobile Broadband API and passing a SAFEARRAY with the binary blob contents.

3.3.7 Forcing the Mobile Broadband device to reregister/reconnect to the network after provisioning completes The following two activation methods can serve this purpose: and . The directive is used to force reregistration to the Mobile Broadband Network. This is accomplished by turning the Mobile Broadband radio off and then back on. After the radio comes back on, the adapter is connected using the default profile. This directive should be used sparingly and only if it is necessary to deregister from the network after account activation. The directive is used when context activation needs to be redone in order to apply any new security/policy settings after account activation has completed. This is done by deactivating the PDP context and reactivating based on the default profile settings for the Mobile Broadband adapter. If the default profile is updated in the same provisioning xml, the new profile settings will be used. Both of these directives can optionally be specified with retry counts/intervals and delayed execution times. Note that if the radio is successfully cycled on in a but the automatic connection back to the network using the default profile fails, then subsequent retries will not cycle the radio again.

{00000000-1111-2222-3333-444444444444} 1234567890

3.3.8 Updating data usage statistics for a connection profile Only usage for profiles that were provisioned via the ProvisioningAgent may be updated. This is accomplished by applying a new Account Provisioning file with updated plan information. It is possible to provide a provisioning file that contains

May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 26

only Usage information, or only Plans. Depending on how much of the system configuration you want to change, the new provisioning file may include: •

Profiles, Plan Descriptions, and Usage



Plan Descriptions and Usage (updates existing profiles)



Plan Usage (updates existing profiles and plans)

If you apply new profiles and reference plans that are not defined in the XML, the provisioning results will include a warning.

3.3.9 Update data usage via an SMS message This is accomplished by doing one of the following: •

Specifying an operator message, receiving an operator notification message, reading the message via the SMS API, parsing the message in the app, and then setting the usage via IProvisionedProfile.



Specifying an operator message rule with a valid combination of usage fields and providing the updated usage in the SMS directly.

3.4 Troubleshooting Provisioning Failures 3.4.1 Results from the Provisioning API If provisioning fails entirely, you will receive an exception when attempting to perform the provisioning action. Failures that could cause exceptions include: •

XML that does not conform to the Provisioning schema



XML that requires a signature, but is not signed appropriately (see section 3.2.7)

3.4.2 Identifying partial provisioning failures Portions of the provisioning operation may not succeed because of a variety of reasons, transient or otherwise (for example, WIFI hardware not present at the time of provisioning would fail WLAN profile provisioning). The Provisioning Agent does a best effort attempt to provision everything in the file. When something fails, this is noted in the provisioning results returned asynchronously via ProvisionFromXmlDocumentAsync ProvisionFromXmlDocumentAsync. The results are returned as XML and can be parsed to discover the failure. Elements provide structure to know what failed and ErrorCode attributes indicate the reason for the failure (as a standard HRESULT). For example, the following would indicate that no WLAN profiles were provisioned because the WLAN service was not active.



May 31, 2012 © 2012 Microsoft. All rights reserved.

Providing Mobile Broadband Metadata - 27

If an individual profile failed to be applied, it will appear as follows:

3.4.3 Event Logs Open Event Viewer Viewer, then navigate to Applications and Services > Microsoft > Windows> NetworkProvisioning > Operational. Events in this channel can provide detailed feedback about provisioning failures.

Resources Overview of Mobile Broadband in Windows 8 http://go.microsoft.com/fwlink/?linkid=242052 Preparing to Develop Mobile Operator Apps http://go.microsoft.com/fwlink/?linkid=242057 Development Guide to Creating Mobile Operator Apps http://go.microsoft.com/fwlink/?linkid=242058 Mobile Operator Hardware Guidelines for Windows 8 http://go.microsoft.com/fwlink/?linkid=242059 Designing User Experience of Mobile Operator Apps http://go.microsoft.com/fwlink/?linkid=242066 Overview of Mobile Broadband Windows Runtime API http://go.microsoft.com/fwlink/?linkid=242060 Service Metadata Package Schema Reference for Windows 8 http://go.microsoft.com/fwlink/?linkid=242065 Matching Service Metadata for MVNO Scenarios http://go.microsoft.com/fwlink/?LinkId=249182 Mobile Operator Notifications and System Events http://go.microsoft.com/fwlink/?linkid=242062 Mobile Broadband SMS http://go.microsoft.com/fwlink/?linkid=242061 Submitting a Mobile Operator App http://go.microsoft.com/fwlink/?linkid=242069

May 31, 2012 © 2012 Microsoft. All rights reserved.