Winsock Secure Socket Extensions

In the second edition of Writing Secure Code, we said we hoped one day we’d be able to require IPSec on a socket at run time from an application, instead of hoping that the administrator had read the manual and actually configured the application at the network level. It seems that the networking team was listening, because exactly this functionality ended up shipping in Windows Vista. The Windows Platform SDK topic to look up is “Windows Filtering Platform API Secure Socket Functions.” We’re only going to give you a quick overview of these functions here. The first function is WSASetSocketSecurity. Your code should call WSASetSocketSecurity before either calling bind (assuming you’re writing a server) or connect (assuming you’re creating a client), and if you’re writing a kernel mode application, you’ll need to use WSAIoctl to set the security settings. To use this API, you’ll need to set up a SOCKET_SECURITY_SETTINGS structure, which is defined here:

 typedef struct _SOCKET_SECURITY_SETTINGS {    SOCKET_SECURITY_PROTOCOL securityProtocol;    ULONG securityFlags; } SOCKET_SECURITY_SETTINGS;

The securityProtocol member has two valid values currently defined: SOCKET_SECURITY_PROTOCOL_DEFAULT, which is what you’d get using a default socket, and SOCKET_SECURITY_PROTOCOL_IPSEC, which actually enforces that IPSec be used for this socket. Unfortunately, it isn’t quite that simple. Once you set the SecurityProtocol member to SOCKET_SECURITY_PROTOCOL_IPSEC, WSASetSocketSecurity expects to be passed a SOCKET_SECURITY_SETTINGS_IPSEC structure. The first option you can use determines whether IPSec is required to allow connections, or we’ll just use IPSec when available, which is done by setting the SecurityFlags member to either SOCKET_SETTINGS_GUARANTEE_ENCRYPTION or SOCKET_SETTINGS_ALLOW_INSECURE. If you choose to allow insecure connections, you may want to call WSAQuerySocketSecurity on connections and branch your code depending on whether the connection is secure or not. There is one flag in the IpsecFlags member defined–SOCKET_SETTINGS_IPSEC_SKIP_FILTER_INSTANTIATION– which is used when you know that the IPSec policy has already been configured for your application. Note that if you supply NULL as the pointer to the SOCKET_SECURITY_SETTINGS structure, default IPSec configuration for that system will be applied to your application.

Although we’ve been able to do server authentication and impersonation of socket clients in the past, it involved writing quite a lot of fairly messy Security Support Provider Interface (SSPI) code. Among the improvements in Windows Vista is WSASetSocketPeerTargetName, which allows the client to specify the service principal name (SPN) of the server and application (Microsoft 2007) they want to connect to. If this option is used, once connect returns success, we know we’ve connected to the server we intended to connect to. It’s important to know what server you’re connecting to, because the next interesting API is WSAImpersonateSocketPeer, which is what the server is going to call to identify the user that’s just connected and to make access control decisions. If you’re writing a server application, be sure to check whether the impersonation succeeded, and remember to call WSARevertImpersonation as soon as you’re done checking access. You should also remember to carefully take into account exceptions (whether C++ or SEH exceptions) thrown while inside a block that’s impersonating. If you’re able to leverage C++, a good approach is to create a class that reverts the impersonation in the destructor–then you’re guaranteed to revert as the stack unwinds. If you’re using C, or can’t use C++ exception handlers, try-finally can achieve the same effect.

Overall, this is a great set of useful new API calls. The alternative is to write a lot of messy code, and we’ve seen ISVs go as far as using embedded Web servers with SSL/TLS to accomplish the same thing–too bad they also forgot to set up certificates correctly for the SSL/TLS connection and accomplished little more than security by obscurity. Once the platform support for the new socket options is widespread, these new socket options will make getting real security a lot easier.