Security Settings in HTML Bridge
Microsoft Silverlight will reach end of support after October 2021. Learn more.
In Silverlight, three security settings control how Silverlight interacts with JavaScript and Document Object Model (DOM) code in same-domain access and cross-domain access scenarios:
The EnableHtmlAccess parameter, which is set on the Silverlight plug-in on the host page, prevents a malicious cross-domain Silverlight-based application from accessing the host page's JavaScript and DOM code.
The ExternalCallersFromCrossDomain deployment manifest attribute prevents a malicious cross-domain host from accessing scriptable properties, methods, or events that are exposed by the Silverlight-based application.
The AllowHtmlPopupwindow parameter, which is set on the Silverlight plug-in on the host page, controls pop-up windows that are opened by cross-domain Silverlight-based applications. When this attribute is set to false (the default when the Silverlight control is loaded from a different domain than the containing page or hosting iframe), a developer cannot call HtmlPage.PopupWindow.
The following table summarizes access from the point of view of the Silverlight plug-in.
Access direction |
Security setting |
Control location |
|---|---|---|
Outbound (Silverlight to JavaScript and DOM) |
enableHtmlAccess |
Host HTML page |
Inbound (JavaScript and DOM to Silverlight managed code) |
ExternalCallersFromCrossDomain |
Silverlight .xap file |
.gif "Note") Note: |
|---|
|
.png "Silverlight for Windows Phone"){kind=icon}
Silverlight for Windows Phone does not support the HTML Bridge feature.Outbound Calls from Silverlight to JavaScript
The enableHtmlAccess parameter is set on the Silverlight plug-in. It enables managed code in the .xap file to access the JavaScript and DOM code on the host page. This parameter can be set only during plug-in initialization, and is read-only afterward. For same-domain applications, the parameter is set to true by default, and you do not have to explicitly set its value in code. For cross-domain applications, the parameter is set to false by default, and you have to explicitly enable it, as shown in the following host page HTML code.
<div id="silverlightControlHost">
<object data="data:application/x-silverlight-2,"
type="application/x-silverlight-2"
width="300" height="100"
<param name="source"
value="http://www.northwindtraders.com/MySample.xap"/>
<param name="enableHtmlAccess" value="true" />
</object>
</div>
When the enableHtmlAccess parameter is set to true, as shown in the previous example, the following HtmlPage properties are enabled:
.gif "Caution note") Caution: |
|---|
When a host page enables HTML access, it gives the Silverlight-based application complete access to its DOM, including the ability to modify content, insert and evaluate JavaScript code, and so on. This access should be allowed only if the host page trusts the Silverlight-based application. HTML access is enabled by default for same-domain Silverlight-based applications, because there is implicit trust between HTML and same-domain Silverlight content. However, access must be specifically enabled for cross-domain applications. |
When the enableHtmlAccess parameter is set to false (the default for cross-domain applications), the previous properties are disabled, and they throw exceptions instead of returning values. Therefore, Silverlight code is prevented from directly obtaining references to DOM or JavaScript objects. In addition, the enableHtmlAccess parameter cannot be set to true after the Silverlight Web object has been initialized.
enableHtmlAccess Workarounds
When the enableHtmlAccess parameter is set to false, direct access to JavaScript or DOM elements and objects is not possible. However, individual, specific access can be programmatically re-established in the following cases:
Silverlight code exposes one or more scriptable entry points that accept ScriptObject references as input parameters.
Silverlight code explicitly registers the scriptable entry points by calling the RegisterScriptableObject method.
Access to scriptable entry points is not disabled with the ExternalCallersFromCrossDomain attribute.
JavaScript code accesses the plug-in's Content property, obtains a reference to one of the scriptable entry points, and passes a DOM object or JavaScript object reference as an input parameter.
| Note: |
|---|
These conditions cannot occur by accident. The Silverlight managed code and the JavaScript code must each be written specifically to allow mutual access. |
How to Retrieve the enableHtmlAccess Value
Silverlight managed code can obtain the value of the plug-in's enableHtmlAccess parameter by getting the Settings.EnableHTMLAccess or HtmlPage.IsEnabled property.
Inbound Calls from JavaScript to Silverlight
The ExternalCallersFromCrossDomain attribute controls JavaScript and DOM access to scriptable objects that are defined in cross-domain .xap files.
The attribute has no effect in same-domain .xap files. Access is disabled by default in cross-domain .xap files.
The attribute is set on the root element of the application manifest, as shown in the following Silverlight deployment code.
<Deployment xmlns="https://schemas.microsoft.com/client/2007"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
EntryPointAssembly="MyAppAssembly"
EntryPointType="MyNamespace.MyApplication"
ExternalCallersFromCrossDomain="ScriptableOnly"
>
<Deployment.Parts>
<AssemblyPart Source="MyAppAssembly.dll" />
<AssemblyPart Source="MyUserControl.dll" />
</Deployment.Parts>
</Deployment>
The ExternalCallersFromCrossDomain attribute accepts two values: ScriptableOnly and NoAccess.
When the attribute is set to ScriptableOnly, the host's native JavaScript can only access scriptable objects that the Silverlight application code registers with the runtime. It cannot query or set properties on any other objects. Additionally, it will not receive event notifications.
| Caution: |
|---|
The ScriptableOnly value will allow a cross-domain .xap file to programmatically call any scriptable objects that are explicitly exposed by the application. |
When the ExternalCallersFromCrossDomain attribute is set to NoAccess, scriptable entry points and creatable types are not available to JavaScript or DOM through Content and createObject. Although managed calls to RegisterScriptableObject, RegisterCreateableType, and so on will appear to succeed (exceptions to managed code are not thrown), the registered entry points and types will not be available through Content or createObject.
Application Manifest
The application manifest is created by default when you build your Silverlight project. If you are using Visual Studio, you can disable manifest generation by clearing the Generate Silverlight manifest file check box in the Properties window, Silverlight tab. (To open the Properties window, click Properties on the Project menu.)
If manifest generation is disabled, you will not be able to set the ExternalCallersFromCrossDomain attribute.
ExternalCallersFromCrossDomain Workarounds
When the ExternalCallersFromCrossDomain attribute is set to NoAccess, direct access to Silverlight managed code is not possible. However, individual, specific access can be programmatically re-established if the following conditions are true:
The Silverlight plug-in's enableHtmlAccess property is set to true.
Silverlight managed code calls a JavaScript function and passes one or more managed objects as input parameters to the Invoke, InvokeSelf, and SetProperty methods.
The managed instances passed in the previous step have scriptable properties, methods, or events, and the objects have been registered for scriptable access by using the RegisterScriptableObject method.
| Note: |
|---|
These conditions cannot occur by accident. They require explicit steps by the cross-domain Silverlight-based application to pass managed objects to the host's JavaScript. |
How to Retrieve the ExternalCallersFromCrossDomain Value
You can get the current value of the ExternalCallersFromCrossDomain attribute from the ExternalCallersFromCrossDomain read-only property. This property returns a CrossDomainAccess value that indicates the access level of cross-domain callers.
See Also