SoftwareDisable Configuration Service Provider

4/8/2010

The SoftwareDisable Configuration Service Provider makes possible secure block–listing of binary files in the ROM of a device by using Group Policy management. If the user or other applications try to call block-listed binaries, an application execution prompt is displayed informing the user why the application is disabled. The SoftwareDisable Configuration Service Provider also makes possible secure allow-listing of unsigned binary files in RAM to enable running files that are not otherwise authorized to run due to device policy.

The SoftwareDisable Configuration Service Provider is managed over both the OMA DM protocol and the OMA Client Provisioning protocol.

The default security role to access the SoftwareDisable Configuration Service Provider is Manager.

Note

Access to this Configuration Service Provider is determined by security roles. Because OEMs and mobile operators can selectively disallow access, ask them about the availability of this Configuration Service Provider. For more information about roles, see Security Roles and Default Roles for Configuration Service Providers.

The following image shows the SoftwareDisable Configuration Service Provider management object in tree format as used by OMA DM.

The following image shows the SoftwareDisable Configuration Service Provider management object in tree format as used by OMA Client Provisioning.

Characteristics

• SoftwareDisable
  The root node of the SoftwareDisable Configuration Service Provider.

  Type Microsoft.com/windowsMobile/1.0/SwDisableMO

  Permissions	Get
  Data type	node
  Occurs	One

• DisabledSystemFiles
  Groups disabled files from the MODULES or FILES section of ROM. This is the block list of in-ROM files that are not authorized to run.

  Binary file name values to be added to DisabledSystemFiles must first be converted to Unicode, then UTF-8 encoded, and then URI escaped before they are sent to the device.

  Permissions	Get, Add, Delete
  Data type	node
  Occurs	One

• EnabledInstalledFiles
  Groups enabled binary files from persistent storage.

  Permissions	Get, Add, Delete
  Data type	node
  Occurs	One

• SHA1
  Groups binary hashes that are generated with the SHA1 hash algorithm. This is an allow list of files that are authorized to run. These files must be identified by their hash.

  Permissions	Get, Add, Delete
  Data type	node
  Occurs	One

• {Binhash}
  Placeholder for one binary file on the allow list. {Binhash} is a B64 encoded SHA1 hash of a binary file. If the file is signed, the signature part of the file is excluded. Deleting an instance of this characteristic will remove the file from the allow list.

  Permissions	Get, Add, Delete, Replace
  Data type	node
  Occurs	ZeroOrMore

Parameters

• {binary file name}
  Specifies a single entry on the block list. Optionally, you can assign a friendly name to the entry in addition to the binary filename.

  Permissions	Get, Add, Delete, Replace
  Data type	chr
  Occurs	ZeroOrMore

• PrivilegeLevel
  Specifies whether to enable an application on the allow list to run in trusted or normal security mode.

  Note

  If an application is allowed to run but is not on the allow list, the running permissions are based on the certificate and the 2-tier security policy value.

  The valid values for this parameter are as follows:

  • 1 - Normal (Default value)
  • 2 - Trusted

  Permissions	Get, Add, Delete, Replace
  Data type	int
  Occurs	ZeroOrOne

• FileName
  Holds the application name. This parameter is used by the server to track which applications are on the allow list.

  Permissions	Get, Add, Delete, Replace
  Data type	chr
  Occurs	ZeroOrOne

• NotificationString
  The string that is shown when a process tries to access a binary file that is block-listed, or install a .cab file that is not permitted. If no string is specified, the default string will be shown.

  The %1 variable represents the block-listed file name and %2 represents the friendly name of the block-listed file. These variables can be inserted in the string and the device will replace them with the actual names at runtime.

  Note

  If the string contains the %2 variable but there is no friendly name specified for the block-listed application, %2 will be replaced by an empty string.

  The maximum string length is 256 characters. If it is longer than allowed length it will be truncated.

  Permissions	Get, Add, Delete, Replace
  Data type	chr
  Occurs	ZeroOrOne

• DisableNotification
  Disables the runtime application disable notification dialog box.

  The behavior for the valid values is as follows:

  • True: The runtime application disabled notification is not shown.
  • False or not present: The runtime application disabled notification is shown.

  Permissions	Get, Add, Delete, Replace
  Data type	bool
  Occurs	ZeroOrOne

Microsoft Custom Elements

The following table shows the Microsoft custom elements that this Configuration Service Provider supports for OMA Client Provisioning.

Elements	Available
parm-query	Yes
noparm	Yes
nocharacteristic	Yes
characteristic-query	Yes Recursive: Yes Root level of the Configuration Service Provider: Yes

Use these elements to build standard OMA Client Provisioning configuration XML. For information about specific elements, see MSPROV DTD Elements. For general examples of how to use the Microsoft custom elements, see OMA Client Provisioning XML File Examples.

For information about OMA Client Provisioning, see OMA Client Provisioning Files.

Remarks

The device’s Grant Manager security policy value must not include the User_Authenticated role and RAPI policy must not be set to Open. This prevents the user from changing the software disable configuration set by the device manager. For more information about security roles see Security Roles.**

If an in-ROM application is block-listed and the binary file is already on the device in the FILES section of ROM when the block list is deployed, the device will use the file to generate the file hash and add it to the revocation list.

If the file is not on the device when the block list is deployed, the device cannot automatically generate the revocation hash. If the file is later added to the device the in-ROM execution of the file will be blocked, but the user can still copy the in-ROM file to RAM and execute it. To prevent this, the device manager should either reapply the in-ROM block list after the file is on the device, or put the file hash in the revocation list by using the LoaderRevocation Configuration Service Provider.

To allow-list a binary that is in the device RAM, if the administrator does not have the .cab installation file, copy the binaries to the desktop by using Desktop ActiveSync, and then use the hash tool that is provided in the Windows Mobile 6.1 package to generate a hash of the binaries.

This Configuration Service Provider allows the device manager to block-list in ROM applications and there could be adverse and unexpected results. If the device manager plans to block-list an application which is not listed in the default admin console UI, thorough testing is needed to make sure that the action does not break anything before deploying the change to the device.

The device will prompt a restart after either the allow list or the block list is updated.

See Also

Concepts

Configuration Service Provider Reference for Windows Mobile Devices
SoftwareDisable Configuration Service Provider Examples for OMA DM
SoftwareDisable Configuration Service Provider Examples for OMA Client Provisioning
SoftwareDisable DDF File