Implementing a Custom Security Manager

Applications can manage the default URL security zone settings by using the IInternetZoneManager interface; however, any changes made with IInternetZoneManager are not static, because the user can override them. In most cases, applications that need to control the URL security zone settings should host the WebBrowser Control or MSHTML, and should implement their own security manager.

This documentation assumes that you have an understanding of Microsoft Win32 programming. You should also have an understanding of OLE and COM programming, as well as an understanding of the format and syntax of URLs. For more information, see RFC1738: Uniform Resource Locators (URL).

To compile programs that use the features provided by URL security zones, make sure the Urlmon.h header file is in the include directory, and the Urlmon.lib library file is in the library directory, of the C/C++ compiler you use.

This topic contains the following sections.

• Handling URL Security Zones
  • Interfaces related to URL security zones:
  • Applications Hosting the WebBrowser Control or MSHTML
  • Components Hosted by MSHTML
• Creating a Customized URL Security Manager
• Accessing the Default Managers
• Related topics

Handling URL Security Zones

There are two situations in which you would use the URL security zone interfaces:

• Applications that host either the WebBrowser Control or MSHTML and that will implement their own security manager to handle security zones.
• Controls that are hosted by MSHTML and that will get information about a security setting.

Interfaces related to URL security zones:

• IInternetHostSecurityManager
• IInternetSecurityManager
• IInternetSecurityMgrSite
• IInternetZoneManager

To access the new security zone lockdown, Microsoft Internet Explorer 6 for Windows XP Service Pack 2 (SP2) has two extended interfaces and a new interface.

• IInternetSecurityManagerEx—This interface extends IInternetSecurityManager so that Windows Internet Explorer can retrieve the URL policies from the locked-down security zone, as well as from the normal security zones.
  • The IInternetSecurityManagerEx::ProcessUrlActionEx method determines the policy for a specified action and displays a prompt if the policy calls for one. If FEATURE_PROTOCOL_LOCKDOWN is enabled for the current process and if URLACTION_ALLOW_RESTRICTEDPROTOCOLS is set to either URLPOLICY_DISALLOW or URLPOLICY_QUERY for the zone of the URL, the caller can indicate that the URL value can be read from the Lockdown zones, using the pdwOutFlags parameter. ProcessUrlActionEx informs the caller about the choice of zone setting made through the dwFlags parameter.
• IInternetZoneManagerEx—This interface extends IInternetZoneManager so that Internet Explorer can either retrieve the policy associated with a specified URL action or set the action policy associated with a zone. The extended interface enables Internet Explorer to perform these actions in both the locked-down security zone and the normal security zones.
• IZoneIdentifier—This new interface provides methods for getting and setting the security zone for a file.

Applications Hosting the WebBrowser Control or MSHTML

The WebBrowser Control or MSHTML hosts could create a security manager (by implementing the IInternetSecurityManager interface) that handles the URL actions and policies that are important to the host. Other URL actions and policies would be passed to the default security manager so it could handle them appropriately. The IInternetSecurityMgrSite interface would be used to handle Windows-related information from the component so that the customized security manager could handle any user interface it required.

To create a customized security manager, the component must implement the IInternetSecurityManager interface. Any methods or URL actions that the customized security manager needs the default security manager to act on should return INET_E_DEFAULT_ACTION.

Security Warning: Implementing IInternetSecurityManager methods incorrectly can compromise the security of your application. Any methods or URL actions that the customized security manager needs the default security manager to act on should return INET_E_DEFAULT_ACTION. If a method does not override default behavior and returns an HRESULT indicating success, the action is unhandled and can put users at risk for an elevation of privilege attack. You should review Security Considerations: URL Security Zones API before continuing.

The component must also implement an object that supports the IOleClientSite interface when embedding either the WebBrowser Control or MSHTML.

The following steps occur for a URL action.

1. MSHTML uses CoCreateInstance to create an instance of the Internet Security Manager.

   

2. The Internet Security Manager calls the QueryInterface method on MSHTML to get its IServiceProvider interface. MSHTML then calls the QueryInterface method on the IOleClientSite interface to get the IServiceProvider interface.

   

3. IServiceProvider::QueryService is called to get an IInternetSecurityManager interface. The component then passes a pointer to its implementation of IInternetSecurityManager to the Internet Security Manager.

   

4. Calls from MSHTML to the IInternetSecurityManager methods are passed to the custom security manager from the default Internet Security Manager.

   

5. If the method called returns INET_E_DEFAULT_ACTION, the default implementation of IInternetSecurityManager is used to resolve the call. Otherwise, the result from the custom security manager is returned.

   

