Fine-grained tunneling restrictions

'Tunneling' or 'port forwarding' refers to the ability of an SSH client (a) to have WinSSHD initiate a TCP/IP connection to another server on the SSH client's behalf (called client-to-server tunneling), or (b) to have WinSSHD accept incoming TCP/IP connections on a server's interface and port and forward those connections to the client (called server-to-client port forwarding). (You can learn more in our Short guide to SSH port forwarding.)

If your requirements are simple, WinSSHD provides two easy ways to control a user's or group's access to tunneling. In the WinSSHD settings entry for the account or group, there are fields Permit C2S port forwarding and Permit S2C port forwarding. Disable the first and the user will not be able to tell WinSSHD to initiate outbound connections. Disable the second and the user will not be able to instruct WinSSHD to listen for connections to forward to the SSH client.

Sometimes, however, such simple controls are not sufficient. For example, you may want to allow the user to use port forwarding to access a service provided by a particular machine on the server's local network; but you don't want to allow the user to use this capability to access any server on the internet, e.g. as a proxy for web browsing.

Such fine-grained control is provided by the Connect rules and Listening rules settings available in each group or account settings entry. This section will attempt to explain how these settings work, with two examples following at the end.

Connect rules

Connect rules control what destinations the SSH client will be able to connect to using client-2-server port forwarding. There are two types of connect rules: 'IP rules' and 'DNS name rules'. IP rules control permitted destinations based on their IP address, and DNS name rules control them based on their DNS name.

An IP rule allows you to specify either a complete IP address (significant bits = 32) or a whole subnet (significant bits = 8 for 255.0.0.0, 16 for 255.255.0.0 or 24 for 255.255.255.0). The IP address 0.0.0.0 with significant bits = 0 will match any destination.

A DNS name rule allows you to specify a destination either using a specific DNS name or a wildcard of the form *.com, *.bitvise.com or *.research.bitvise.com. A lone wildcard (just *) will match any destination.

IP rules and DNS name rules are automatically sorted by WinSSHD in order of decreasing specificity: the most specific rules are processed first and the more general ones later. The most specific rule match takes precedence.

Connect rules are always processed IP rules first, DNS name rules second. If a match is found in IP rules, the DNS name rules are not searched. This means that if there's a blanket 0.0.0.0 rule in IP rules, the DNS names will never be searched because the blanket IP rule will match all destinations.

If WinSSHD gets a client-to-server tunneling request for which there is no match in the account's Connect rules, or if there are no Connect rules or no account settings entry in the first place, the Connect rules of the account's group settings entry will be processed. If no match is found in the group Connect rules either, the connection is rejected.

By default, the Connect rule list for a group contains a single entry allowing access to all destinations if 'Permit C2S port forwarding' for the user is true. An account's Connect rule list is empty by default, passing all decisions to Connect rules defined for the user's group.

Listen rules

Listen rules control what server interfaces and ports the user will be able to bind in order to accept connections and forward them to the SSH client. Since interfaces are always specified by their IP, there is need for only one rule list.

A listen rule identifies an IP of one of the server's network interfaces and a port range for which the SSH client is allowed or denied listening. The special IP 0.0.0.0 matches any interface.

A listen rule may contain additional Accept rules which control the origin hosts from which connections to the interface and port range defined in the listen rule will be accepted. By default, the accept rule list contains a single entry allowing connections from all sources.

If WinSSHD gets a server-to-client tunneling request for which there is no match in the account's Listen rules, or if there are no Listen rules or no account settings entry in the first place, the Listen rules of the account's group settings entry will be processed. If no match is found in the group Listen rules either, the tunneling attempt is rejected.

By default, the Listen rule list for a group contains a single entry allowing all interfaces and ports to be bound if 'Permit S2C port forwarding' for the user is true. An account's Listen rule list is empty by default, passing all decisions to Listen rules defined for the user's group.

Example 1: Permit a client-to-server destination

Suppose your WinSSHD resides on machine 10.10.10.5 in your internal network, and you wish to allow the user to connect through WinSSHD to a Remote Desktop service running on machine 10.10.10.16. You would first need to decide whether to configure this policy for the user's group or for the individual user. If for the individual user, you would need to add a WinSSHD account settings entry for the user if one does not yet exist. Then, you would open the group or account settings entry that you wish to configure this restriction for, and perform the following:

1. Add 'allow' rule for client-2-server connections:
   1. open the 'Connect rules: IP rules' list and click Add
   2. under IP rule, input the IP address of the server to which the user is allowed to connect - in our example, 10.10.10.16
   3. under Significant bits, enter 32 to specify that the IP address in this case identifies an individual IP (10.10.10.16), not a subnet (e.g. 24 for 10.10.10.x)
   4. under Port range rule, set 'Port from' to the RDP port (3389), and 'Port to' to the same value
   5. under Instructions, enable the 'Allow connect' setting and leave the rest at defaults
   6. click OK to confirm and add the configured rule
2. Add 'deny' rule for client-2-server connections:
   1. click Add in 'Connect rules: IP rules'
   2. the default will be a rule that denies all connections. Just click OK to add the rule.

In this example, if you wanted to prohibit the user from setting up any kind of server-to-client forwardings whatsoever, you would simply set 'Permit S2C port forwarding' to false. Otherwise, if you wanted to configure a specific range of ports and interfaces where the SSH client may instruct WinSSHD to listen, you would add appropriate Listen rules as in the Example 2 (below).

Example 2: Permit a server-to-client binding

Suppose your WinSSHD server machine has two network interfaces: 10.10.10.5 is the private IP address in the local area network and 123.23.12.111 is the server's public IP address on the internet. You know that the user who will be logging into WinSSHD will need to run a program on the server side which will initiate a TCP connection to the client, and the user will achieve this using server-to-client port forwarding. You want to allow the user to forward connections from the server's local network through the server's 10.10.10.5 private network interface, as well as from the server itself using the 127.0.0.1 loopback interface, but you do not wish to allow the user to listen for connections from the internet through interface 123.23.12.111. You also want to restrict the user to listening on ports 1024-65535.

Again, you would first need to decide whether to configure this policy for the user's group or for the individual user. If for the individual user, you would need to add a WinSSHD account settings entry for the user if one does not yet exist. Then, you would open the group or account settings entry that you wish to configure this restriction for, and perform the following:

1. Add 'allow' listening rule for 10.10.10.5:
   1. open 'Listening rules' list and click Add
   2. under IP rule, input the IP address of the interface - in our example, 10.10.10.5
   3. under Port range rule, enter 1024 into 'Port from' and 65535 into 'Port to'
   4. enable the 'Allow listening' checkbox
   5. under Instructions, enable the 'Allow connect' setting and leave the rest at default values
   6. click OK to confirm and add the configured rule
2. Add 'allow' listening rule for 127.0.0.1:
   1. repeat steps under 1, but using 127.0.0.1 instead of 10.10.10.5. You should now have 2 listening rules.
3. Add 'deny' rule for other listening interfaces:
   1. click Add in 'Listening rules'
   2. the default will be a rule that denies binding on all listening interfaces and all ports. Just click OK to add the rule.

In this example, if you wanted to prohibit the user from setting up any kind of client-to-server forwardings whatsoever, you would simply set 'Permit C2S port forwarding' to false. Otherwise, if you wanted to configure a specific range of destination servers and their ports to which the SSH client may connect, you would add appropriate Connect rules as in Example 1 (above).