openssl/NOTES-SANITIZERS.md

Notes on Sanitizers

Compiler sanitizers are tools that can be enabled during compilation to detect various types of bugs at runtime. OpenSSL supports three sanitizers:

• AddressSanitizer (ASan): Detects memory errors such as use-after-free, buffer overflows, and memory leaks.
• UndefinedBehaviorSanitizer (UBSan): Detects undefined behavior such as integer overflow, null pointer dereference, and type mismatches.
• MemorySanitizer (MSan): Detects use of uninitialized memory.

Sanitizers are generally faster than Valgrind and can detect certain issues that Valgrind cannot, making them a useful complement to Valgrind-based testing.

Requirements

1. GCC or Clang compiler with sanitizer support
   • GCC 4.8+ or Clang 3.1+ for ASan and UBSan
   • Clang only for MSan (GCC does not implement MemorySanitizer)
2. Linux, macOS, or other supported platform
   • Note: MSan is only supported on Linux
   • Note: Leak detection (LSan) is not yet supported on macOS

Building with Sanitizers

OpenSSL provides configuration options to enable sanitizers:

AddressSanitizer (ASan)

$ ./config enable-asan
$ make

UndefinedBehaviorSanitizer (UBSan)

$ ./config enable-ubsan
$ make

MemorySanitizer (MSan)

MSan is only implemented by Clang, so the compiler must be set to clang:

$ CC=clang ./config enable-msan
$ make

Note: MSan requires that all code, including libraries, be compiled with MSan. This makes it more difficult to use than ASan or UBSan.

Combining Sanitizers

ASan and UBSan can be used together:

$ ./config enable-asan enable-ubsan
$ make

Note: ASan and MSan cannot be used together as they are mutually exclusive.

Running Tests

After building with sanitizers enabled, run the tests normally:

$ make test

The sanitizers will automatically detect issues during test execution and report them to stderr. If a sanitizer detects an error, the test will fail.

Running Specific Tests

To run a specific test with verbose output:

$ make test TESTS=test_name VERBOSE=1

Sanitizer Environment Variables

Sanitizer behavior can be controlled via environment variables:

ASAN_OPTIONS

Controls AddressSanitizer behavior. Common options:

# Allow malloc to return NULL instead of aborting
ASAN_OPTIONS=allocator_may_return_null=1

# Disable leak detection (LSan runs as part of ASan by default)
ASAN_OPTIONS=detect_leaks=0

# Get more detailed stack traces
ASAN_OPTIONS=fast_unwind_on_malloc=0

UBSAN_OPTIONS

Controls UndefinedBehaviorSanitizer behavior:

# Print stack traces for UBSan errors
UBSAN_OPTIONS=print_stacktrace=1

MSAN_OPTIONS

Controls MemorySanitizer behavior:

# Allow malloc to return NULL instead of aborting
MSAN_OPTIONS=allocator_may_return_null=1

Example with environment variables:

$ ASAN_OPTIONS=detect_leaks=1 make test TESTS=test_name

Interpreting Results

When a sanitizer detects an issue, it will print a detailed error report including:

• The type of error (e.g., "heap-buffer-overflow", "use-after-free")
• Stack trace showing where the error occurred
• Stack trace showing where the memory was allocated (for memory errors)
• Information about the memory region involved

Example ASan output:

==12345==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x...
    #0 0x... in function_name file.c:123
    #1 0x... in caller_function file.c:456
    ...

Comparison with Valgrind

Feature	Sanitizers	Valgrind
Performance	~2x slowdown	~10-50x slowdown
Requires recompilation	Yes	No
Memory leak detection	ASan (with LSan)	Yes
Uninitialized memory	MSan	Yes
Buffer overflow detection	ASan	Yes
Undefined behavior	UBSan	Limited
Platform support	Linux, macOS	Linux, macOS, etc

See Also

• NOTES-VALGRIND.md - Running tests with Valgrind
• test/README.md - General test documentation
• AddressSanitizer documentation
• UndefinedBehaviorSanitizer documentation
• MemorySanitizer documentation