Programmers rely on documentation. It's how we learn to use APIs. Misusing APIs is a leading source of vulnerability. You might think that documentation is a cure to this ailment. Unfortunately, as someone who has been in software development for a long time, I can tell you that documentation quality is not always what it should be. API documentation serves as a reference. I have yet to meet the programmer who can recall every nuance about every API for all the languages they program in. (Were such a programmer to exist, its name might well be Robby the Robot.)
Recently I was converting strings using the mbstowcs_s and wcstombs_s functions. (These are from from the bounds checking extensions to the C Library specified in ISO/IEC TR 24731-1.) These functions allow you to convert multibyte character sequences to and from wide character sequences. These functions are available to C and C++ programmers using Microsoft's Visual Studio compiler. (I am not yet aware of any UNIX compatible compiler that supports the draft TR 24731-1 standard.)
Since these two functions convert strings, it is worth looking at the parameters they expect. (Not doing so is a sure fire way to do something stupid, like enable a buffer overflow.) Looking at the relevant parameters for these two functions, we see:
mbstowcs_s:
[in] sizeInWords
The size of the wcstr buffer in words.
[in] count
The maximum number of wide characters to store in the wcstr buffer, not including the terminating null, or _TRUNCATE.
wcstombs_s:
[in] sizeInBytes
The size in bytes of the mbstr buffer.
[in] count
The maximum number of bytes to be stored in the mbstr buffer, or _TRUNCATE.
Does count in wcstombs_s account for the terminating NULL or not? Failure to account for this could introduce an off-by-one error which, in turn, may lead to an exploitable condition, such as a buffer overflow. How can we determine this from the documentation? Well, in its current state, we can't. This is what we call a “doc bug.”
Luckily, Microsoft includes the source code for the C Runtime with most Visual Studio SKUs. Assuming you installed Visual Studio in Program Files, you should be able to find the CRT source code in Program Files\Microsoft Visual Studio 9.0\VC\crt\src. CRT source code is included with all Visual Studio SKUs except for the Express Editions. Luckily for Express Edition users, the forthcoming Visual Studio 2010 release finally opens up the CRT sources to Express Edition users. If you are using an Express Edition of VS2008 or earlier, consider grabbing the VS2010 Express beta from here.
In any case, if you have the CRT source code, it is easy to track down the source for wcstombs_s and check to see if the terminating NULL is intended to be accounted for or not. Looking into wcstombs.c we discover this bit of text in the comment for the wcstombs_s function:
size_t n = maximum number of bytes to store in s (not including the terminating NULL)
Clearly, the terminating NULL is not meant to be included. This is as we suspected, but now we have verified it instead of blindly assuming that it would be the case. As security practitioners we should be careful not to make assumptions. Verify instead!
This documentation bug has been reported to Microsoft. With any luck it will get addressed prior to the VS 2010 release on March 22, 2010.