Hercules CTCI-W32

"What's New"

(i.e. "Release Notes")

CTCI-W32   3.2.1

March 1, 2007

CTCI-W32   3.2.0

late February, 2007

CTCI-W32   3.1.7

October, 2006

CTCI-W32   3.1.6

August, 2006

CTCI-W32   3.1.2

May, 2006

CTCI-W32   3.1.0

April, 2006

  1. Support for WinPCap version 3.1

    The previous version of CTCI-W32 contains a serious flaw in its initialization logic that causes it to enter into a "soft deadlock" situation when used with WinPCap version 3.1 or greater. Symptoms include tt32info and tt32test (i.e. 'test.exe') hanging for several seconds and then exiting without actually doing anything (i.e. without actually ever starting up at all), as well as CTCI-W32 not functioning properly (if at all) when used with Hercules.

    The technical details of the flaw (as well as how it was accidentally introduced) are largely unimportant (except perhaps to Windows programmer geeks) compared with the importance that it has now been identified and fixed.

    This new version of CTCI-W32 should now work properly with WinPCap 3.1 and, more than likely, all future versions of WinPCap as well (until such time as they make a major change requiring me to add additional support for it, that is).

    Thus, if you wish to take advantage of WinPCap's latest capabilities (whatever they may be) you must use this new 3.1 version of CTCI-W32 and not any of the older ones.

  2. New "ex" versions of all functions have been defined

    to work around an as-yet unidentified/unresolved bug involving TunTap32.dll's inability to directly set the caller's 'errno' variable. These functions are identical to all of the existing functions except that there is a new pointer variable argument passed as the last argument. To use any of these new functions, the caller should pass in this new last argument the address of an integer variable which TunTap32.dll then sets to the proper 'errno' value that the caller should then set its own errno variable to upon return. (i.e. the easiest way would be to point it directly to your module's (executable's/dll's) errno var so TunTap32 ends up directly setting it [to its proper value])

  3. TunTap open no longer ignores the 'flags' parameter.

    One of either O_RDONLY, O_WRONLY or O_RDWR must be specified. Specifying any other flags causes an error. (impacted tuntap32 calls: tuntap32_open, tuntap32_open_ip_tuntap) The flag is honored too. If the interface is opened O_RDONLY then any writes will cause an error and vice versa. (impacted tuntap32 calls: tuntap32_read, tuntap32_write, tuntap32_read_ip_tap, tuntap32_write_ip_tun)

  4. Semantics of Get/SetDeviceBufferSize & Get/SetIOBufferSize changed.

    Both are now specified in bytes. (Previously, the 'Get' functions returned the value in 'K'. They now both return the value in bytes, the same format that is passed to the 'Set' function). (impacted ioctl codes: TT32GDEVBUFF, and TT32GIOBUFF):

  5. Semantics of Get/SetReadTimeout changed for the same/similar reason.

    Since the timeout value is specified in milliseconds, it is thus returned the same way: in milliseconds. (impacted ioctl codes: TT32GTIMEOUT)

  6. SetIFaceFlags does not allow IFF_RUNNING to be set period.

    IFF_RUNNING means the interface is physically operational and is set internally by TunTap32 whenever the interface is succesfully initialized. If IFF_RUNNING is specified, it is silently ignored without error. (impacted ioctl codes: SIOCSIFFLAGS)

  7. SetIFaceFlags does not allow IFF_UP unless IFF_RUNNING is already set.

    IFF_RUNNING means interface is physically operational. If it is not set, then the interface cannot be enabled (IFF_UP) because it isn't operational. If IFF_UP is specified but IFF_RUNNING is not set, then an EACCES error is returned. (impacted ioctl codes: SIOCSIFFLAGS)

  8. SetIFaceFlags does not allow IFF_UP until SetTunTapFlags (ioctl TUNSETIFF) is first called

    to define the interface type to either IFF_TUN or IFF_TAP. (impacted ioctl codes: SIOCSIFFLAGS)

  9. Changed semantics of SetIFaceFlags API.

    Previously the flags passed to SetIFaceFlags would be combined (ORed) with existing (previously set) flags. Now whatever flags you pass are used to completely replace existing flag settings (i.e. subsequent calls override previous calls). This means that if you call SetIFaceFlags multiple times, only the flags set in the very last call are actually used. (impacted ioctl codes: SIOCSIFFLAGS)

  10. Calling SetIFaceFlags with 'IFF_DEBUG' now enables internal packet tracing

    WARNING! The output is very verbose! Every read/written packet is traced. (impacted ioctl codes: SIOCSIFFLAGS)

  11. Setting an interface's IP address (CTunTap::SetHercVirtIPAddr) causes the virtual interface's MAC address to be changed appropriately as well

    (to reflect the new IP address since the default virtual interface MAC address is based on its IP address). This automatic updating of the interface's MAC address only occurs if the default MAC address hasn't already been manually changed to some other value via a prior call to SetHercVirtMACAddr (tuntap32_ioctl(SIOCSIFHWADDR)). If a prior call was made to manually set the MAC to some other value then that value is honored and the MAC address is then not automatically changed. (impacted ioctl codes: SIOCSIFDSTADDR)

  12. The IFace (host physical adapter or 'destination address') used by the constructed virtual interface / adapter is defined at 'open' time and cannot be changed.

    ioctl(SIOCSIFADDR) cannot be used to "switch" to using a different IFace (host physical adapter) once an interface has been 'open'ed. Attempts to do so will be ignored and result in an error if the ip address specified in the call is not zero (meaning "don't care") and different from the one currently being used.

    That is to say, calls which specify either zero as the ip address, or which specify the same ip address as would be returned by a SIOCGIFADDR ioctl call, will continue to succeed as normal (since the iface (host physical adapter) is not actually being changed). Specifying any other non-zero ip address different from the one used in the 'open' call however, will be rejected and result in an error.

  13. Setting MTU (SetIFaceMTU) now actually does something

    It defines the size of your write buffer (i.e. the maximum number of bytes that you can write to the adapter). (impacted ioctl codes: SIOCSIFMTU; impacted tuntap32 calls: tuntap32_write, tuntap32_write_ip_tun)

  14. CTunTap::SetIOBufferSize ("define dll i/o buffer size") may not be strictly honored.

    The buffer size will be automatically reallocated larger (if possible) whenever needed. If automatic reallocation fails however, then a warning is issued and the packets that wouldn't fit into the smaller buffer are discarded. (impacted calls: ioctl(TT32SIOBUFF) and tuntap32_read)

  15. Read/Write now returns EACCES error if the interface not enabled (IFF_UP).

    You must manually call SetIFaceFlags with IFF_UP to enable the interface (i.e. "bring it up" or "enable it"). (impacted tuntap32 calls: tuntap32_read, tuntap32_write, tuntap32_read_ip_tap, tuntap32_write_ip_tun, and, indirectly, tuntap32_ioctl code: SIOCSIFFLAGS)

  16. CTunTap::Write has been greatly enhanced to make every best effort to determine the proper MAC address to use

    in the Ethernet header that it automatically builds for TUN interfaces. It now scans internal objects for all known real/virtual MAC addresses, queries Windows via GetBestInterface, etc, including actually sending an ARP packet out on the wire via the the Windows 'SendARP' API.

    Only when all such attempts fail does it then fall back to using the prior logic of relying on on Windows' "IP Forwarding" feature to route the packet. (impacted tuntap32 calls: tuntap32_write, tuntap32_write_ip_tun)

  17. CTunTap32App::IOCtl now actually returns an accurate return code

    Previously it wasn't even checking to see whether its TunTap calls were successful or not. Oops! (impacted tuntap32 calls: tuntap32_ioctl)

  18. (** RESCINDED in v3.1.7 **)   CTunTap32App::IOCtl added support for SIOCADDRT & SIOCDELRT ioctl codes

    (** RESCINDED in v3.1.7 **)   which allow one to directly manipulate Window's routing tables. (impacted tuntap32 calls: tuntap32_ioctl)

  19. CTunTap32App::IOCtl added support for SIOCxARP & SIOCxRARP ioctl codes

    to allow one to directly manipulate Window's ARP tables. (impacted tuntap32 calls: tuntap32_ioctl)

  20. The 'dwGatewayIPAddrMask' field in the "ADAPTER_INFO_LIST_ENTRY" structure defined in FishPackAPI.h

    is deprecated since it never contained any useful information anyway (its value was always zero). Additionally, the structure was extended to include some new fields pertaining to checksum offloading (see next item below), a new flag indicating whether a networking cable is actually plugged into the adapter or not, and, for WinNT variant operating systems only, the IP Helper "adapter index" value.

  21. TunTap32.DLL should now be fully "Task Offloading Compatible"

    meaning you may now freely enable whatever Task Offloading capabilities your adapter may happen to support (including Checksum Offloading, since TunTap32 has now been coded to both detect and compensate for it).

    Due to the current lack of Checksum Offloading support in WinPCap however, Checksum Offloading will never actually be used (even if your adapter happens to support it) in the following two situations:

    1. For packets sent by your virtual guest,
    2. For packets received by your virtual guest when sent directly from your Windows host to your virtual guest.

    That is to say, normally packets sent by other systems to your guest can have the verification of their checksums offloaded to the host's adapter that receives them (since they obviously have to pass through it and are thus able to take advantage of your adapter's 'Receive' Task Offloading capabailities), but in the case of your host sending packets to your guest, Checksum Offloading cannot occur since such packets never actually pass through the physical hardware (adapter) and are instead intercepted by WinPCap and passed directly to TunTap32 for delivery to your virtual guest.

    Thus, regardless of whether or not your adapter happens to support 'Receive' Checksum Offloading, all packets sent from your Windows host to your virtual guest will never be able to taker advantage of the Checksum Offloading capabilities of your adapter (even though from your virtual guest's point of view the packets are indeed being received and not sent).

    Furthermore, due to the very nature of the way Task Offloading is designed and implemented at the Windows device-driver level, all such packets (sent from your Windows host to your virtual guest) will incur a slight (but hopefully not noticible) performance penalty as a result of TunTap32 having to manually re-calculate the checksums for all such packets (since your Windows host never did so since it was naively expecting the hardware to do it).

    All packets sent to your virtual guest from other systems however (i.e. external to your Windows host, such as from other workstations on your local LAN or from the Internet) should not incur such a penalty however, since they should already have proper checksum values (by virtue of the fact that they were never sent from your host's but rather only received by it).

    (Clear as mud, right? <g>)

  22. TT32Test itself has been significantly enhanced / modified,

    and now supports testing on two different TunTap32 interfaces at the same time (the first one is a TUN interface by default (like before) and the second one is (by default) a TAP interface), thereby allowing testing of both TunTap32's TUN logic as well as its TAP logic at the same time (as well as how well it behaves when combinations of both are used at the same time).

    Detailed (very verbose) debug tracing messages are also provided to both verify and debug proper TunTap32 functioning, as well as it now displays, for each adapter, whether or not checksum offloading is enabled (although due to the previously mentioned change that shouldn't be an issue anymore).

  23. TT32Test's main window is now a CEditView type

    that displays all trace/testing messages while testing is active (so you can see what's going on) and now no longer asks for an o/p file filename until the application is closed (at which point you can then specify the filename of what file you wish to save the test messages in, if so desired).

    Also, because the view is now an edit view, you can now copy the test messages directly from the main window for pasting, if needed, into some other program or document (such as an email asking for help for example).

  24. TT32Test now automatically adds a PTP (point-to-point) route entry into Windows' routing table

    for each TUN and TAP interface that it creates, just like Hercules does. The entries are of course automatically removed whenever the interfaces are closed.

  25. The "IP Forwarding" option should now no longer be needed if you network already has a router

    that is responsible for routing traffic through your LAN. If your LAN does not have a router however, then you will still need it of course (so that your virtual guest's packets can be routed properly through your network).

    Additionally, it should it mentioned that if you are using a real router to route traffic on your LAN, then, technically, you should not ever enable 'IP Forwarding' on your Windows host. If you do, double packets will result as a consequence of both your router and Windows both attempting to route traffic to your virtual guest. (Note that due to the way networking is designed to operate however, such duplicate packets should not actually cause any problems other than the obvious slight degradation that would result due to the extra redundant packets flowing through it thereby needlessly consuming available bandwidth).

  26. UNICODE support: the groundwork is being laid for possible future support for languages other than English.

    As a result, CTCI-W32 now ships in two flavors: normal and UNICODE. At the moment both are logically identical to one another however (and thus should behave identically too), so it currently does not matter which one you use. In the future however, the UNICODE versions may (should I decide to do it) be customized for different languages and thus be different. (For now though they're the same)

  27. All version numbers have been brought into sync with one another

    since they are all always packaged together as one "product" anyway. In the future, whenever a new release of an individual component is needed, all components will be released together with a uniform updated new version number (in order to make it easier to determine whether or not you have the most current version of each component installed or not).

  28. The "preferred base address" of all DLLs (TunTap32.dll and FishPack.dll)

    have been changed to 0x400000 (4MB) in order to maximize available virtual address space.

    Previously they were using the Windows default (which is currently 0x10000000 (256MB)), thereby causing valuable potential address space to be wasted due to fragmentation. Using a preferred base of 4MB however, potentially frees up an additional 230MB+ of valuable virtual address space, thereby allowing more memory to be used by your applications rather than having it wasted due to memory fragmentation. (Refer to the new "Maximizing Hercules Available Memory" web page for more information on rebasing Windows DLLs to increase available memory.)

  29. The CTCI-W32 package now contains a built-in dependency on a completely unrelated DLL

    unoriginally called 'FishLib.dll'. The FishLib DLL is simply a collection of routines and functions common to most of the programs I write and splitting that common functionality out into a separate maintainable module makes it easier for me to maintain all of my products without having to duplicate my efforts.

TunTap32   2.1.0 build 404

(approximate release date: Sept 11, 2005)

FishPack,     TunTap32

(approximate release date: July 14, 2003)


(approximate release date: November 19, 2002)

FishPack,     TunTap32,     tt32info

(approximate release date: October 29, 2002)

FishPack,     TunTap32,     tt32info

(approximate release date: May 4, 2002)

FishPack,     TunTap32,     tt32info

  "Fish"  (David B. Trout)

"Programming today is a race between
software engineers striving to build bigger
and better idiot-proof programs, and the
Universe trying to produce bigger and better
idiots. So far, the Universe is winning."

- Rich Cook