Windows Core Networking : WSK

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

TDI Client to Winsock Kernel (WSK) Porting Survey

wndpteam — Thu, 19 Oct 2006 19:19:42 GMT

As you know per previous posts on this blog, Winsock Kernel, a new transport-independent kernel mode Network Programming Interface (NPI), is available on Windows Vista and Windows Server Longhorn platforms. On Windows Vista & Windows Server Longhorn, TDI is still supported for compatibility reasons; however, it has been implemented using a translation layer and thus its performance is sub-optimal resulting in performance degradation for TDI clients. For this reason, as well as others (TDI on path to deprecation, etc -- see resource links below), drivers should opt to use WSK whenever possible.

To help us understand how we can best make WSK adoption and porting from TDI to WSK straightforward, we would appreciate it if you could respond to the following questions. Responses can be sent to wskapi at microsoft.com

If you have an existing TDI Client driver:

1) Which operating systems does your TDI client support (Windows XP and/or Windows Server 2003, etc)?

2) Do you plan to port your TDI client to WSK on Windows Vista / Windows Longhorn server OR do you plan to continue to use your TDI-based driver on Windows Vista / Windows Longhorn Server?

a. If WSK was also supported on Windows XP and/or Windows Server 2003, would your answer to question #2 above change? If so, how?

If you are working on a new project which requires a kernel mode driver with network capabilities:

3) Do you plan to support Windows XP / Windows 2003 with the project deliverable? If so, would you use WSK for the project if it was available on these platforms?

Additional Requirements:

4) Do you have any requirements (performance, etc) that would need to be met by WSK (on pre Windows Vista platforms) in order for WSK to be an option on such platforms?

WSK Resources

Overview of WSK: http://blogs.msdn.com/wndp/archive/2006/02/24/538746.aspx

Network Programming with Winsock Kernel: http://blogs.msdn.com/wndp/archive/2006/05/04/Winhec-blog-wsk.aspx

WSK MSDN Documentation: http://msdn.microsoft.com/library/en-us/NetLH_d/hh/NetLH_d/wsk_2bb30f2b-db42-465a-9abd-61a7a7515273.xml.asp?frame=true

WDK RC1 Download: See http://connect.microsoft.com, Windows Driver Kit Program, Downloads Section

If you have any further comments or questions, please feel free to contact us at wskapi at microsoft.com.

We look forward to your feedback.

--Mike Flasko

Network Programming with Winsock Kernel (WSK)

wndpteam — Thu, 04 May 2006 16:00:00 GMT

Winsock Kernel (WSK) is the latest network programming interface introduced by the WNDP team in Windows Vista. As evident by its name, WSK can be used by kernel-mode drivers for sending and receiving data over the network. But less evident to many developers, WSK is not an interface for performing network “filtering”. Hence, to clarify a common misconception up front, if all you want is to perform some form of network traffic filtering or interception, then you are strongly advised to look at the Windows Filtering Platform (WFP) interface first. WFP is the one-stop shop for network filtering in Windows Vista.

As we have first presented in last year’s Driver DevCon and WinHEC 2005, our main goal with WSK is to provide a programming interface which is easier-to-use and has higher performance relative to its predecessor Transport Driver Interface (TDI) for kernel-mode network applications. Since last year, we have considerably improved the WSK documentation in the Windows Driver Kit (WDK), and have also added a WSK sample driver to the WDK. A preview version of the pre-Beta2 WSK documents and sample is available as described in a previous blog on this site by Mike Flasko.

In WinHEC 2006, the session on WSK will be geared more towards the guidelines and best practices to follow in WSK to achieve optimal performance and stability. For those of you planning to attend the WSK session in WinHEC 2006, we encourage you to get familiar with the available WSK documents and the sample prior to the session to get the most out of the presentation. We have identified a number of areas in WSK over the past year based on feedback from both external and internal WSK clients that require more explanation and guidance. These include how to start and stop using WSK (WSK registration and deregistration), IRP handling, building and processing WSK_BUFs, when to use socket callbacks, how to achieve optimal throughput when sending stream data, how transport address security works, and how to use a single IPv6 socket for both IPv6 and IPv4 traffic. We will discuss all of these areas in depth in the WSK session in WinHEC 2006.

An important question I would like to address here is when to use WSK. Let’s look at this starting with a Winsock2 application in user-mode. If your Winsock2 application is working fine in the user-mode land, then you have no reason to consider a WSK-based implementation for that application. An important misconception here is to assume that a kernel-mode implementation will automatically provide much better performance than a user-mode implementation, which is not true. Remember also that kernel-mode programming has much stricter requirements in order to ensure a high degree of system stability and robustness; if your kernel-mode code is not rock solid, then moving your application into the kernel will cause more grief than good. Lastly, user-mode Winsock2 interface is a richer higher-level interface while, even though we have made it relatively simple and easy-to-use, WSK is still quite a low-level interface which sometimes requires an intimate familiarity of protocol-specific behavior from its clients to avoid pitfalls. To give a few concrete examples, Winsock2 does have dedicated routines for complex tasks like transmitting a file or connecting by name to remote peers whereas WSK doesn’t. Also as another less obvious example, Winsock2 performs buffering in the send direction, which allows even simple applications using blocking send requests to achieve decent throughput whereas WSK does not perform any “socket-level” buffering, hence requires the application to know about and account for things like Nagling, delayed-ack, bandwidth-delay product, etc to achieve decent throughput.

My personal guidance on implementing anything in kernel is to ask this question first: Is there a significant performance, stability, robustness, or security benefit in a kernel-mode implementation for a given functionality that can not otherwise be achieved by a user-mode implementation? This guidance may sound a bit abstract without a concrete example. So, let’s take a look at a real example. The HTTP.sys component in Windows Vista implements a kernel-mode HTTP stack by using the WSK interface. Prior to HTTP.sys, HTTP applications like Internet Information Services (IIS) used to use Winsock2 directly. The move to the HTTP.sys model was driven by several important factors. First, multiple HTTP applications running on the same system often needed to share a single TCP port (e.g. 80). Implementation of this sharing by keeping a clean and secure isolation between multiple HTTP application instances was not straight-forward via Winsock2 in user-mode. HTTP.sys has brought a robust solution to this problem by taking on the responsibility of managing multiple HTTP connections in kernel over a single WSK socket. This allowed applications like IIS to support multiple 3^rd party plug-ins running in user-mode, in isolation, and with least-privilege in order to achieve better system stability and security. Second, HTTP.sys has a kernel-mode cache implementation that allows it to satisfy incoming HTTP requests directly in the kernel without making a user-mode transition. A kernel-mode cache for HTTP.sys makes sense due to the static nature of HTTP content. The full benefit of this cache is made possible by receiving and sending data over a WSK socket in kernel directly. This boosts the overall performance. However, note that this performance factor alone can not be the sole reason for implementing an HTTP stack in kernel without the former factor.

I hope what was stated so far above gives you a pretty good idea about when to use WSK. As for how to use WSK in the best possible way, we will address that topic in the WSK session in WinHEC 2006. We hope to see all of you there!

-Osman N. Ertugay