How to Use Schannel for SSL Sockets on Windows

Did you know that Windows offers a native SSL sockets facility? You’d figure that since IE has SSL support, and MS SQL has SSL support, and .NET has SSL support, that there would be some lower-level SSL support available in Windows. It’s there. Really. But you’ll have a hard time finding any clear, explanatory documentation on it.

I spent most of the past month adding SSL support to Apache Qpid on Windows, both client and broker components. I used a disproportionate amount of that time struggling with making sense of the Schannel API, as it is poorly documented. Some information (such as a nice overview of how to make use of it) is missing, and I’ll cover that here. Other information is flat out wrong in the MSDN docs; I’ll cover some of that in a subsequent post.

I pretty quickly located some info in MSDN with the promising title “Establishing a Secure Connection with Authentication”. I read it and really just didn’t get it. (Of course, now, in hindsight, it looks pretty clear.) Part of my trouble may have been a paradigm expectation.   Both OpenSSL and NSS pretty much wrap all of the SSL operations into their own API which takes the place of the plain socket calls. Functions such as connect(), send(), recv() have their SSL-enabled counterparts in OpenSSL and NSS; adding SSL capability to an existing system ends up copying the socket-level code and replacing plain sockets calls with the equivalent SSL calls (yes, there are some other details to take care of, but model-wise, that’s pretty much how it goes).

In Schannel the plain Windows Sockets calls are still used for establishing a connection and transferring data. The SSL support is, conceptually, added as a layer between the Winsock calls and the application’s data handling. The SSL/Schannel layer acts as an intermediary between the application data and the socket, encrypting/decrypting and handling SSL negotiations as needed. The data sent/received on the socket is opaque data either handed to Windows for decrypting or given by Windows after encrypting the normal application-level data. Similarly, SSL negotiation involves passing opaque data to the security context functions in Windows and obeying what those functions say to do: send some bytes to the peer, wait for more bytes from the peer, or both. So to add SSL support to an existing TCP-based application is more like adding a shim that takes care of negotiating the SSL session and encrypting/decrypting data as it passes through the shim.

The shim approach is pretty much how I added SSL support to the C++ broker and client for Apache Qpid on Windows. Once I got my head around the new paradigm, it wasn’t too hard. Except for the errors and omissions in the encrypt/decrypt API documentation… I’ll cover that shortly.

The SSL support did  not get into Qpid 0.6, unfortunately. But it will be in the development stream shortly after 0.6 is released and part of the next release for sure.

4 Responses to “How to Use Schannel for SSL Sockets on Windows”

  1. James Mansion Says:

    Isn’t this model available everywhere with OpenSSL too, using memory BIOs?

    I think Len Holgate went there some time ago:

    I haven’t looked at the SChannel APIs yet but your description of them looks like using a BIO pair so that OpenSSL can be a stream filter rather than replacing the socket APIs.

  2. Len Holgate Says:


    Yes, you can use the “shim” approach with OpenSSL as well if you use BIOs rather than the socket functions and IMHO it’s a much better approach and pretty much the only route you can take if you want to work with async sockets.

    The SChannel model is slightly lower level than the OpenSSL model (assuming you take the BIO route with OpenSSL) as OpenSSL will accumulate the data for you (so you can just keep pushing encrypted data into it and it will spit out cleartext data once it has enough to process) whereas SChannel requires that you do your own accumulation.


    I agree the SChannel docs are a little bit of a handful. I found that reading up on the other SSPI protocols helped me to understand how the SChannel stuff worked, as did the MSDN sample. The docs could be better though 🙂

  3. r.ashok Says:

    Is there any proper API documentation available for SChannel apis to setup C SSL client or server ? I can do with OpenSSL APIs, now I wanted to do with SChannel SSL APIs but I am not able to find proper samle code and API documentation.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

<span>%d</span> bloggers like this: