This paper provides information about Network Isolation for Windows operating systems. It provides guidelines for developers to determine the network boundary that a Metro style app will operate in, and what capabilities will be required to access required resources. This information applies to the following operating systems: Windows Developer Preview The current version of this paper is maintained on the web at: Network Isolation for Metro style Apps
Disclaimer: This document is provided as-is. Information and views expressed in this document, including URL and other Internet website references, may change without notice. Some information relates to prereleased product which may be substantially modified before its commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes. 2011 Microsoft. All rights reserved.
Contents
Introduction ................................................................................................................... 3 Basic Concepts................................................................................................................ 3 Boundaries ................................................................................................................. 3 Capabilities ................................................................................................................. 4 Understanding Capabilities Required by Your App ........................................................ 4 Web Client that Consumes Content ...................................................................... 5 Internet App that Consumes and Produces Content ............................................ 5 Peer-to-Peer Appss ................................................................................................ 5 Apps Used for Sharing Content across the Local Network .................................... 5 Line of Business Apps ......................................................................................... 6 Xbox Live Game with Achievements ..................................................................... 6 Multiplayer Internet Game using Cloud Services .................................................. 6 Multiplayer Games that use Proximity Features for Matchmaking ...................... 6 Internet Broadcast Apps ........................................................................................ 7 Media Content Playback Apps ............................................................................... 7 How Windows Defines and Discovers Network Boundaries.......................................... 7 How to Set Capabilities with Visual Studio 11 ............................................................... 8 Network Isolation Scenarios ........................................................................................ 10 Debugging and Troubleshooting .................................................................................. 14 LoopbackExempt...................................................................................................... 14 Debugging ................................................................................................................ 14 Summary ...................................................................................................................... 16
Introduction
The new Windows Runtime APIs enable a developer to control the security profile of an app under development. Network access is part of this application security model. Not all apps will require access to the network. However for those that do, Windows provides the appropriate level of granularity for apps to access the network securely. With network isolation, developers can define the scope of the network access required for each process, which prevents a process without the appropriate scope from accessing the specified type of network or connection. The ability to set and enforce these boundaries ensures that compromised apps have access only to networks they have explicitly been granted access to, significantly reducing the scope of their impact in other apps or the system itself.
Basic Concepts
Boundaries
The Windows Network Isolation feature enforces the network boundaries actively discovered by the operating system. The following table shows details about network boundary types. Table 1. Network Boundary Types
Type Home/Work Network Description Your local home or corporate network. It is composed of the local subnets the computer is connected to and local proxies configured as part of the network. Internet proxies are excluded from this boundary. The Internet, excluding the home or work network. This is composed of any proxy that provides access the Internet. Any network access that is not part of your home/work network is considered to be Internet.
Internet
Capabilities
Capabilities are security IDs used to enforce the boundaries at the firewall level. The values in the following table represent the networking isolation capabilities defined for Metro style apps. Table 2. Network Capabilities
Capability InternetClient Description Gives outbound access to the Internet and networks in public places such as airports and coffee shops (that is, networks where the user has designated the network as public). Most apps that require Internet should use this capability. This is the InternetClient capability in the app manifest. Gives inbound and outbound access to the Internet and networks in public places such as airports and coffee shops. Inbound access to critical ports is always blocked. Because InternetClientServer is a superset of the InternetClient capability, you do not need to declare both. This is the internetClientServer capability in the app manifest. Gives an app inbound and outbound access to the networks of the user's trusted places such as home and the enterprise he or she works for. Inbound access to critical ports is always blocked. This is the PrivateNetworkClientServer capability in the app manifest.
InternetClientServer
PrivateNetworkClientServer
Certain other capabilities may also need to be enabled in the app manifest for network access to work as expected. These capabilities are defined as GUIDs which are used by Windows to enforce the boundaries.
In a similar way, when an app listens for connections (inbound or unsolicited connections), the operating system checks the IP address that the app is attempting to listen to. The operating system then verifies that the source IP address matches the capabilities associated with the app. The following entries are general examples, and the capabilities required to support them.
Peer-to-Peer Appss
An app of this type shares and consumes content in a manner that distributes the workload across all clients involved. Network behavior involves two primary interactions: Connecting to retrieved shared content from others Allowing others to connect and get the users shared content
Because traffic will be inbound/unsolicited connections from the Internet endpoints and drive outbound/solicited connections to Internet endpoints, declare the InternetClientServer capability when you develop this kind of Metro style app. Note: This type of app does not accept connections directly to or from home/work network endpoints.
Allowing others within the home/work network to connect and get the users shared content.
Because traffic will be outbound/solicited connections to endpoints within the home network only, declare the PrivateNetworkClientServer capability when you develop this kind of Metro style app. Note: This type of app does not accept connections directly to or from Internet endpoints.
communicating. In the context of a game, this involves a task like matchmaking for multiplayer games. This kind of device interaction using an app only requires the declaration of the Proximity capability.
Tablet
Firewall
Gateway Proxy
SharePoint Server
Laptop PC
The operating system probes the network and discovers the addresses bound to each interface and which gateways are acting as exit or entry points for Internet connections. The following table gives details about the information discovered during this process. Table 3. Network Discovery Addresses and Behavior
Network Addresses and Interfaces Local addresses and subnets Behavior
Typical addresses that will be discovered as home or work network are those in these IPv4 ranges:
10.0.0.0-10.255.255.255 172.16.0.0-172.31.255.255 192.168.0.0-192.168.255.255
The operating system will treat all ipv6 local addresses as home or work network addresses, including native and transition technology addresses. IPv6 address types that will be discovered are:
Local subnet associated with the native IPV6 address Link-Local addresses (fe80::/10) Transition technology addresses (6to4, ISATAP) excluding the Teredo range (2001::/32)
In work network environments that use Active Directory, the subnets that make up the internal network are sites, and the operating system that is part of the corporate network will perform queries to Active Directory to request information. The operating system probes the network to discover gateways and proxies to the Internet. IP addresses associated with these devices are included in the Internet boundary and may be included in the local subnet. Simply put, when defining network boundaries, the Internet address range includes all addresses that are not part of the home or Network + Internet Gateway and Proxy set.
After opening the app manifest, you choose, from a control window, the capabilities that are appropriate for your app. Visual Studio provides a description of each capability to the right of the capability list.
By setting the correct capabilities for your app , you enable your scenario and ensure the app is easily on-boarded. Do not include capabilities that are not required for app functionality. This can result in a more thorough review of the app and a delay in being on-boarded.
When creating an app that will connect to the Internet, you must add the following capability to the app manifest. <?xml version="1.0" encoding="utf-8"?> <Package xmlns=""> <Identity Name="" Version="" Publisher="" /> <Properties> <DisplayName></DisplayName> <PublisherDisplayName></PublisherDisplayName> <Logo></Logo> </Properties> <Resources> <Resource Language="" /> </Resources> <Prerequisites> <OSMinVersion></OSMinVersion> <OSMaxVersionTested></OSMaxVersionTested> </Prerequisites> <Capabilities> <Capability Name="internetClient"/> </Capabilities>
September 13, 2011 2011 Microsoft. All rights reserved.
<Apps> <Application Id="" StartPage=""> <VisualElements DisplayName="" Description="" Logo="" SmallLogo="" ForegroundText="" BackgroundColor="" ToastCapable=""> <DefaultTile ShortName="" ShowName="" WideLogo="" /> <SplashScreen BackgroundColor="" Image="" /> </VisualElements> </Application > </Apps> </Package> By indicating this capability, when the app attempts to connect to an Internet endpoint the firewall element will: Allow the DNS name resolution for this destination. With the Application ID and the capabilities associated with it, make a decision about allowing a connection to the target IP-address (65.55.206.203). Because the app has InternetClient capability, allow the app to connect to the target endpoint.
Regardless of the environmental conditions of the computer where the app is running, the connection will succeed as long as there is a discoverable Internet gateway or proxy. Note The proxy may request additional information to connect to the Internet. In this case, the user will need to provide the requested information in order to access the Internet.
Connect to the Internet as Client-Server
When creating an app that listens for connections from the Internet declare the InternetClientServer capability in the app manifest. This allows the app to connect to Internet endpoints. As a result, it is not necessary to declare InternetClient when InternetClientServer capability is used. <?xml version="1.0" encoding="utf-8"?> <Package xmlns=""> <Identity Name="" Version="" Publisher="" /> <Properties> <DisplayName></DisplayName> <PublisherDisplayName></PublisherDisplayName> <Logo></Logo> </Properties> <Resources> <Resource Language="" /> </Resources> <Prerequisites> <OSMinVersion></OSMinVersion> <OSMaxVersionTested></OSMaxVersionTested> </Prerequisites>
September 13, 2011 2011 Microsoft. All rights reserved.
<Capabilities> <Capability Name="internetClientServer"/> </Capabilities> <Apps> <Application Id="" StartPage=""> <VisualElements DisplayName="" Description="" Logo="" SmallLogo="" ForegroundText="" BackgroundColor="" ToastCapable=""> <DefaultTile ShortName="" ShowName="" WideLogo="" /> <SplashScreen BackgroundColor="" Image="" /> </VisualElements> </Application > </Apps> </Package> The system will operate as follows: The app attempts to listen on a port bound to the system IP address. The firewall looks at the Application ID and the capabilities associated with this app to make a decision to allow or block this operation. Upon approval, the app can listen on that particular port. For every inbound/unsolicited connection request, the firewall evaluates the source IP address of the connection request and decides whether to allow or block it.
When creating apps that require the capability to listen or connect to a local endpoint (an IP address confined to the local network), declare the privateNetworkClientServer capability. <?xml version="1.0" encoding="utf-8"?> <Package xmlns=""> <Identity Name="" Version="" Publisher="" /> <Properties> <DisplayName></DisplayName> <PublisherDisplayName></PublisherDisplayName> <Logo></Logo> </Properties> <Resources> <Resource Language="" /> </Resources> <Prerequisites> <OSMinVersion></OSMinVersion> <OSMaxVersionTested></OSMaxVersionTested> </Prerequisites> <Capabilities> <Capability Name="privateNetworkClientServer"/> </Capabilities>
September 13, 2011 2011 Microsoft. All rights reserved.
<Apps> <Application Id="" StartPage=""> <VisualElements DisplayName="" Description="" Logo="" SmallLogo="" ForegroundText="" BackgroundColor="" ToastCapable=""> <DefaultTile ShortName="" ShowName="" WideLogo="" /> <SplashScreen BackgroundColor="" Image="" /> </VisualElements> </Application > </Apps> </Package> The system will operate as follows: The app attempts to listen on a port bound to the system IP address. The firewall looks at the Application ID and the capabilities associated with this app to make a decision to allow or block this operation. Upon approval, the app can listen on that particular port. For every inbound/unsolicited connection request, the firewall evaluates the source IP address of the connection request and decides whether to allow or block it.
Use the loopback interface for intra-process and inter-process communication. However, inter-process communication is fundamentally a violation of the boundary isolation model, and Metro style apps are encouraged to avoid using the loopback interface for this type of communication. To that end, the system prevents interprocess communication by default over the loopback interface. To exempt the loopback restriction for inter-process communication, the app can be configured in LoopbackExempt mode. For more information about this mode, see LoopbackExempt. Note: The system permits loopback communication for intra-process communication by a Metro style app process when implementing any of the networking capabilities detailed in this white paper.
Network Isolation and Proximity Scenarios
The Network Isolation feature fully integrates with the Windows Runtime Proximity components. When declaring the Proximity capability, there is no need to indicate additional networking capabilities.
Network Isolation and PlayTo Scenarios
PlayTo allows apps to connect to machine endpoints within the home/work network. The Networks Isolation feature fully integrates with PlayTo components. When declaring the PlayTo capability, there is no need to indicate additional networking capabilities.
LoopbackExempt
In scenarios where the developer is creating a client app on the computer where the server is running, the communication between the client and the server needs to occur over the loopback interface. However, the operating system blocks this interface by default for inter-process communication by Metro style apps. With this module, the tool exposes a functionality that allows the developer to make an app exempt from the loopback restriction. The following examples demonstrate methods of making Metro style apps exempt from the loopback restriction.
To Make Your App Exempt by Package ID (SID)
%windir%\system32\CheckNetIsolation.exe LoopbackExempt c
To See All Apps that are LoopbackExempt
%windir%\system32\CheckNetIsolation.exe LoopbackExempt s
Debugging
After submitting a Metro style app to the Windows Store, the app review process scrutinizes the number and type of capabilities the app declares. Rejection occurs if too many overpowering capabilities are declared. For that reason, developers are encouraged to declare only the capabilities their apps will actually use. This module exposes a clear way to identify whether an app is using all declared capabilities. By using these commands, the troubleshooter is instructing the tool to track which of the declared capabilities your app is actually using.
Steps required when using this tool
1. Deploy your app on the target computer. 2. Under c:\Program Files\Apps, find the app name _pubhash. This is the name you will need to pass as a parameter.
3. Alternatively you can get the package SID by looking at the regkey under HKEY_CURRENT_USER\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppContainer 4. Open a command-line window with elevated privileges. 5. Run either of these commands : To debug your app using Package ID %windir%\system32\CheckNetIsolation.exe Debug p= S-1-15-24125766819-3228448775-2449327860-2490758337-12642418653581724871-2122349299 To debug your app using AppContainer name %windir%\system32\CheckNetIsolation.exe Debug n=stocks_mw26f2swbd5nr 6. Launch your app and test for operations your app will normally perform. 7. Press CTRL+C. 8. The output will look like this.
9. When overpowering capabilities are declared, the output will look like this.
Summary
When developing Metro style apps, Network Isolation helps your product to take advantage of the isolation mechanisms that will keep the app and system secure. By using these mechanisms, Windows can select the appropriate security profile required for your app to operate.