diff --git a/specs/EnhancedSecurityModeLevel.md b/specs/EnhancedSecurityModeLevel.md new file mode 100644 index 000000000..62189e576 --- /dev/null +++ b/specs/EnhancedSecurityModeLevel.md @@ -0,0 +1,149 @@ +EnhancedSecurityModeLevel +=== + +# Background + +Enhanced Security Mode (ESM) is a Microsoft Edge security feature that reduces +the risk of memory-related vulnerabilities by disabling JavaScript Just-in-Time +(JIT) compilation and enabling additional operating system protections. + +In WebView2, ESM is off by default to avoid performance impact. You can enable +ESM for stricter security when rendering untrusted sites. While this improves +security, it may reduce JavaScript performance. + +In Microsoft Edge, ESM offers two levels: + +- Balanced – Enhanced security is used for unfamiliar sites based on browser usage patterns. +- Strict – Enhanced security is used for all sites. + +![image](https://github.com/MicrosoftEdge/WebView2Feedback/assets/82386753/35977716-e46c-4257-82da-906b0c6f833e) + +Unlike Microsoft Edge, WebView2 does not support the heuristic-based "Balanced" +level; only Off and Strict are available. + +Today, the ESM level in WebView2 can be set only at environment creation by using +the `--sdsm-state` browser feature flag ([webview2 browser flag docs](https://learn.microsoft.com/en-us/microsoft-edge/webview2/concepts/webview-features-flags?tabs=dotnetcsharp)). +The setting applies globally to all profiles and cannot be changed at runtime. + +This proposal introduces an API to configure the Enhanced Security Mode level. +The configuration is persisted for a WebView2 profile within the user data folder. + +# Description + +The `EnhancedSecurityModeLevel` property allows you to control the Enhanced Security +Mode level for WebView2 instances associated with a profile. This level applies to the +context of the profile. That is, all WebView2s sharing the same profile are affected +and the value is persisted in the user data folder. + +The default value is `COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL_OFF`. + +When set to `Off`, Enhanced Security Mode is completely disabled. When set to +`Strict`, the feature is enabled and applies strict security policies to all sites. + +See `COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL` for descriptions of levels. + +Changes apply to future navigations; reload may be required to see the effect. + +# Examples + +## EnhancedSecurityModeLevel + +Set Enhanced Security Mode level for a profile. + +```c# +void SetEnhancedSecurityModeLevel(CoreWebView2EnhancedSecurityModeLevel value) +{ + var profile = webView2.CoreWebView2.Profile; + profile.EnhancedSecurityModeLevel = value; + MessageBox.Show(this, + "Enhanced Security Mode level is set successfully", + "Enhanced Security Mode"); +} +``` + +```cpp +void SettingsComponent::SetEnhancedSecurityModeLevel( + COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL value) +{ + wil::com_ptr webView2_13; + webView2_13 = m_webView.try_query(); + + if (webView2_13) + { + wil::com_ptr profile; + CHECK_FAILURE(webView2_13->get_Profile(&profile)); + + auto profile12 = profile.try_query(); + if (profile12) + { + CHECK_FAILURE(profile12->put_EnhancedSecurityModeLevel(value)); + MessageBox( + nullptr, + L"Enhanced Security Mode level is set successfully", + L"Enhanced Security Mode", MB_OK); + } + } +} +``` + +# API Details + +``` +/// Enhanced Security Mode levels. +[v1_enum] +typedef enum COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL { + /// Enhanced Security Mode is turned off. + COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL_OFF, + /// Enhanced Security Mode is enabled in Strict level. Disables JavaScript + /// Just-in-Time (JIT) compilation and enables additional OS protections. + /// + /// This level applies enhanced security for all sites but may reduce JavaScript performance. + /// + /// See [Browsing more safely with Microsoft Edge](https://learn.microsoft.com/en-us/DeployEdge/microsoft-edge-security-browse-safer) + /// for more details about Enhanced Security Mode. + COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL_STRICT, +} COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL; + +/// Extension of ICoreWebView2Profile to control Enhanced Security Mode (ESM) level. +/// +/// ESM reduces the risk of memory-related vulnerabilities by disabling JavaScript +/// Just-in-Time (JIT) compilation and enabling additional OS protections. +/// This property applies to all WebView2 instances sharing the same profile and +/// is persisted in the user data folder. +/// +/// See `COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL` for descriptions of levels. +/// +/// If `EnhancedSecurityModeLevel` is set, the property value is persisted in the profile. +/// Changes apply to future navigations; reload may be required. +/// +/// Enabling ESM improves security but may reduce JavaScript performance. +[uuid(450fab50-f6d8-4517-baea-964ec12d5c8c), object, pointer_default(unique)] +interface ICoreWebView2Profile12 : IUnknown { + /// Gets the `EnhancedSecurityModeLevel` property. + [propget] HRESULT EnhancedSecurityModeLevel([out, retval] COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL* value); + + /// Sets the `EnhancedSecurityModeLevel` property. + [propput] HRESULT EnhancedSecurityModeLevel([in] COREWEBVIEW2_ENHANCED_SECURITY_MODE_LEVEL value); +} +``` + +```c# (but really MIDL3) +namespace Microsoft.Web.WebView2.Core +{ + enum CoreWebView2EnhancedSecurityModeLevel + { + Off = 0, + Strict = 1 + }; + + runtimeclass CoreWebView2Profile + { + // ... + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Profile12")] + { + // ICoreWebView2Profile12 members + CoreWebView2EnhancedSecurityModeLevel EnhancedSecurityModeLevel { get; set; }; + } + } +} +```