RAPI Restricted Mode Security

  • Article

Send Feedback

With the release of Windows Mobile 5.0, RAPI restricted mode was introduced for Windows Mobile-based devices. Previously, Windows Mobile-based Pocket PCs had no such security policy. Restricted mode behaves the same on both Windows Mobile-based Pocket PCs and Smartphones and has implications for both Remote API and Remote API 2 functions.

You can provide increased security for Windows Mobile-based Pocket PCs or Smartphones by using security policies and specifically by using the RAPI security policy. The RAPI security policy provides the following options:

  • Closed Mode. All RAPI calls are disabled and access to ActiveSync is denied.
  • Restricted Mode. RAPI calls and access to ActiveSync are enabled. In restricted mode, files in ROM and files that have the System flag set are read-only through RAPI. Also, only signed dlls and dlls that have been added to the RAPI section of the metabase can be invoked with RAPI. For more information on adding a dll to the metabase, see the section on CeRapiInvoke below. Also, in restricted mode, protected registry keys are read-only through RAPI. When a device is running in restricted mode and an application attempts to use RAPI to access a restricted file, dll, or registry key, there is no dialog displayed on the device prompting the user to allow the operation. The RAPI method invoked will simply fail. For a list of the protected registry keys, see Privileged APIs.
  • Open Mode. Enable full access to all RAPI calls and access to ActiveSync. This is the least secure mode. An attacker could potentially put a .dll on the device using RAPI, use CeRapiInvoke to run it privileged, and thereby compromise security.

To help provide a higher level of security for a device while allowing the use of RAPI, it is recommended that you set the RAPI Policy to restricted mode and then allow access to individual dlls and databases by modifying the metabase.

RAPI Restricted Mode and CeRapiInvoke

CeRapiInvoke loads the device-side DLL named in pDllPath, then calls the RAPI extension named in pFunctionName.

It is the responsibility of the RAPI extension to release the IRAPIStream object (that is, to call pIRAPIStream->Release();).

As of Windows Mobile Version 5.0, the Remote Access Security Policy on Smartphone and Pocket PC is set to Restricted by default. These devices are considered "Locked," which prevents you from using CeRapiInvoke to invoke device-side DLLs — unless you take extra steps to satisfy the requirements of the Remote Access Security Policy. For more information on RAPI security, see Security for Windows Mobile-based Devices.

Note   Even if it is locked, CeRapiInvoke is permitted on the non-phone version of Pocket PC.

CeRapiInvoke gives elevated privileges to any DLL that can be invoked on the Windows Mobile–based device.

RAPI security policies are set in the project.reg configuration file.

Use the following procedure if you successfully used CeRapiInvoke in the past, and it now fails under the Windows Mobile 5.0 Remote Access Security Policy.

To satisfy the requirements of the Remote Access Security Policy

  1. Create a provisioning XML document that adds the new node "RAPI" to the metabase. This node must include the absolute path to the *.DLL file. For more information, see Metabase Settings. The following code example shows the contents of a typical provisioning XML file.

    <wap-provisioningdoc>
   <characteristic type="Metabase">
      <characteristic type="RAPI\Program Files\Green Sky\recaller.dll\*">
      <parm name="rw-access" value="3"/>
      <parm name="access-role" value="152"/> <!-- 152 maps to "CARRIER_TPS | USER_AUTH | MANAGER" -->
      </characteristic>
   </characteristic>
</wap-provisioningdoc>

  2. Pass the file name of the provisioning XML document to the CAB wizard using the /postxml command line option. The CAB wizard will append the XML to the _setup.xml file it places in the CAB. For more information on creating CAB files, see CAB Wizard.

    You can also apply the settings in the XML file from code running on the device. For more information, see DMProcessConfigXML.

  3. Set the System attribute on the *.DLL file..

RAPI Restricted Mode and Database Access

By default, databases cannot be accessed by RAPI on devices running in restricted mode. Attempts to use RAPI's database functions such as CeOpenDatabase (RAPI) and CeOpenDatabaseEx (RAPI) will result in an access denied error. To access a database from RAPI, you will need to configure its permissions in the metabase with a provisioning XML file. The following example shows the XML that modifies a database's permissions to allow access from RAPI when the device is in restricted mode.

<wap-provisioningdoc>
  <characteristic type="Metabase">
    <characteristic type="Database\<db_name>\*">
      <parm name="rw-access" value="3"/>
      <parm name="access-role" value="152"/>
    </characteristic>
  </characteristic>
</wap-provisioningdoc>

In the above example <db_name> should be replaced with the name of the database for which permissions are being modified.

Before attempting to access a database in a mounted database volume, you must mount the volume using CeMountDBVol (RAPI). This action will also fail by default under RAPI restricted mode security. To use this function, you must first modify the permissions of the database volume in the metabase. The following example illustrates the provisioning XML that sets the permissions for a database volume to allow it to be mounted by RAPI.

<wap-provisioningdoc>
  <characteristic type="Metabase">
    <characteristic type="Database\\Program Files\<db_volume>\*">
      <parm name="rw-access" value="3"/>
      <parm name="access-role" value="152"/>
     </characteristic>
  </characteristic>
</wap-provisioningdoc>

In the above example <db_volume> should be replaced with the name of the database volume file for which permissions are being modified. You must include two backslashes before the path to the volume file.

The provisioning XML files for modifying the permissions of databases and database volumes can be invoked from code running on the device. For more information, see DMProcessConfigXML.

A provisioning XML file can also be invoked at installation time by passing it to the CAB wizard using the /postxml command line option when generating a CAB file. For more information, see CAB Wizard.

See Also

Remote API (RAPI) Reference | Security Best Practices | CeRapiInvoke

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.