Bootstrapping To Use An OMA DM Server

Article
08/28/2006

The primary bootstrap objective is to configure a Windows Mobile-based device to recognize your OMA DM server as having MANAGER privileges on that device. You accomplish this by sending a provisioning document which uses OMA Client Provisioning version 1.1 XML format. Contained in the document is an w7 APPLICATION characteristic which has the values required to fill the DMAcc portion of the device's DM tree. This includes, among other things, the DM server's name and address. The message will also include authentication information for the DM server and the device. After processing this message the device will accept management commands from the DM server.

Note The device requires an SSL connection to the DM server. If the root certificate of the DM server SSL channel is not in the device's default root certificate store then the root certificate needs to be provisioned in bootstrap message as well.

The following example shows a typical DM bootstrap message. It configures the device with the information required for it to connect to, and authenticate a specified DM server:

<wap-provisioningdoc version="1.1">
  <characteristic type="APPLICATION">
    <parm name="APPID" value="w7"/>
    <parm name="PROVIDER-ID" value="com.mgmtsrv.manage"/>
    <parm name="NAME" value="Mgmt Server"/>
    <parm name="ADDR" value="https://www.mgmtserver.com:8080/manage"/>
    <parm name="TO-NAPID" value="ABCGPRS1"/>
    <parm name="ROLE" value="8"/>
    <characteristic type="APPAUTH">
      <parm name="AAUTHLEVEL" value="APPSRV"/>
      <parm name="AAUTHTYPE" value="DIGEST"/>
      <parm name="AAUTHNAME" value="clientname"/>
      <parm name="AAUTHSECRET" value="clientsecret"/>
      <parm name="AAUTHDATA" value="clientnonce"/>
    </characteristic>
    <characteristic type="APPAUTH">
      <parm name="AAUTHLEVEL" value="CLIENT"/>
      <parm name="AAUTHTYPE" value="DIGEST"/>
      <parm name="AAUTHSECRET" value="serversecret"/>
      <parm name="AAUTHDATA" value="servernonce"/>
    </characteristic>
  </characteristic>

  <characteristic type="NAPDEF">
    <parm name="NAPID" value="ABCGPRS1"/>
    <parm name="NAME" value="ABC GPRS Connection"/>
    <parm name="NAP-ADDRESS" value="ABCGPRSAPN"/>
    <parm name="NAP-ADDRTYPE" value="APN"/>
    <parm name="BEARER" value="GSM-GPRS"/>
  </characteristic>

<!-- IMPORTANT NOTICE change to policy 4119 ONLY IF the message is sent over RAPI so that the message that is assigned OPERATOR_TPS role will be granted as the device manager by updating the following policy.--> 
  <characteristic type="SecurityPolicy">
    <parm name="4119" value="128"/>
  </characteristic>

<!-- Added the change to policy grant manager policy (4119) and WAP Signed Message policy (4107) if the message is sent OTA through WAP Push so that the message that is assigned OPERATOR_TPS role will be granted as the device manager and pure user pin signed or network pin signed WAP push provisioning message from unknown source is disallowed --> 

  <characteristic type="SecurityPolicy">
    <parm name="4119" value="128"/>
    <parm name="4107" value="3200"/>
  </characteristic>
  <characteristic type="CertificateStore">
   <characteristic type="ROOT">
     <!-- add DM server's SSL root certificate if it is not in the  device's default root certificate store -->
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

The APPLICATION characteristic specifies information about the server. The INIT parm is specific to the OMA DM protocol. When present, it indicates to the device that it should initiate a management session with the server immediately after successfully processing the message.

The ROLE parm is a Microsoft custom parm. It indicates that, during the DM session, messages from the server will have the specified security role. In the example, the assigned value indicates to the device that the messages will have MANAGER authority (ROLE = 8).

Note The security roles of the DM server account are the same as the bootstrap message unless they are explicitly set by using ROLE parameters. The DM server account cannot have more roles than those of the bootstrap message, and it cannot configure a role that it doesn't have. ******

The security roles for the DM server are assigned as follows:

If the DM server is bootstrapped at manufacture, the server is assigned all roles implicitly.
When bootstrapping a DM server account over the air (OTA) or through Remote API (RAPI), the DM server roles are set to the Role parameter of the server account, as described in DMAcc Configuration Service Provider and the w7 APPLICATION Configuration Service Provider.

The two APPAUTH characteristics specify authentication information for the DM server and for the client device.

Windows Mobile Version 5.0 supports the following options for delivering the OMA DM bootstrap provisioning document to the device:

Bootstrap During Production
This is the recommended option. The provisioning file can be placed in ROM by the Operator's OEM during production.

Note The INIT parm must not be in the provisioning file in ROM.
Bootstrap OTA via WAP Push for non-branded devices
The provisioning file can be sent to the device OTA via WAP Push. However, you will need to enable OTA bootstrapping which is disabled on the device by default. See Enabling OTA Bootstrapping for more information.

Note If the device is reset OTA bootstrap settings will be lost as the device will revert to the default factory settings.
Use Image Update to place a .provxml file in ROM
Bootstrap at the point of sale (for non branded devices) using a .cpf file.
1. Your OEM must place a certificate in the SPC store with Role = Manager.
2. The cert signed .cpf file that contains a w7 APPLICATION characteristic and corresponding data connectivity settings is sent to the device using a MMC card.

Bootstrapping To Use An OMA DM Server

See Also

Additional resources