6. The Internet Security Manager returns the result back to MSHTML.

   

Note  The URL security zone API offers support only for a single, customized security manager to delegate URL actions back to the default security manager. If more than one customized security manager is implemented, the additional security managers must explicitly find and invoke the security manager above them to allow multiple delegations to operate correctly.

 

Components Hosted by MSHTML

Components hosted by the WebBrowser Control or MSHTML might need to query the security manager for the URL policies being implemented in the URL security zone they are in. These components include script engines such as Microsoft JScript and Microsoft Visual Basic Scripting Edition (VBScript), controls, Java applets, and so on. For example, the component download mechanism in Internet Explorer must ask the security manager if it can download unsigned Microsoft ActiveX Controls. The component calls the IInternetHostSecurityManager::ProcessUrlAction method to check what the policy is on Java applets to help determine its answer.

Security Warning: Using this method incorrectly can compromise the security of your application. Upon a return value indicating S_FALSE or any error, your component should assume that the URL action is not allowed under the current policy. If your component performs an action after receiving an error, users may be at risk for an elevation of privilege attack. You should review Security Considerations: URL Security Zones API before continuing.

To query for URL policies, these components use the IInternetHostSecurityManager interface. The component must also have the address of a site interface implemented by the WebBrowser Control or MSHTML. The exact site interface would depend on the type of component being hosted. For example, a script engine should have the IActiveScriptSite interface implemented, while controls would implement an IOleClientSite interface. To get the address of this interface:

1. The component calls the QueryInterface method on the site interface to get the IServiceProvider interface. The component then calls IServiceProvider::QueryService to get the IInternetHostSecurityManager interface.

   

2. The component calls the IInternetHostSecurityManager methods. The host security manager creates an instance of the Internet Security Manager. The host security manager then adds the URL and calls the associated method on the IInternetSecurityManager interface.

   

   If a custom security manager was implemented by a host application, the default Internet Security Manager would pass the call up to the custom security manager's IInternetSecurityManager interface.

3. The IInternetSecurityManager method would return its results to IInternetHostSecurityManager, which would then pass the results to the component.

   

Creating a Customized URL Security Manager

A customized URL security manager can be created for applications that host either the WebBrowser Control or MSHTML by implementing the IInternetSecurityManager interface. Most of the IInternetSecurityManager methods, except IInternetSecurityManager::ProcessUrlAction, would need only to return INET_E_DEFAULT_ACTION to defer the call to the default security manager.

Security Warning: Implementing IInternetSecurityManager methods incorrectly can compromise the security of your application. Any methods or URL actions that the customized security manager needs the default security manager to act on should return INET_E_DEFAULT_ACTION. If a method does not override default behavior and returns an HRESULT indicating success, the action is unhandled and can put users at risk for an elevation of privilege attack. You should review Security Considerations: URL Security Zones API before continuing.

The following example shows an implementation of the IInternetSecurityManager::ProcessUrlAction method for a customized security manager that requires that data be encrypted.

HRESULT MySecurityManager::ProcessUrlAction(LPWSTR pwszUrl,
                                            DWORD dwAction,
                                            BYTE *pPolicy,
                                            DWORD cbPolicy,
                                            DWORD dwReserved)
{
    DWORD dwPolicy = URLPOLICY_ENCRYPT_REQUIRED;

    if (dwAction == URLACTION_ENCRYPT_DATA)
    {{
        if (cbPolicy >= size (DWORD))
        {
            *(DWORD *)pPOLICY = dwPOLICY;
            return S_OK;
        }
        else
            return S_FALSE;
    }
    else
        return INET_E_DEFAULT_ACTION;
}

Note  The default security manager cannot be replaced by a customized security manager.

 

Accessing the Default Managers

To access the default Internet Security Manager and Internet Zone Manager objects, the client application should use the CoCreateInstance function to create an instance of these objects.

The following sample creates an instance of both the Internet Security Manager and the Internet Zone Manager.

HRESULT hr;
IInternetSecurityManager *pSecurityMgr;
IInternetZoneManager *pZoneMgr;

hr = CoCreateInstance(CLSID_InternetSecurityManager, NULL, CLSCTX_INPROC_SERVER,
                      IID_IInternetSecurityManager, (void**)&pSecurityMgr);

hr = CoCreateInstance(CLSID_InternetZoneManager, NULL, CLSCTX_INPROC_SERVER,
                      IID_IInternetZoneManager, (void**)&pZoneMgr);

Related topics

About URL Security Zones