Managing Tunnel Port Ranges

  • Article

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

Displaying the Existing Tunnel Port Ranges

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

  1. 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.

  2. Declare an FPCArray object, an FPCTunnelPortRanges collection, and an FPCTunnelPortRange object.

  3. Get references to the FPCArray object and the FPCTunnelPortRanges collection.

  4. 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.

Script Listing: ShowTPRanges.vbs

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

' 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

Creating a New Tunnel Port Range

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

  1. 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.

  2. Declare an FPCArray object, an FPCTunnelPortRanges collection, an FPCTunnelPortRange object, and an Integer.

  3. Get references to the FPCArray object and the FPCTunnelPortRanges collection.

  4. Call the AddRange method on the collection with the parameters supplied by the user to create the new tunnel port range.

  5. 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.

Script Listing: AddTPRange.vbs

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

' 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

Deleting a Tunnel Port Range

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

  1. 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.

  2. Declare an FPCArray object and an FPCTunnelPortRanges collection.

  3. Get references to the FPCArray object and the FPCTunnelPortRanges collection.

  4. Call the Remove method on the collection with the parameter supplied by the user to delete the tunnel port range.

  5. 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.

Script Listing: DelTPRange.vbs

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

' 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 Information

Additional ISA Server 2004 documents are available on the ISA Server 2004 Guidance page (https://www.microsoft.com).