Managing Tunnel Port Ranges
A tunnel port range specifies one or more ports on which the Microsoft® ISA Server Web proxy can forward a Hypertext Transfer Protocol (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, ISA Server can inspect only the IP and TCP headers. The ISA Server 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 an ISA Server 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 ISA Server computer listens for outbound requests from clients in the Internal network on port 8080. When the CONNECT request reaches the ISA Server 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 ISA Server 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 ISA Server 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 ISA Server 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 443–443 (the single port 443) for HTTP over SSL and 563–563 (the single port 563) for the Network News Transfer Protocol over SSL (NNTPS). Because traffic sent in an established connection to a port included in a tunnel port range bypasses the ISA Server policy rules and Web proxy inspection, only tunnel port ranges for which this is required should be added.
A single tunnel port range is represented by an FPCTunnelPortRange administration COM object, and all the FPCTunnelPortRange objects defined in an array are contained in the FPCTunnelPortRanges collection for the array. You can use the properties of the FPCTunnelPortRange object to view or modify the range of tunnel ports defined by the object, and you can use the AddRange method to create an additional tunnel port range in the FPCTunnelPortRanges collection.
The FPCTunnelPortRange object provides the following properties for defining a tunnel port range:
- Name. This property gets or sets the name of the tunnel port range. This name is initially set when the tunnel port range is created.
- TunnelLowPort. This property gets or sets the port number that marks the low end of the tunnel port range. Its value is initially set when the tunnel port range is created, and its range of permissible values is from 1 through 65535.
- TunnelHighPort. This property gets or sets the port number that marks the high end of the tunnel port range. Its value is initially set when the tunnel port range is created, and its range of permissible values is from 1 through 65535.
On This Page
Displaying the Existing Tunnel Port Ranges
Script Listing: ShowTPRanges.vbs
Script Listing: AddTPRange.vbs
Script Listing: DelTPRange.vbs
Additional Information
The Microsoft Visual Basic® Scripting Edition (VBScript) code in ShowTPRanges.vbs (listed later in this Web page) retrieves the collection of tunnel port ranges defined in the containing array, iterates through the collection, and displays the names and port ranges for the tunnel port ranges. This script must be run on an ISA Server 2004 computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.
Usage:CScript ShowTPRanges.vbs
To display the names and port ranges for the existing tunnel port ranges
Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.
Declare an FPCArray object, an
FPCTunnelPortRanges
collection, and an FPCTunnelPortRange object.Get references to the FPCArray object and the FPCTunnelPortRanges collection.
If at least one tunnel port range is defined in the collection, iterate through the collection and display the name and port range for each tunnel port range defined in the collection.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE
' RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE
' USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR WITHOUT MODIFICATION, IS
' HEREBY PERMITTED.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script retrieves the collection of tunnel port ranges defined in the
' containing array, iterates through the collection, and displays the names
' and port ranges for the tunnel port ranges.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Sub ShowTPRanges()
' Create the root object.
Dim root ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
' Declare the other objects needed.
Dim isaArray ' An FPCArray object
Dim tpRanges ' An FPCTunnelPortRanges collection
Dim tpRange ' An FPCTunnelPortRange object
' Get references to the array object
' and the collection of tunnel port ranges.
Set isaArray = root.GetContainingArray()
Set tpRanges = isaArray.ArrayPolicy.WebProxy.TunnelPortRanges
' If at least one tunnel port range is defined in the
' collection, display the names and port ranges for all
' the tunnel port ranges.
If tpRanges.Count > 0 Then
For Each tpRange In tpRanges
WScript.Echo tpRange.Name & ": " & tpRange.TunnelLowPort & _
"-" & tpRange.TunnelHighPort
Next
Else
WScript.Echo "No tunnel port ranges are defined."
End If
End Sub
ShowTPRanges
The VBScript code in AddTPRange.vbs (listed later in this Web page) includes a subprocedure that creates a new tunnel port range containing a single user-specified port to allow clients to send requests, for example, SSL requests, to that port. This script must be run on an ISA Server 2004 computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.
Usage:[CScript] AddTPRange.vbs RangeName TunnelPort
RangeName specifies the name of the new tunnel port range.
TunnelPort specifies the single port to be included in the new tunnel port range.
Example:CScript AddTPRange.vbs "SSL 3520" 3520
To create a new tunnel port range containing a single port
Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.
Declare an FPCArray object, an FPCTunnelPortRanges collection, an FPCTunnelPortRange object, and an Integer.
Get references to the FPCArray object and the FPCTunnelPortRanges collection.
Call the AddRange method on the collection with the parameters supplied by the user to create the new tunnel port range.
Call Save on the collection of tunnel port ranges to write the changes to persistent storage. Note that the fResetRequiredServices parameter is set to True to restart the Firewall service.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE
' RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE
' USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR WITHOUT MODIFICATION, IS
' HEREBY PERMITTED.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script creates a new tunnel port range containing a single user-specified
' port to allow clients to send requests, for example, SSL requests, to that
' port.
' This script can be run from a command prompt by entering the
' following command:
' CScript AddTPRange.vbs RangeName PortNumber
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
' Define the constants needed.
Const Error_TypeMismatch = &HD
Const Error_AlreadyExists = &H800700B7
Const Error_OutOfRange = &H80070057
Main(WScript.Arguments)
Sub Main(args)
If(args.Count <> 2) Then
Usage()
Else
AddTPRange args(0), args(1)
End If
End Sub
Sub AddTPRange(newRangeName, newTunnelPort)
' Create the root object.
Dim root ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
'Declare the other objects needed.
Dim isaArray ' An ISA Server array object
Dim tpRanges ' An FPCTunnelPortRanges collection
Dim newRange ' An FPCTunnelPortRange object
Dim port ' An Integer
' 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.
On Error Resume Next
port = CDbl(newTunnelPort)
If Err.Number = Error_TypeMismatch Then
WScript.Echo "A number must be entered for the port to be included."
WScript.Quit
End If
Err.Clear
Set newRange = tpRanges.AddRange(newRangeName, port, port)
If Err.Number = Error_AlreadyExists Then
WScript.Echo "A port range with the name specified already exists."
WScript.Quit
ElseIf Err.Number = Error_OutOfRange Then
WScript.Echo "The range of permissible ports is from 1 through 65535."
WScript.Quit
End If
On Error GoTo 0
' Save the changes to the collection of tunnel port ranges
' with fResetRequiredServices set to True to restart the Firewall service.
tpRanges.Save True
WScript.Echo "Done!"
End Sub
Sub Usage()
WScript.Echo "Usage:" & VbCrLf _
& " " & WScript.ScriptName & " RangeName TunnelPort" & VbCrLf _
& "" & VbCrLf _
& " RangeName - Name of the tunnel port range to be added" & VbCrLf _
& " TunnelPort - Port to be included in the new tunnel port range"
WScript.Quit
End Sub
The VBScript code in DelTPRange.vbs (listed later in this Web page) includes a subprocedure that deletes the tunnel port range having the name specified by the user. This script must be run on an ISA Server 2004 computer with the Microsoft Firewall service installed, but it can be modified to run on a remote management computer.
Usage:[CScript] DelTPRange.vbs RangeName
RangeName specifies the name of the new tunnel port range to be deleted.
Example:CScript DelTPRange.vbs "SSL 3520"
To delete the tunnel port range with the name specified by the user
Create an instance of the FPC COM object, which is known as the root object and provides access to the other ISA Server administration COM objects.
Declare an FPCArray object and an FPCTunnelPortRanges collection.
Get references to the FPCArray object and the FPCTunnelPortRanges collection.
Call the Remove method on the collection with the parameter supplied by the user to delete the tunnel port range.
Call Save on the collection of tunnel port ranges to write the changes to persistent storage. Note that the fResetRequiredServices parameter is set to True to restart the Firewall service.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' Copyright (c) Microsoft Corporation. All rights reserved.
' THIS CODE IS MADE AVAILABLE AS IS, WITHOUT WARRANTY OF ANY KIND. THE ENTIRE
' RISK OF THE USE OR THE RESULTS FROM THE USE OF THIS CODE REMAINS WITH THE
' USER. USE AND REDISTRIBUTION OF THIS CODE, WITH OR WITHOUT MODIFICATION, IS
' HEREBY PERMITTED.
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
' This script deletes the specified tunnel port range.
' This script can be run from a command prompt by entering the
' following command:
' CScript DelTPRange.vbs RangeName
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Option Explicit
' Define the constant needed.
const Error_FileNotFound = &H80070002
Main(WScript.Arguments)
Sub Main(args)
If(args.Count <> 1) Then
Usage()
Else
DelTPRange args(0)
End If
End Sub
Sub DelTPRange(rangeName)
' Create the root object.
Dim root ' The FPCLib.FPC root object
Set root = CreateObject("FPC.Root")
'Declare the other objects needed.
Dim isaArray ' An ISA Server array object
Dim tpRanges ' An FPCTunnelPortRanges collection
' Get a reference to the array and to
' the collection of tunnel port ranges.
Set isaArray = root.GetContainingArray()
Set tpRanges = isaArray.ArrayPolicy.WebProxy.TunnelPortRanges
' Delete the specified tunnel port range.
On Error Resume Next
tpRanges.Remove(rangeName)
If Err.Number = Error_FileNotFound Then
WScript.Echo "The tunnel port range specified could not be found."
WScript.Quit
Else
WScript.Echo "Removing the tunnel port range specified ..."
End If
On Error GoTo 0
' Save the changes to the collection of tunnel port ranges
' with fResetRequiredServices set to True to restart the Firewall service.
tpRanges.Save True
WScript.Echo "Done!"
End Sub
Sub Usage()
WScript.Echo "Usage:" & VbCrLf _
& " " & WScript.ScriptName & " RangeName" & VbCrLf _
& "" & VbCrLf _
& " RangeName - Name of the tunnel port range to be deleted"
WScript.Quit
End Sub
Additional ISA Server 2004 documents are available on the ISA Server 2004 Guidance page (https://www.microsoft.com).