FPCTunnelPortRange Object

Article
08/13/2010

The FPCTunnelPortRange object defines a tunnel port range. A tunnel port range specifies one or more ports on which the Forefront TMG Web proxy can forward an HTTP CONNECT request from a Web proxy client to a Web server. After a connection is established, packets sent from the client to the Web server on the port specified in the CONNECT request pass directly to the Web server without deep inspection by the Web proxy.

Ports that are included in tunnel port ranges are useful for passing packets with an encrypted payload, particularly Secure Sockets Layer (SSL) packets, through the Web proxy after a connection is established between a client on a protected network and an external Web server. When SSL-encrypted traffic is sent, Forefront TMG can inspect only the IP and TCP headers. The Forefront TMG computer cannot perform application-layer inspection of the encrypted contents in the SSL tunnel between the client and Web server.

When a client specifies the HTTPS protocol (HTTP over SSL) in a URL in a CERN-compliant Web browser configured to send requests to port 8080 (the default port number) on a Forefront TMG computer, the Web browser sends the following HTTP CONNECT request:

CONNECT host_name:443 HTTP/1.1

The number 443 is the default TCP port for SSL, but any port specified in the URL will be used.

By default, the Forefront TMG computer listens for outbound requests from clients in the Internal network on port 8080. When the CONNECT request reaches the Forefront TMG computer on the listening port, the Microsoft Firewall service checks the rules to determine whether a request may be sent from the source to the destination using the HTTP protocol. If the request passes the rules check, the Firewall service forwards the request to the Forefront TMG Web proxy, and the Web proxy determines whether the port specified in the CONNECT request is included in a tunnel port range. If the port number passes this test, the Web proxy allows the request to be sent to the TCP port specified on the destination host to open a connection. When this operation succeeds, the Forefront TMG computer informs the client that the connection has been established. From that point on, the client sends encrypted packets directly to the destination on the port specified in the CONNECT request without any mediation by the Web proxy.

An encrypted SSL tunnel is created only when the Forefront TMG computer connects to an SSL server using a port that is defined as a tunnel port by including it in a tunnel port range. When a Web proxy client tries to connect to an SSL server that is configured for a port that is not included in a tunnel port range, the connection attempt fails.

By default, the external port ranges that are defined as tunnel port ranges are confined to the range 443-443 (the single port 443) for HTTP over SSL and to the range 563-563 (the single port 563) for the Network News Transfer Protocol over SSL (NNTPS). You can use the properties of the FPCTunnelPortRange object to change the range of tunnel ports defined by the object, and you can use the AddRange method to create an additional tunnel port range. However, because traffic sent to ports included in a tunnel port range bypasses the Forefront TMG policy rules and Web proxy inspection, only tunnel port ranges for which this is required should be added.

This object is created as an element of an FPCTunnelPortRanges collection.

Dd421339.bkbutton(en-us,MSDN.10).png Click here to see the Forefront TMG object hierarchy.

Methods

The FPCTunnelPortRange object defines the following methods.

Method	Description
Refresh	Reads the values of all of the object's properties from persistent storage, discarding any changes that have not been saved.
Save	Writes the current values of all of the object's properties to persistent storage.

Properties

The FPCTunnelPortRange object defines the following properties.

Property	Description
Name	Gets or sets the name of the tunnel port range.
TunnelHighPort	Gets or sets the high end of the tunnel port range.
TunnelLowPort	Gets or sets the low end of the tunnel port range.

Interfaces for C++ Programming

This object implements the IFPCTunnelPortRange interface.

Example Code

The following VBScript code shows how to create a new tunnel port range consisting of a single port.

' Define the constants needed.
Const NewRangeName = "SSL 3520"
Const NewRangePort = "3520"
' Create the root object.
Dim root  ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
'Declare the other objects needed.
Dim isaArray     ' a Forefront TMG array object
Dim tpRanges     ' An FPCTunnelPortRanges collection
Dim newRange     ' An FPCTunnelPortRange object
' Get a reference to the array and to
' the collection of tunnel port ranges.
Set isaArray = root.GetContainingArray()
Set tpRanges = isaArray.ArrayPolicy.WebProxy.TunnelPortRanges
' Create a new tunnel port range.
Set newRange = tpRanges.AddRange(NewRangeName, NewRangePort, NewRangePort)
' Save the changes to the collection of tunnel port ranges
' with fResetRequiredServices set to True to restart the Firewall service.
tpRanges.Save True

Requirements

Client	Requires Windows 7 or Windows Vista.
Server	Requires Windows Server 2008 R2 or Windows Server 2008 x64 Edition with SP2.
Version	Requires Forefront Threat Management Gateway (TMG) 2010.
IDL	Declared in Msfpccom.idl.