Windows Core Networking : Winsock

Winsock SO_EXCLUSIVEADDRUSE on Vista

wndpteam — Tue, 20 Mar 2007 00:12:00 GMT

I've been asked a couple times about the socket option SO_EXCLUSIVEADDRUSE on Vista and especially how it relates to dual stack sockets. The following doc link describes the basic idea of this socket option:

http://msdn2.microsoft.com/en-us/library/ms740621.aspx

However, it hasn't been updated with any Vista specific behavior. We're working on updating that doc but it takes a while for the change to propagate to the web.

Vista follows the same rules as Windows Server 2003 when looking at that documentation, but what happens when using a dual stack socket? A dual stack socket is one that is created as IPv6 but then the IPV6_V6ONLY socket option is set to false. This results in the socket being bound to the same port on both the IPv4 and IPv6 stack. This mans that the security check is performed for the given port on both the IPv4 and IPv6 networking stacks. If either check fails, the entire bind request fails.

For example, a IPv6 dual stack socket is to be bound to port 5150 on the wildcard address (since it doesn't make sense to bind a dual stack socket to a specfic IP address). If SO_EXCLUSIVEADDRUSE is not set, then the bind will succeed even if there is another socket (IPv4 or IPv6) bound to a specific IP address on port 5150. This is no different what is described in the article above. However, if SO_EXCLUSIVEADDRUSE was set then if any other socket is bound to port 5150 (either IPv4 or IPv6), the bind call will fail thus indicating that you don't have exclusive access to that port.

Just as a reminder, applications should never set SO_REUSEADDR except for some very specific uses (e.g. multicasting) while servers should always set SO_EXCLUSIVEADDRUSE.

--Anthony Jones (AJones)

Winsock Header Weirdness

wndpteam — Tue, 19 Dec 2006 02:35:00 GMT

There are two main Winsock headers used depending on which version your application needs. There is winsock.h for Winsock v1.x and winsock2.h for Winsock v2.x and they are mutually exclusive. That is, if you include both header files you will see a lot of compilation errors.

As you may know, windows.h includes a lot of other header files if you don't define WIN32_LEAN_AND_MEAN in your source code. One of the headers it does include without this define is winsock.h. This can cause problems if you are intending to use Winsock 2 features and are linking to ws2_32.lib. In addition to causing obvious compilation errors (due to structure redefinitions or missing definitions) there is a subtle issue regarding IP multicast support. Winsock 1 defined the IP multicast socket options IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP as 5 and 6; however, when Winsock 2 was defined these values changed to 12 and 13. By including winsock.h and linking to wsock32.lib, these values are fixed up since the Windows operating system will only recognize the Winsock 2 values. By mismatching the header file and link library, the application would see failures when calling setsockopt.

Winsock developers should define WIN32_LEAN_AND_MEAN and explicitly include the Winsock header for the version they require as well as link with the appropriate lib -- winsock.h goes with wsock32.lib while winsock2.h goes with ws2_32.lib.

Our Mike Flasko and Anthony Jones on Channel 9

wndpteam — Wed, 13 Dec 2006 18:46:00 GMT

There is a new video up on channel9 talking about Coding to support IPv6. Go check it out!

-- Ari Pernick

LSP Installation Problems with WSCInstallProvider64_32

wndpteam — Wed, 29 Nov 2006 00:51:00 GMT

An LSP (or Winsock provider) can be installed into the Winsock catalog through several different function calls. Also, as you might know, on 64-bit Windows there are two different Winsock catalogs – one for 32-bit applications and one for 64-bit native applications. In order for an LSP to be loaded by both native and WOW64 applications, it must be installed into both catalogs. There are two ways to install a Winsock provider into both catalogs:

1. Call WSCInstallProvider64_32 which installs the same provider entries into both Winsock catalogs

2. On Vista, call WSCInstallProviderAndChains which performs all the necessary steps but results in separate install calls to the 64-bit and 32-bit catalogs

Each of these functions will install the provider information into the appropriate Winsock catalog. The Winsock catalog is a repository in the registry that contains information about each Winsock provider. For 64-bit Windows, there are two versions of the catalog – one for native 64-bit applications and one for 32-bit applications.

Unfortunately WSCInstallProvider64_32 works in only a handful of cases. The basic problem with this function is it attempts to install the same WSAPROTOCOL_INFOW structures into both Winsock catalogs. This means that the protocol chains specified in the WSAPROTOCOL_INFOW structure will contain the same catalog IDs for both the 32-bit and 64-bit Winsock catalogs. However, if a Winsock provider was installed either into one but not both catalogs or if the Winsock provider was installed into both catalogs using methods #2 then the catalog IDs in each of the two Winsock catalogs become out of sync.

For example, one way the catalog can become out of sync is if an LSP is installed only into the 64-bit catalog. That is, the application installs an LSP provider which will be assigned the next free catalog entry ID – say 1020. Then another LSP is installed using WSCInstallProvider64_32. This LSP installer builds a protocol chain and layers its entries over the first LSP that has the ID of 1020. Since WSCInstallProvider64_32 installs the same WSAPROTOCOL_INFOW into both catalogs, the 32-bit Winsock catalog now contains an entry that references provider 1020 which does not exist in the 32-bit catalog. This would result in the loss of network connectivity for 32-bit applications.

For Windows Vista, if WSCInstallProvider64_32 is called and the 32-bit and 64-bit Winsock catalogs are not in sync, then the call will fail with WSANO_RECOVERY.

Because of this it is recommended that LSPs move to the WSCInstallProviderAndChains function on Vista which takes this issue into account (as well as saves you from writing and maintaining the ~600 lines of code to perform all the install steps). Of course, for downlevel Windows OSes, WSCInstallProvider64_32 is the only method for installing an LSP entry into both catalogs. The current LSP SDK sample dynamically checks if WSCInstallProviderAndChains is available and uses that; otherwise, it falls back to using WSCInstallProvider64_32. The latest sample is available from http://connect.microsoft.com/wndp.

--Anthony Jones (AJones)

WSAPoll, A new Winsock API to simplify porting poll() applications to Winsock.

wndpteam — Thu, 26 Oct 2006 18:49:00 GMT

Hello, my name is Chad Carlin. I'm a software developer on the Winsock Test Team. Among the many improvements to the Winsock API shipping in Vista is the new WSAPoll function. Its primary purpose is to simplify the porting of a sockets application that currently uses poll() by providing an identical facility in Winsock for managing groups of sockets. Depending on the needs of your application, this addition could be an attractive option.

If you are new to poll, (since just about everyone is new to WSAPoll() ), I'll explain its role in network programming with a brief example. Suppose that you have a server application that is providing a service to several clients concurrently. You would not want your process to be blocked while waiting for a client to send or be able to receive data. You could create a thread per socket, but that would hinder the scalability of your application. By creating an array of structures, each with a member, which is a pointer to one of your sockets, you can poll this array to identify which sockets are guaranteed to be available for reading or writing data. This keeps your server process busy servicing ready clients or other performing useful work.

You should be aware that if you are choosing between using select() and WSAPoll(), that WSAPoll() scales better to a larger number of sockets and can accommodate sockets of different types. If you are creating a large-scale, high-performance Winsock2 application, we recommend that you use the native Winsock overlapped IO facilities.

If you have experience developing applications using poll(), WSAPoll will be very familiar. It is designed to behave just like poll(). In fact, I recently ported the Winsock WSAPoll SDK sample to run on BSD Unix. I know that sounds backwards from what you would expect but, we all like sample code after all. As it turns out it didn't matter which direction I ported. I had really hoped to have some clever insight to give you, or some real handy tip about how to work around some special difference. The truth is, the portions of the code dealing with poll() were unchanged from the sample. Except, of course, for changing the name of the API. Frankly, porting the poll() code went so smoothly, it made converting Windows threads to pthreads seem like the lion's share of the work.

To speed up your porting effort here are some tips:

The minimum set of include files that you'll need are: Winsock2.h, ws2tcpip.h and mstcpip.h. You'll want to switch from using the errno global variable to using the WSAGetLastError() function when looking for extended error codes.

For simplicity, the SDK sample uses macros to fill in the IPv6 address structures to connect or bind to the loopback interface. You should use getaddrinfo() which is the preferred method when writing an IP agnostic application. To support both address types you'll want to switch to using SOCKADDR_STORAGE types instead of sockaddr types used in BSD.

Here is an example of calling WSAPoll on a socket to check if it is writable. If the remote endpoint has accepted the connection, we call send. Get the full sample from the SDK for additional details.

//Call poll for writeability on connecting socket
fdarray.fd = csock;
fdarray.events = POLLWRNORM;
if (SOCKET_ERROR == (ret = WSAPoll(&fdarray, 1, DEFAULT_WAIT )))
{
    ERR("poll");
}     
if (ret)
{
    if (fdarray.revents & POLLWRNORM)
    {
        printf("Established connection and signalled POLLWRNORM \n");            
        //Send data
        if (SOCKET_ERROR == (ret = send(csock, TST_MSG, sizeof (TST_MSG),)))
        {
            ERR("send");
        } else {
            printf("Sent %d bytes@ %d\n",ret, __LINE__);
        }
    }
...

Listing of networking code samples in the Windows SDK:
http://windowssdk.msdn.microsoft.com/en-us/library/ms716684.aspx

Find the latest version of the Platform SDK which includes the sample mentioned above:
http://msdn.microsoft.com/downloads/

MSDN WSAPoll documentation page:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winsock/winsock/wsapoll.asp

--Chad Carlin

Creating IP Agnostic Applications - Part 2 (Dual Mode Sockets)

wndpteam — Tue, 24 Oct 2006 20:59:00 GMT

In a previous post I wrote about how on Windows Vista and Windows Server "Longhorn," IPv6 is installed and enabled by default and that when both IPv4 and IPv6 are enabled, the TCP/IP stack prefers to use IPv6 over IPv4. With the growth of IPv6, applications must now work seamlessly over both protocols (IPv4 & IPv6). The remainder of this post discusses one way to make handling both protocols easier by using a single socket that works with IPv4 & IPv6. No longer do you need to create two sockets to make your application IPv4 & IPv6 aware :).

Windows Vista and Windows Server Longhorn includes a new TCP/IP stack which includes common TCP & UDP layers on top of the IPv4 and IPv6 layers. This new architecture has made it possible for a single IPv6 socket to work with both IPv6 and IPv4. For example, using a single IPv6 socket one can now accept BOTH IPv4 and IPv6 traffic. Such a socket is typically dubbed a "dual mode" socket. Dual mode sockets are usable by managed code sockets (ie. System.Net.Sockets.Socket), native Winsock sockets as well as Winsock Kernel (WSK) sockets.

To create a "dual mode" socket, the following steps are needed:

Create an IPv6 socket
Set the IPV6_V6ONLY socket option to false

Once you have created the socket and set the appropriate option, the socket can be used to accept incoming IPv4/v6 connections or connect to an IPv4/v6 destination. The snippets below outline accepting incoming connections over both protocols in native and managed code:

Note: The code is meant as demonstration code; error code checking and exception handling have been left off the code snippets to keep them as concise as possible.

.NET (C#)

Socket sock = new Socket(AddressFamily.InterNetworkV6, SocketType.Stream, ProtocolType.Tcp);
// 27 is equivalent to IPV6_V6ONLY socket option in the winsock snippet below
sock.SetSocketOption(SocketOptionLevel.IPv6, (SocketOptionName)27, 0);
sock.Bind(new IPEndPoint(IPAddress.IPv6Any, 8000));
sock.Listen(5);
Socket client = sock.Accept();
// send / receive data on 'client' socket

Winsock

WSADATA wsaData;
SOCKET lsock = INVALID_SOCKET;
SOCKET csock = INVALID_SOCKET;
SOCKADDR_STORAGE serverAddr = {0};
SOCKADDR_STORAGE clientAddr = {0};
int off = 0;
int port = 8000;
int clientAddrLen = sizeof(clientAddr);
WSAStartup(MAKEWORD(2,2), &wsaData); 
serverAddr.ss_family = AF_INET6;
INETADDR_SETANY((SOCKADDR *)&serverAddr);
SS_PORT(&serverAddr) = htons(port);
lsock = socket(AF_INET6, SOCK_STREAM, IPPROTO_TCP)

//make the socket a dual mode socket
setsockopt(lsock,IPPROTO_IPV6,IPV6_V6ONLY,(char *)&off, sizeof(off));
bind(lsock, (SOCKADDR *)&serverAddr, (int)INET_SOCKADDR_LENGTH(serverAddr.ss_family));
listen(lsock, 5);
csock = accept(lsock, (SOCKADDR *)&clientAddr, &clientAddrLen); 
... 
... 
WSACleanup();

When using a dual mode socket, it is important to remember the socket is at root an IPv6 socket. Since this is the case, when specifying an IPv4 address to such a socket (ie. connect to IPv4 endpoint using a dual mode socket) one must format the IPv4 address as an IPv4 mapped address prior to passing the address to a socket function. Fortunately, one can use IN6ADDR_SETV4MAPPED(...), defined in mstcpip.h to simplify this task.

The following shows an example of what this looks like in Winsock:

WSADATA wsaData;
SOCKET csock = INVALID_SOCKET;
SOCKADDR_STORAGE addrLoopback4 = {0}; 
int port = 8000;
int off = 0; 
addrLoopback4.ss_family = AF_INET;
INETADDR_SETLOOPBACK((SOCKADDR*)&addrLoopback4);
SS_PORT(&addrLoopback4) = htons(port); 
WSAStartup(MAKEWORD(2,2), &wsaData);
if((csock = socket(AF_INET6, SOCK_STREAM, IPPROTO_TCP)) == INVALID_SOCKET)
{
     //error creating the listening socket
     WSACleanup();
     return 1;
} 
//make the socket a dual mode socket
setsockopt(csock,IPPROTO_IPV6,IPV6_V6ONLY,(char *)&off, sizeof(off)); 
// format the address as a v4 mapped address if needed
ConvertToV4MappedAddressIfNeeded((SOCKADDR *) &addrLoopback4);
// connect
connect(csock, (SOCKADDR *)&addrLoopback4, sizeof(addrLoopback4)); 
printf("Connect complete"); 
closesocket(csock); 
WSACleanup();
return 0; 
  


void ConvertToV4MappedAddressIfNeeded(PSOCKADDR pAddr)
{
    // if v4 address, convert to v4 mapped v6 address
    if (AF_INET == pAddr->sa_family)
    {
        IN_ADDR In4addr;    
        SCOPE_ID scope = INETADDR_SCOPE_ID(pAddr);
        USHORT port = INETADDR_PORT(pAddr);
        In4addr = *(IN_ADDR*)INETADDR_ADDRESS(pAddr);
        ZeroMemory(pAddr, sizeof(SOCKADDR_STORAGE));
        IN6ADDR_SETV4MAPPED(
             (PSOCKADDR_IN6)pAddr,
             &In4addr,
             scope,
             port
             ); 
    }
}

Cheers,

-- Mike Flasko

Debugging Winsock LSPs

wndpteam — Thu, 05 Oct 2006 21:47:00 GMT

Several people have asked for tips on debugging LSPs, and unfortunately there’s no easy method to do so. One difficulty with LSPs is that once it’s installed any number of processes can immediately load the faulty LSP and begin to behave badly. This usually isn’t fatal unless one of those processes happens to be WINLOGON.EXE, LSASS.EXE, or another system critical service in which case your computer will shut down.

Problems with LSPs typically manifest in one of two ways:

1. An application crash

2. The application fails in an unexpected error

The first problem is usually easier to diagnose. This is done by using a debugger to either attach to the process and dumping the relevant stack that caused the violation or by running the application under the debugger. Almost all of application crashes from LSPs are due to invalid memory access (i.e. access violation). With the debugger (either Visual Studio, WinDbg.exe, NTSD.EXE, etc.) you can view the faulting instruction and dump the memory address that your LSP was trying to access. This usually gives you enough information to trace through your code and see how and where that structure and/or variable is manipulated to track down the culprit.

However, in some instances that might not be enough. In that case the next step would be to step through your LSP code for typical socket operations that would lead up to the crash. For example, if the crash occurred in your LSP’s overlapped completion routine then setting breakpoints in your LSP’s WSPSend and OverlappedCompletionRoutine would be the first step. When those breakpoints are hit, you can then validate the LSPs internal state for each socket and that request. Setting additional breakpoints on routines that manipulate the LSP internal state may also be necessary.

Other areas of the LSP to look at when debugging access violations are:

1. Access to the LSP socket context structure from multiple threads – many apps perform simultaneous socket operations on the same socket from multiple threads. Verify the LSP correctly references and utilizes CRITICAL_SECTIONs when necessary to handle this case.

2. Validating calling parameters – the Winsock API specification states that Winsock will catch invalid memory pointers for some input parameters and return WSAEFAULT. This means any LSP must also do this validation.

3. Overlapped completion – LSPs add considerable overhead to the amount of time it takes for an overlapped operation to fully complete. Some poorly written applications use stack based WSAOVERLAPPED structures and then leave that function even though the operation is still pending. When the operation completes, the LSP ends up over writing a random stack location. This isn’t a bug in the LSP bug a bug in the application, and there’s nothing the LSP can do to prevent this. The only recourse here is to contact that application owner.

If you are experiencing a crash in a system critical process like LSASS.EXE then life is much more difficult. In this case, debugging can only be performed by piping the user mode debugger to the kernel mode debugger (kd.exe). This will stop the entire OS execution while stepping through the faulting process and will prevent the OS from rebooting underneath you. This type of debugging can only be accomplished using the Windows debugging tools found here:

http://www.microsoft.com/whdc/devtools/debugging/default.mspx

For the second type of LSP failure, unexpected application errors, the starting point is more nebulous. An example of this is installing an LSP and then having your web browser fail to load a web page you know should succeed. Since you don’t immediately know what call is unexpectedly failing, these problems require more work. Several approaches are:

1. Use a debugger to step through the expected Winsock calls if known (e.g. Internet Explorer would call socket, connect, select, send, and recv.

2. Add tracing to your LSP to log unexpected failures.

Tracing is generally a good thing to add since it’s useful and can be reused (if any other problems come up). Additionally, since you probably won’t know what the failing application is explicitly doing in terms of Winsock calls, adding tracing usually takes less time in the long run.

Some other random LSP tips:

1. Always remember to install your LSP over both TCP and UDP entries for IPv4 and IPv6. Several applications will call select and pass handles owned by multiple providers, and if your LSP doesn’t layer over that provider then there is a possibility that your LSP is completely bypassed and the owning provider will fail its WSPSelect call (as it won’t understand the LSP sockets passed to it).

2. When debugging an LSP you may install and remove your LSP multiple times. After a while you can get into a state where various processes have loaded different versions of your LSP. It’s a good idea to reboot your computer after several iterations of installing and removing your LSP.

3. Debug your LSP on a Windows Vista computer J. Winsock LSP categorization will prevent system services from loading your LSP which will prevent the flakiness mentioned in the previous point. See the following blog posting about LSP categorization: http://blogs.msdn.com/wndp/archive/2006/02/09/529031.aspx

--Anthony Jones (AJones)

Creating IP Agnostic Applications - Part 1

wndpteam — Tue, 29 Aug 2006 18:00:00 GMT

In Windows Vista and Windows Server "Longhorn," IPv6 is installed and enabled by default. When both IPv4 and IPv6 are enabled on these OSs, the TCP/IP stack prefers to use IPv6 over IPv4. For example, APIs such as ConnectByName will attempt to connect first via IPv6. See this post for a detailed discussion of address sorting.

Since the IPv6 stack has been enhanced, is installed by default and the preferred network layer, it is important when writing network code to ensure your application is IP agnostic. That is, your application should be able to function well when:

IPv4 and IPv6 are installed
IPv4 is the only network layer protocol installed
IPv6 is the only network layer protocol installed

At first glance this requirement may seem like significant added complexity for an application developer, but there is good news :). We have been actively working on ways to make writing IP agnostic applications simple. The remainder of this post will talk about how to get started making your apps IPv6 aware. In a subsequent post, I hope to drill down into specific topics.

Check Out the Porting Guide

When writing such applications, I suggest reading the Winsock IPv6 Porting Guide. This document is applicable to Windows Vista and Windows Server Longhorn as well as many prior OSs such as Windows XP and Window Server 2003. While the document speaks directly to the use of native code Winsock APIs, the concepts presented are directly applicable to both native and managed code (ie. .Net Framework). Would a version of this document targeted at managed code development be useful? Are there areas of the porting guide you would like expanded? If so, please let us know.

How to Check if IPv4 or IPv6 is Installed

One of the first tasks you may need to do is determine if IPv4 and/or IPv6 are installed on the machine. I believe there a number of suggested methods out there, but the recommended method which will reliably tell you if a protocol is installed is to attempt to create a socket for the address family in question.

For Winsock developers, this is accomplished by calling the socket or WSASocket function with the address family parameter set to AF_INET to test IPv4 availability and AF_INET6 for IPv6.

For .Net Framework applications, use the Socket.SupportsIPv4 property to test IPv4 availability and Socket.OSSupportsIPv6 for IPv6.

Note: There is a Socket.SupportsIPv6 property, but this is NOT the one you want in this case. For compat reasons we could not change the meaning of this property which does not tell you whether the machine has IPv6 installed, but instead gives back the value of a legacy configuration switch.

Previous Posts

Brad Williamson has posted already on a couple of the APIs available on Windows Vista & Windows Server "Longhorn" which simplify connection establishment for IP agnostic apps.

-Mike Flasko

WSAConnectByName() and WSAConnectByList()

wndpteam — Wed, 26 Jul 2006 01:00:00 GMT

G’Day, my name is Brad Williamson, a Software Design Engineer with the Windows Networking Developer Platform (WNDP) group here at Microsoft. I am going to talk about two APIs that were introduced in Windows Vista Beta 2 to simplify the process of connecting to another connection-oriented socket application.

By far, one of the most common scenarios in sockets programming is to connect to a remote address after resolving the hostname. To do this, you first call getaddrinfo() to resolve a hostname. Then, for each address, you create a socket, bind to that socket, and call connect(),WSAConnect(), or ConnectEx(). This process continues until the connection succeeds or the address list has been exhausted. With IPv6 becoming more prevalent, the address list that you have to traverse will be large.

Furthermore, if you have a machine with multiple interfaces (whether that be multiple NICs and/or multiple IP addresses on the same NIC), you may want to determine which interface best suits the destination address, and then bind appropriately.

As you will agree, the process of connecting optimally to a destination connection-oriented socket requires a lot of code.

With Windows Vista, this process is simplified with the introduction of two new Winsock APIs: WSAConnectByName() and WSAConnectByList().

WSAConnectByName() establishes a connection to another application, using an optimal source and destination address pair, given a specified socket, host and port. Given a socket s, host name and port (or a well known service name); WSAConnectByName() will connect to the destination. If successful, WSAConnectByName() will return the local address which socket s is bound to, and the remote address connected to.

BOOL PASCAL WSAConnectByName(
  SOCKET s,
  LPSTR nodename,
  LPSTR servicename,
  LPDWORD LocalAddressLength,
  LPSOCKADDR LocalAddress,
  LPDWORD RemoteAddressLength,
  LPSOCKADDR RemoteAddress,
  const struct timeval* timeout,
  LPWSAOVERLAPPED Reserved
);

In addition to WSAConnectByName(), we have introduced WSAConnectByList() which establishes a connection to one of the addresses specified in the SocketAddressList structure.

BOOL PASCAL WSAConnectByList(
  SOCKET s,
  PSOCKET_ADDRESS_LIST SocketAddressList,
  LPDWORD LocalAddressLength,
  LPSOCKADDR LocalAddress,
  LPDWORD RemoteAddressLength,
  LPSOCKADDR RemoteAddress,
  const struct timeval* timeout,
  LPWSAOVERLAPPED Reserved
);

By using WSAConnectByName() and WSAConnectByList():

For WSAConnectByName(), your application is transparent to the name resolution. The list of remote addresses that we attempt to connect to is determined by the socket type passed in. This also includes dual-mode sockets (supporting IPv4 and IPv6) where the socket option IPV6_V6ONLY has been set to FALSE.
Your application does not have to optimize the address list to determine which interface you should bind to.
Eliminates the need for your application to include code to minimize the time of the connecting.

Having said this, here are two caveats to using these APIs:

Connection-oriented mode is only supported, and
Overlapped I/O is not supported. These APIs will block even if the socket is in non-blocking mode. Update: We will support Overlapped I/O in a future release.

More information about these new APIs can be found in:

http://msdn.microsoft.com/library/en-us/winsock/winsock/wsaconnectbyname_2.asp

and

http://msdn.microsoft.com/library/en-us/winsock/winsock/wsaconnectbylist.asp

So, when writing your next Winsock based application using Windows Vista, be sure to try out WSAConnectByName() and WSAConnectByList(). Please let us know if you have any questions, comments or suggestions.

--Brad Williamson

The (new) Trouble with select and LSPs...

wndpteam — Thu, 13 Jul 2006 21:00:00 GMT

If you’ve ever had to deal with Winsock LSPs, then you probably know that handling select function calls are rather convoluted – especially with certain apps that pass multiple socket types into select. Some applications (like IE) will pass a UDP/IPv4 and a TCP/IPv4 socket in a single select call. This works fine unless you have a non-IFS LSP installed only over UDP/IPv4 or TCP/IPv4 (but not both) in which case IE may lose network connectivity. This is because the order of the socket handles matter. That is, Winsock will find the first socket in the first non-empty FD_SET and call the provider that owns that handle to service the select call. If the first handle is a UDP/IPv4 socket from a base provider and the second handle is the TCP/IPv4 from an LSP provider, the base provider (BSP) will attempt to lookup the LSP handle which will fail with WSAENOTSOCK. Because of this Microsoft has always recommended that non-IFS LSPs layer over all entries for a particular address family (i.e. layer over all the IPv4 entries).

With Vista, things have gotten interesting again. Many system services (like DNS) have been updated to support both IPv4 and IPv6 which means there are applications passing in a mix of IPv4 and IPv6 sockets in a single select call. So, the same problem exists now if your LSP layers only over IPv4 entries but not over IPv6 entries. To prevent Vista from breaking (e.g. DNS name resolution not working) when an IPv4 only LSP is installed, a change was made to select to bypass LSPs entirely if a non-IFS LSP is installed that is layered over just IPv4 (or only over IPv6). Note that only the LSP’s WSPSelect routine is bypassed, all other calls will still be routed to the LSP. Also, Winsock will only enter the “bypass select” mode if it detects there is an LSP installed over only one of the two required protocols (IPv4 or IPv6). If all non-IFS LSPs are installed over both IPv4 and IPv6, then those LSPs will still intercept the select call.

Most LSPs do not need to intercept select unless they are interjecting data into the application’s stream in which case they would need to inject read events to notify select based applications that data is present. For those LSPs that do need to intercept select calls, they will have to be modified to do so. The method by which an LSP’s WSPSelect is bypassed is as follows:

The ws2_32 select call translates each application socket to a base provider (BSP) handle, by calling the ioctl SIO_BSP_HANDLE_SELECT (described below) for each socket handle
Once all FD_SETs have been translated, select routes the call to the first socket handle in the first non-empty FD_SET which will be a BSP. Since all socket handles are from base providers, all handles are known to be valid
Once the BSP provider returns, the handles returned are mapped back to the application handles

For an LSP to intercept select calls, it will need to trap the WSAIoctl call and the ioctl SIO_BSP_HANDLE_SELECT in the LSP’s WSPIoctl function. This ioctl passes the application handle as the socket parameter and expects the “base” handle to be returned in the output parameter. For an LSP to successfully intercept select calls on Vista it must do the following:

The LSP must be installed either over all BSP entries or be installed over all IPv4 and IPv6 entries
The LSP must intercept the SIO_BSP_HANDLE_SELECT ioctl call and return the same socket handle value that was passed as the socket parameter (i.e. the LSP’s socket handle that it returned to the caller)

The following code snippet illustrates the basic idea:

int WSPAPI

WSPIoctl(

SOCKET s,

DWORD dwIoControlCode,

LPVOID lpvInBuffer,

DWORD cbInBuffer,

LPVOID lpvOutBuffer,

DWORD cbOutBuffer,

LPDWORD lpcbBytesReturned,

LPWSAOVERLAPPED lpOverlapped,

LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,

LPWSATHREADID lpThreadId,

LPINT lpErrno

)

{

if (SIO_BSP_HANDLE_SELECT == dwIoControlCode)

{

if (cbOutBuffer < sizeof(SOCKET))

{

*lpErrno = WSAEFAULT;

Return SOCKET_ERROR;

}

*lpvOutBuffer = s;

*lpcbBytesReturned = sizeof(s);

return NO_ERROR;

}

// … Rest of your WSPIoctl

}

Finally, its important to point out that if your LSP chooses to intercept select it does not 100% guarantee that the problem described here will not be encountered. Under certain LSP layering configurations its always possible that the first handle belongs to a BSP or an LSP positioned lower in the LSP stack such that it will be unable to translate a given higher layer LSP handle. So, unless you absolutely have to intercept select calls, don’t.

Note that this change was made after Beta 2.

--Anthony Jones (AJones)

WNDP Connect Site gets an upgrade!

wndpteam — Tue, 06 Jun 2006 19:32:00 GMT

Last year we setup a small site on connect.microsoft.com in order to let our blog readers, developers and users file bugs, make suggestions and get some conntent like whitepapers and samples early. The downside to the site was that you couldn't easily deep link and it required a Windows Live (aka Passport) login. Well the folks at connect.microsoft.com have launched a new version of connect that enables access to much of the site without a login including readonly access to the bugs filled there much like the popular MSDN Product Feedback Center.

Check it out: http://connect.microsoft.com/WNDP

-- Ari Pernick

Winsock and the new SDK Headers

wndpteam — Fri, 07 Apr 2006 23:45:00 GMT

As you may have noticed in the recent Vista CTP SDK, the Winsock headers have undergone some changes. First, instead of a couple monolithic files (winsock2.h and mswsock.h), they have been split into a number of smaller files for ease of maintenance as well as for use by other components that don't necessarily load Winsock but need to use some of its defines. For example, device drivers that need protocol and structure definitions might only include ws2def.h instead of winsock2.h which pulls in a bunch of conflicting SDK definitions (since the driver already pulls in DDK definitions).

The other major change is header versioning. Recently all the Windows header files have been versioned to only define constants, structures, and APIs if the source is explicitly compiled for a Windows OS version that supports those definitions. This allows developers to use one set of headers that can be compiled for any target Windows OS. Unfortunately, this also means if you don't define _WIN32_WINNT at all, many of the definitions are not declared at all.

The good news is the downloadable SDK does set this define according to the target OS selected when running under the SDK environment. However, Visual Studio does not set this define. Therefore if your build environment of choice is VS, you may need to set this define in your project in order to compile correctly for your targeted OS.

To target a project for Vista, _WIN32_WINNT should be set to 0x0600. For a complete list of OS target version numbers, see the following KB article:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winprog/winprog/using_the_windows_headers.asp

-Anthony Jones (AJones)

Introduction to Winsock Kernel (WSK)

wndpteam — Fri, 24 Feb 2006 20:45:00 GMT

Overview of WSK

In Windows Vista a new transport-independent kernel mode Network Programming Interface (NPI) called Winsock Kernel (WSK) has been added. Using WSK, kernel-mode software modules can perform network communication using socket-like programming semantics similar to those supported in user-mode Winsock2. While the WSK NPI supports most of the same socket programming concepts as user-mode Winsock2 like socket creation, bind, connect, accept, send and receive, it is a completely new programming interface with unique characteristics such as asynchronous I/O that uses IRPs and event callbacks to enhance performance.

WSK was designed with the following goals in mind:

o Provide a simple to use, Winsock2-like interface to kernel mode developers.

oBetter expose the innovations made by the next generation TCP/IP stack in Windows Vista

o Improve scalability and efficiency by improving on the performance and memory limitations of previous Network Programming Interfaces (NPI). For example, WSK has improved socket creation performance and a smaller memory footprint per socket than past NPIs.

o Easy to port existing TDI clients to WSK. Components such as http.sys (kernel mode HTTP handler) within Windows Vista have ported from TDI to WSK with ease.

At the core of WSK is the WSK subsystem, which implements the WSK Provider NPI. At its upper edge, WSK exposes this provider implementation for use by WSK applications. At its lower edge, the WSK subsystem interfaces with transport providers such as the TCP/IP stack. WSK applications implement the WSK Client NPI and consume the WSK Provider NPI to perform network I/O operations.

Note: All components in the diagram above reside in the kernel

Some of the additional benefits in WSK include:

o Enhanced IPv6 support. WSK clients can use a single IPv6 socket to handle both IPv4 and IPv6 traffic. For example a single WSK listening socket can accept both IPv4 and IPv6 connections.

o Improved Serviceability. The WSK subsystem hides the intricacies of transport discovery and load/unload handling from the WSK clients. This allows the WSK subsystem to improve the system’s serviceability with minimal direct impact on WSK clients.

o Uniform support for standard options or IOCTLs across all transports

TDI and WSK

TDI is a widely used interface to interact with the network stack and intercept application traffic. Since prior to Windows Vista, the user mode Winsock2 API used the TDI interface to interact with TCP/IP. Kernel-mode TDI filter drivers were used by some software vendors to intercept all Winsock traffic before it was submitted to the TCP/IP stack. A TDI client also enabled a driver to send and receive data to/from the TCP/IP stack. Even though TDI has been a worthy predecessor for WSK for over a decade, it has shortcomings such as a sharp learning curve and performance bottlenecks.

In Windows Vista, WSK is the recommended NPI for performing network I/O in the kernel and the Windows Filtering Platform (WFP) is the recommended API for network filtering (replacement for TDI filter drivers). New kernel mode clients should opt to use WSK for network I/O instead of TDI because WSK is more flexible, easier to use, and offers much better performance. To take advantage of the next generation stack, existing TDI applications should move to WSK in the Windows Vista timeframe. On Windows Vista, TDI is still supported; however, it has been implemented using a translation layer and thus its performance is sub-optimal resulting in performance degradation for TDI clients. In addition, the capabilities that are available using TDI are going to be significantly more limited than through WSK as no new functionality is being developed for TDI.

WSK applications are not limited to the TCP/IP transport implemented in the next generation TCP/IP stack in Windows Vista. WSK allows its clients to use protocols implemented by TDI-based transports by translating WSK operations to TDI operations on behalf of the client for those TDI transports denoted by the client. This gives clients of WSK the convenience of a single NPI rather than using WSK for some protocols and TDI for others. WSK also allows TDI filters to intercept TCP/IP traffic to/from WSK clients to facilitate a smooth transition period during which software vendors move from TDI filters to WFP for performing network traffic filtering.

Additional Information

If you have any questions, comments or would like to obtain a copy of the WSK documentation and associated sample, please email wskapi@microsoft.com.

WSK bugs and feature suggestions can be submitted to the Microsoft bug database by joining the Windows Network Developer Platform (WNDP) program at the Microsoft Connect website: http://connect.microsoft.com.

Note: The WSK sample will not build in WDK build 5308 due to missing header files. This is a known issue and should be corrected in the Beta 2 WDK.

-- Mike Flasko

Winsock and Vista User Account Control

wndpteam — Wed, 22 Feb 2006 20:41:00 GMT

As you might have heard, Vista introduces User Account Control (UAC) which is a security feature that enables users to perform some tasks as non-Administrators. This has an effect on LSP writers as the Winsock functions to install and remove LSP entries can only be called as an Administrator. On Vista there is a difference between the built in local Administrator account and users that are a member of the Administrators group. That is, users that are a member of the Administrators group are actually running with reduced privileges compared to the built in Administrator account.

The effect of this change is that the LSP install functions will return an access denied error unless the user is the built-in Administrator or unless the installing application is modified to prompt the user whether the installation should be allowed. The sample LSP has been updated to illustrate this change. The updated sample can be obtained from the Microsoft Connect website:

http://connect.microsoft.com

Once at the site, select 'available programs' from the navigation bar on the left side of the screen. You then need to join the 'WNDP' (Windows Network Developer Platform) group. From there the sample is available in the 'downloads' section.

In order for the install application to prompt a limited user whether to continue with the installation, an application manifest needs to be created. This is an XML file named the same as the installing executable with '.manifest' appended to the end (e.g. instlsp.exe.manifest). The manifest is pretty simple – it simply describes the application and indicates that the application requires administrative privileges to install correctly:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<assembly xmlns="urn:schemas-microsoft-com:asm.v1"

manifestVersion="1.0">

<assemblyIdentity version="1.0.0.0"

name="instlsp.exe"

type="win32"/>

<description>instlsp - Sample LSP installer</description>

<requestedExecutionLevel

level="requireAdministrator"

uiAccess="false"/>

</requestedPrivileges>

</security>

</trustInfo>

</assembly>

Once the manifest is created, it simply needs to be referenced in the application’s resource file with the following directive:

#define MANIFEST_RESOURCE_ID 1

MANIFEST_RESOURCE_ID RT_MANIFEST "instlsp.exe.manifest"

You can take a look at the updated sample for the full details, but it is pretty straight forward.

There are a number of UAC related resources to find more information:

Getting Started with UAC

http://www.microsoft.com/technet/windowsvista/evaluate/fea t/uaprot.mspx

UAC Developer Guidelines

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnlong/html/AccProtVista.asp

UAC Blog

http://blogs.msdn.com/uac

UAC Question on Update

http://forums.microsoft.com/msdn/showpost.aspx?postid=111 453&siteid=1

-- Anthony Jones (AJones)

Categorizing LSPs and Applications

wndpteam — Fri, 10 Feb 2006 03:53:00 GMT

In Windows Vista there is a new method for categorizing both Winsock Layered Service Providers (LSP) and applications themselves such that only certain LSPs will be loaded. There are a couple reasons for adding this functionality. One of the main reasons is certain system critical processes such as WinLogon and LSASS create sockets but do not send any traffic on the network so most LSPs should not be loaded. A large percentage of the crashes we see are due to buggy LSPs that cause LSASS.EXE to crash and if it crashes the system forces a shutdown. A side affect of these system processes loading LSPs is that these processes never exit so when an LSP is installed or removed, a reboot is required.

Secondly, there are some cases where applications may not want to load certain LSPs. For example, some apps may not want to load crypto LSPs so they can communicate with other machines that do not have the cypto LSP installed.

Finally, the LSP categories can be used by other LSPs to determine where in the Winsock protocol chain they should install themselves. For years, various LSP developers have wanted a way of knowing how an LSP will behave. For example, an LSP that inspects the data stream would want to be above an LSP that encrypts the data. Of course, this method isn’t fool proof since it relies on 3^rd party LSPs to categorize themselves appropriately, but hopefully, the security enhancements in Vista will help prevent users from unintentionally installing malicious LSPs.

Winsock has defined nine different types of LSPs:

LSP_SYSTEM – an LSP that should be loaded into system critical processes
LSP_INSPECTOR – an LSP that simply monitors the inbound and outbound traffic but does not the data. An HTTP content filterer is an example of an inspector (as it will deny the request).
LSP_REDIRECTOR – this type of LSP simply modifies the addresses used in Winsock calls.
LSP_PROXY – this LSP redirects Winsock calls to a proxy server as well as instruct the proxy via a control channel to establish outbound connections.
LSP_FIREWALL – an LSP that monitors incoming and outbound connection requests. A firewall LSP should only inspect data and deny request but not actually modify the data.
LSP_INBOUND_MODIFY – filters inbound data
LSP_OUTBOUT_MODIFY – filter outbound data
LSP_CRYPTO_COMPRESS – a crypto or compression LSP can modify both inbound and outbound traffic but also includes and out of band signing/negotiation phase.
LSP_LOCAL_CACHE – an LSP that inspects the contents of a Winsock request and satisfying the request by generating the expected response without the request actually hitting the intended destination.

Note that it is possible to categorize an LSP as more than one type. In fact an LSP categorized as LSP_SYSTEM should also be categorized with the type(s) that best describe how it inspects or modifies the Winsock calls.

On Vista , the majority of the system critical processes and system services are already registered with the appropriate categories depending on their functionality.

Categorizing LSPs

There are two new APIs for categorizing an LSP which are defined in ws2spi.h:

int

WSPAPI

WSCSetProviderInfo(

LPGUID lpProviderId,

WSC_PROVIDER_INFO_TYPE InfoType,

PBYTE Info,

size_t InfoSize,

DWORD Flags,

LPINT lpErrno

);

int

WSPAPI

WSCGetProviderInfo(

LPGUID lpProviderId,

WSC_PROVIDER_INFO_TYPE InfoType,

PBYTE Info,

size_t *InfoSize,

DWORD Flags,

LPINT lpErrno

);

In order to categorize an LSP, WSCSetProviderInfo is called that specifies the GUID of the hidden LSP entry (i.e. the LSP entry installed whose ProtocolChain.ChainLen is zero). The WSC_PROVIDER_INFO_TYPE is an enumeration and ProviderInfoLspCategories should be passed. Then a simple DWORD with the appropriate LSP_* flags above is passed as the Info parameter. For example:

DWORD lspCategory = LSP_INBOUND_MODIFY | LSP_OUTBOUND_MODIFY;

GUID lspGuid = &YOUR_LSP_GUID;

int rc, err;

rc = WSCSetProviderInfo( &lspGuid, ProviderInfoLspCategories,

(PBYTE) &lspCategory, sizeof(lspCategory), 0, &err);

Retrieving the LSP category is similar to setting it but using the WSCGetProviderInfo call.

Categorizing Applications

The other part of the equation is categorizing applications themselves to specify those LSPs that should be loaded in its process. This is done via the following two functions also defined in ws2spi.h:

int

WSPAPI

WSCSetApplicationCategory(

LPCWSTR Path,

DWORD PathLength,

LPCWSTR Extra,

DWORD ExtraLength,

DWORD PermittedLspCategories,

DWORD * pPrevPermLspCat,

LPINT lpErrno

);

int

WSPAPI

WSCGetApplicationCategory(

LPCWSTR Path,

DWORD PathLength,

LPCWSTR Extra,

DWORD ExtraLength,

DWORD * pPermittedLspCategories,

LPINT lpErrno

);

In the functions above Path is the full path and executable name while Extra is the arguments passed to that application. The Path argument can contain environment variables as the function calls will expand them as necessary. Note that an application is defined as the full path and executable name as well as any arguments. Thus if the application “c:\foo.exe” is categorized as LSP_PROXY, the application “c:\foo.exe –x 12” is different and would not be considered as allowing LSP_PROXY LSPs.

The following code categorizes “foo.exe –x 12”:

rc = WSCSetApplicationCategory(

L”%windir%\\foo.exe”,

lstrlenW(L”%windir%\\foo.exe”),

L”-x 12”,

lstrlenW(L”-x 12”),

LSP_SYSTEM | LSP_FIREWALL | LSP_CRYPTO_COMPRESS,

NULL,

&err

);

The pPrevPermLspCat parameter is optional and simply returns the previous categories set for this application if it existed.

Determining Which LSPs Get Loaded

The final part of LSP categorization is determining which LSPs will be loaded into which processes. When a process loads Winsock, both the application category and the LSP categories for all installed LSPs and the following comparisons made:

If the application is not categorized, allow all LSPs
If both the application and the LSP have assigned categories, all of the following must be true:
1. At least one of the LSP categories is present in the application’s specified categories
2. ONLY categories specified in the application’s specified categories are specified in the LSPs categories (i.e. if the app specifies a category is must be in the LSP’s category, but if the app specifies a category that is not present in the LSPs category then that is OK)
3. If LSP_SYSTEM is present in the application’s category, it MUST be present in the LSP’s categories

NOTE: If an LSP is not categorized its category is effectively 0. Basically, for a match to occur all the LSP’s specified categories must be present in the application’s categories (i.e. the app must be a superset of the LSP) – with the caveat that if LSP_SYSTEM is present in the app’s category is must also be present in the LSP’s category.

Consider the following example:

Foo.exe is categorized as LSP_SYSTEM + LSP_FIREWALL + LSP_CRYPTO_COMPRESS

Bar.exe is categorized as LSP_FIREWALL + LSP_CRYPTO_COMPRESS

There are four LSPs installed on the system:

LSP1: LSP_SYSTEM

LSP2: 0 (no category set)

LSP3: LSP_FIREWALL

LSP4: LSP_SYSTEM + LSP_FIREWALL + LSP_CRYPTO_COMPRESS + LSP_INSPECTOR

In this example, Foo.exe would only load LSP1 while Bar.exe would load LSP3.

--Anthony Jones (AJones)