Michael Howard
Senior Security Program Manager
Security Engineering
Microsoft Corporation

March 2007

Note: This paper is derived from the book The Security Development Lifecycle, by Michael Howard and Steve Lipner, Microsoft Press, 2006.

Prohibiting the use of banned APIs is a good way to remove a significant number of code vulnerabilities — this practice is reflected in Stage 6 of The Microsoft Security Development Lifecycle: "Establish and Follow Best Practices for Development." It can also be referenced in Chapter 11 of the Microsoft Press Book The Security Development Lifecycle.

When the C runtime library (CRT) was first created about 25 years ago, the threats to computers were different; machines were not as interconnected as they are today, and attacks were not as prevalent. With this in mind, a subset of the C runtime library must be deprecated for new code and, over time, removed from earlier code. It's just too easy to get code wrong that uses these outdated functions. Even some of the classic replacement functions are prone to error, too.

This list is the SDL view of what comprises banned APIs; it is derived from experience with real-world security bugs and focuses almost exclusively on functions that can lead to buffer overruns (Howard, LeBlanc, and Viega 2005). Any function in this section's tables must be replaced with a more secure version. Obviously, you cannot replace a banned API with another banned API. For example, replacing strcpy with strncpy is not valid because strncpy is banned, too.

Also note that some of the function names might be a little different, depending on whether the function takes ASCII, Unicode, _T (ASCII or Unicode), or multibyte chars. Some function names might include A or W at the end of the name. For example, the StrSafe StringCbCatEx function is also available as StringCbCatExW (Unicode) and StringCbCatExA (ASCII).

Table 1. Banned string copy functions and replacements

¹ For StrSafe, * should be replaced with Cch (character count) or Cb (byte count)

Table 2. Banned string concatenation functions and replacements

Table 3. Banned sprintf functions and replacements

Table 4. Banned "n" sprintf functions and replacements

Table 5. Banned variable argument sprintf functions and replacements

Table 6. Banned variable argument "n" sprintf functions and replacements

Table 7. Banned "n" string copy functions and replacements

Table 8. Banned "n" string concatenation functions and replacements

It is common wisdom to replace functions like strcpy with the counted "n" version, such as strncpy. However, in our experience, the "n" functions are also hard to secure (Howard 2004), so we have banned their use in new code.

Table 9. Banned string tokenizing functions and replacements

Table 10. Banned Makepath functions and replacements

Table 11. Banned Splitpath functions and replacements

Table 12. Banned scanf functions and replacements

Table 13. Banned "n" scanf functions and replacements

Table 14. Banned numeric conversion functions and replacements

Table 15. Banned gets functions and replacements

Table 16. Banned IsBad* functions and replacements

Table 17. Banned OEM conversion functions and replacements

Table 18. Banned stack dynamic memory allocation functions and replacements

For critical functions, such as those accepting anonymous Internet connections, strlen must also be replaced:

Table 19. Banned string length functions and replacements

Why the "n" Functions Are Banned

The classic C runtime "n" functions (such as strncpy and strncat) are banned because they are so hard to call correctly. The authors have seen numerous errors calling these functions in an attempt to make code more secure. Note that we're not saying the replacements are perfect, but issues with the current "n" functions include non-null termination of overflowed buffers and no error returns on overflow.

The newer StrSafe and Safe CRT functions are more consistent on failure.

Important Caveat

Simply replacing a banned function call with a better replacement does not guarantee that the code is secure. It's possible to misuse the replacement function, most commonly by getting the destination buffer size wrong.

Review all instances of replaced function calls, and verify that the destination buffer size is correct.

Choosing StrSafe vs. Safe CRT

There is an overlap between these two sets of replacement C runtime functions. Which you choose depends on your specific situation; the following table should help you make the decision. In some cases, you might have little choice but to use one over the other; for example, if your code calls itoa a great deal, there is no replacement in StrSafe, but there is in Safe CRT. You would need to either code around the itoa call or use Safe CRT.

Table 20.

Using StrSafe

To use StrSafe in your C or C++ code, simply add the following header:

#include "strsafe.h"

This will make the functions inline. If you want to use the library version, strsafe.lib, add the following to your code:

#define STRSAFE_LIB
#include "strsafe.h"

Note that all the StrSafe functions include Rtl versions for kernel use.

StrSafe Example

The following code

void Function(char *s1, char *s2) {
    char temp[32];
    strcpy(temp,s1);
    strcat(temp,s2);
}

when converted to StrSafe might look like this:

HRESULT Function(char *s1, char *s2) {
    char temp[32];
    HRESULT hr = StringCchCopy(temp,sizeof(temp),s1);
    if (FAILED(hr)) return hr;
    return StringCchCat(temp,sizeof(temp),s2);
}

Using Safe CRT

The Safe CRT is included with Visual Studio 2005. When you compile code using this compiler, it will automatically warn you of the deprecated functions in the code. Also, in some cases, the compiler will change some function calls to safe function calls if the destination buffer size is known at compile time and CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES is #defined in the code.

For example, the following code

int main(int argc, char* argv[]) {
    char t[10];
       ...
    if (2==argc) 
        strcpy(t,argv[1]);

       ...
    return 0;

}

is changed by the compiler to this:

int main(int argc, char* argv[]) {
    char t[10];
   ...
   if (2==argc) 
       strcpy_s(t,_countof(t),argv[1]);

   ...
   return 0;
}

Safe CRT Example

The following code

void Function(char *s1, char *s2) {
    char temp[32];
    strcpy(temp,s1);
    strcat(temp,s2);
}

when converted to the Safe CRT might look like this:

errno_t Function(char *s1, char *s2) {
    char temp[32];
    errno_t err = strcpy_s(temp,sizeof(temp),s1);
    if (!err) return err;
    return strcat_s(temp,sizeof(temp),s2);
}

Other Replacements

If you are using C++, you should seriously consider using the std::string template class rather than manipulating buffers directly.

Many *nix variants, including OpenBSD and some Linux operating systems, include support for string copy replacements strlcpy and strlcat (Miller and de Raadt 1999).

Tools Support

The Visual Studio 2005 compiler has built-in deprecations for these functions; all C4996 compiler warnings should be investigated to make sure that the function in question is not on the preceding banned list. Also, look out for code that disables this warning, such as #pragma warning(disable:4996).

ROI and Cost Impact

Removing banned APIs is one way to reduce potential security bugs with very little engineering effort, as can be seen at the start of this document. Some Microsoft security bulletins would not have been necessary if banned APIs had not been used.

Metrics and Goals

The metric to track is the number of banned APIs in former code and in new code. The quantity should be zero for new code and should follow a glide path down over time for earlier code.

References

(Howard, LeBlanc, and Viega 2005)

Howard, Michael, David LeBlanc, and John Viega. 19 Deadly Sins of Software Development. New York, NY: McGraw-Hill, 2005. Chapter 1, "Buffer Overruns."

(Howard 2004)

Howard, Michael. "Buffer Overflow in Apache 1.3.xx fixed on Bugtraq—the evils of strncpy and strncat," http://blogs.msdn.com/michael_howard/archive/2004/10/29/249713.aspx, October 2004.

(Miller and de Raadt 1999)

Miller, Todd C., and Theo de Raadt. USENIX Annual Technical Conference, "strlcpy and strlcat – Consistent, Safe String Copy and Concatenation," http://www.usenix.org/events/usenix99/full_papers/millert/millert_html/index.html, June 1999.