Inside the Mobile Developer bag of tricks: Provisioning XML
As a Windows Mobile developer, you’ve seen all the references to provisioning XML right? It’s all over the SDK. You probably know that it can somehow be used to configure devices, but you may not have connected with any value to developers. After all, the docs kind of blur the intended use around OMA Device Management, Operator, and IT control. Net, net – it looks and smells like a device management “thing” (I suppose it is) and that’s normally not a particularly interesting topic for most developer minds. I ignored it for a while. Then I kept solving day-to-day problems with configuration XML. Today, it’s a critical tool in my developer bag-of-tricks that I couldn’t live without.
Why, you say? Let’s step back a moment and ponder what configuration XML means to the Windows Mobile platform. In WM6, there are some 50+ Configuration Service Providers (CSP) used to configure and query the state of a device. This is all mostly done through XML and an API called DMProcessConfigXML. It’s a beautifully simple concept… write some XML, pass it to DMProcessConfigXML, and the API figures out the rest. You don’t need to know anything about the special purpose APIs behind the CSPs or how to call them… it’s just all XML to you. With some simple config XML, I can configure network connections, email accounts, registry entries, security policies, speed dial entries, browsers favorites, etc. It’s a really simple way to get things done.
The benefits
I’ve found it particularly useful in the areas of support and configuring a clean device. I’m constantly helping partners debug problems around security and connectivity. Security policies and Connection Manager settings are only partially visible in the UI of a Windows Mobile device. If you really want to know what certificates are installed, what security policies are set, or what an Operator has done with the connection manager plumbing that could be affecting your network routes, it’s a lot easier to simply query the CSPs to get this info. As a dev, hard-resets also come with the job. I constantly abuse my device to create problems in the course of reproducing issues—then hard reset to bring it back to life. I use a handful of config XML files to restore my device to a state I like it in – configuring my email, browser favorites, and even my data networks. The ability to save state in our emulators has helped a lot here, but occasionally I still need to do something with a real device and this saves me a lot of manual config time setting it back up.
The other point I’ll make here is that it’s just good to know how configuration XML works. It’s an intrinsic part of the platform. Crack apart any CAB and you’ll find config XML (_setup.xml) used to install your app. How do products like Exchange and Systems Center Mobile Device Manager control and configure your device? You got it…Configuration XML.
Methods of provisioning
There are a number of ways to do it. The most direct way is to simply use the DMProcessConfigXML api (there are both managed and unmanaged version of this). When you look at the SDK and samples, stick to the ones labeled “OMA Client Provisioning” (not the OMA DM versions). Everything should be wrapped in a <wap-provisioningdoc>… </wap-provisioningdoc> before you pass it to DMProcessConfigXML.
You will find a number of community and MSDN resources on the topic. Here are a few places to start on Channel9 and MSDN.
For me, I wrote my own little utility that processes any XML files in the same directory and passes them to DMProcessConfigXML. That way, I can just drop it into a directory and add any provisioning XML I want and… off it goes. I can also stick it in the \2577 directory of an SD card, rename it to AutoRun.EXE and have it automatically configure my device upon inserting an SD card (very handy).
You can use a desktop tool like RapiConfig.exe to push provisioning XML from the desktop (subject to RAPI security policies on your device).
You can build an installable CAB or CPF file from the provisioning XML and then install it on the device.
There are some other methods reserved for operators to do things via SMS & WAP gateway but not really applicable to most developers.
Examples Please…
Start with the SDK samples here:https://msdn2.microsoft.com/en-us/library/bb737572.aspx
Connection Manager: Suppose you wanted to see what Connection Manager was doing with your network requests, this might be a good way to verify mappings, networks, plans, etc.
<wap-provisioningdoc>
<characteristic-query type="CM_Mappings" recursive="true"/>
<characteristic-query type="CM_Planner" recursive="true"/>
<characteristic-query type="CM_Networks" recursive="true"/>
<characteristic-query type="CM_ProxyEntries" recursive="true"/>
<characteristic-query type="Wi-Fi" recursive="true"/>
<characteristic-query type="CM_PPPEntries" recursive="true"/>
<characteristic-query type="CM_VPNEntries" recursive="true"/>
<characteristic-query type="CM_NetEntries" recursive="true"/>
<characteristic-query type="CM_GPRSEntries" recursive="true"/>
</wap-provisioningdoc>
Security Policy: Check out SecurityOff.xml, TwoTierPrompt.xml, OneTierPrompt.xml, TwoTierLocket.xml and OneTierLocker.xml in the SDK tools directories.
Certificates: Open the SdkCerts.CAB (or Certs.CAB) in the SDK with WinZip and examine _setup.xml or the certs.xml in the same directory as a provisioning sample for code signing certs.
If you just want to query all the certs, you could do something like this:
<wap-provisioningdoc>
<characteristic type="CertificateStore">
<characteristic-query type="Privileged Execution Trust Authorities" />
<characteristic-query type="Unprivileged Execution Trust Authorities" />
<characteristic-query type="SPC" />
<characteristic-query type="MY" />
<characteristic-query type="ROOT" />
</characteristic>
</wap-provisioningdoc>
The limits
CSP can be subject to security checks just like any other privileged API, so don’t assume you can configure or query anything on the device. You may need privileged access to use some CSPs (e.g. -Exchange and SCMDM go through privileged processes for comprehensive control). Sometimes there may also be better ways to do things that don’t enforce the same security checks. For example, the QueryPolicy API allows you to interrogate a security policy from code without any special access. On an emulator or 1-tier device though, you should be able to do most anything documented in the public CSP list. You can also use the SDK certs to sign your CAB, CFP, or utility for testing purposes on the emulator or a real device that contains the SDK test certificates.
The Picture
Okay, this is totally unrelated to the post at all... but every post needs some kind of visual to keep it interesting. I took a road trip last week and visited two amazing pieces of history...can you guess what they are?
Cheers,
Reed