Bootstrapping To Use An OMA DM Server

Article
11/18/2015

4/8/2010

The primary bootstrap objective is to configure a Windows Mobile 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 a 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.

Code Example

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="servername"/>
    <parm name="NAME" value="Description of server"/>
    <parm name="ADDR" value="https://www.mgmtserver.com:8080/manage"/>
    <parm name="TO-NAPID" value="ABCGPRS1"/>
    <parm name="ROLE" value="24"/>
    <characteristic type="APPAUTH">
      <parm name="AAUTHLEVEL" value="APPSRV"/>
      <parm name="AAUTHTYPE" value="DIGEST"/>
      <parm name="AAUTHNAME" value="clientname"/>
      <parm name="AAUTHSECRET" value="clientsecret"/>
            <!-- client nonce is Base-64 encoded -->
      <parm name="AAUTHDATA" value="Tm9uY2U="/>    
    </characteristic>
    <characteristic type="APPAUTH">
      <parm name="AAUTHLEVEL" value="CLIENT"/>
      <parm name="AAUTHTYPE" value="DIGEST"/>
      <parm name="AAUTHSECRET" value="serversecret"/>
            <!-- server nonce is Base-64 encoded -->
       <parm name="AAUTHDATA" value="bm9uY2U="/>
    </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 this bootstrap 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 grant manager policy (4119), OMA CP NETWPIN Policy (4141), OMA CP USERPIN Policy (4142), OMA CP USERNETWPIN Policy (4143) if this bootstrap 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, network pin signed, or user-network pin signed WAP push provisioning message from untrusted source is disallowed -->

  <characteristic type="SecurityPolicy">
    <parm name="4119" value="128"/>
    <parm name="4141" value="3200"/>
    <parm name="4142" value="3200"/>
    <parm name="4143" 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>

Remarks

For the device to decode correctly, provisioning XML that contains the APPLICATION characteristic must support OMA Client Provisioning version 1.1.

The APPLICATION characteristic specifies information about the server. The INIT parameter 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.

ROLE is a Microsoft custom parameter. 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 and USER_AUTHENTICATED authority (ROLE = 24).

Note

The security roles of the DM server account are the same as the bootstrap message unless they are explicitly set by using the ROLE parameter. The DM server account cannot have more roles than those of the bootstrap message. A DM server can configure a setting if the security role of the server is the same as the role granted to the setting. For example, the DM server can configure settings with manager level access only if the manager role is included in the ROLE values.

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 w7 APPLICATION Configuration Service Provider.

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

Windows Mobile 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 parameter 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 and Authenticated User.
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.

For information about the provisioning file syntax for different OMA Client Provisioning versions, see OMA Client Provisioning Files.

Bootstrapping To Use An OMA DM Server

Code Example

Remarks

See Also

Concepts

Other Resources

Additional resources