Generate the readme from the example

This commit is contained in:
doyle 2023-08-28 22:12:55 +10:00
parent 591956471e
commit 1f5070f456
2 changed files with 304 additions and 19 deletions

View File

@ -1,10 +1,9 @@
#define WIN32_MEAN_AND_LEAN #include <sanitizer/asan_interface.h>
#include <Windows.h>
#include <stdint.h> #include <stdint.h>
#include <stdio.h> #include <stdio.h>
#include <assert.h> #include <assert.h>
#include <sanitizer/asan_interface.h> #include <string.h>
#define IsPowerOfTwo(value, pot) ((((size_t)value) & (((size_t)pot) - 1)) == 0) #define IsPowerOfTwo(value, pot) ((((size_t)value) & (((size_t)pot) - 1)) == 0)
#define AsanAlignment 8 #define AsanAlignment 8
@ -57,15 +56,81 @@ static void PrintPoisonMemoryRegion(int step, char const *array, size_t array_si
int main() int main()
{ {
printf("Here we demonstrate that ASAN poison-ing will only poison the\n" printf(
"byte region if the region meets an 8 byte boundary. It will only\n" "# ASAN Manual Poisoning\n"
"poison bytes upto the 8 byte boundary, any bytes that straddle\n" "\n"
"the boundary that do not hit the next 8 byte boundary are not\n" "## TLDR\n"
"poison-ed.\n\n"); "\n"
"`__asan_poison_memory_region(ptr, size)`\n"
"\n"
"Poisons the byte region `[ptr, AlignDown(ptr+size, 8))`\n"
"\n"
"`__asan_unpoison_memory_region(ptr, size)`\n"
"\n"
"Unpoisons the byte region `[AlignDown(ptr, 8), ptr+size)`\n"
"\n"
"Use the provided macros that are conditionally enabled if ASAN is\n"
"defined from `<sanitizer/asan_interface.h>`.\n"
"\n"
"```\n"
"ASAN_POISON_MEMORY_REGION(addr, size)\n"
"ASAN_UNPOISON_MEMORY_REGION(addr, size)\n"
"```\n"
"\n"
"If in doubt, use `__asan_address_is_poisoned` to sanity check the\n"
"ranges requested to be un/poisoned to avoid potential gaps in\n"
"marked-up memory that may lead to undetected read/writes.\n"
"\n"
"## Overview\n"
"\n"
"ASAN provides a way to manually markup ranges of bytes to\n"
"prohibit or permit reads to those addresses. There's a short\n"
"foot-note in Google's "
"[AddressSanitizerManualPoisoning](https://github.com/google/"
"sanitizers/wiki/AddressSanitizerManualPoisoning)\n"
"documentation that states:\n"
"\n"
"```\n"
"If you have a custom allocation arena, the typical workflow would be\n"
"to poison the entire arena first, and then unpoison allocated chunks\n"
"of memory leaving poisoned redzones between them. The allocated\n"
"chunks should start with 8-aligned addresses.\n"
"```\n"
"\n"
"This repository runs some simple tests to clarify the behaviour of\n"
"the API on un/aligned addresses at various sizes without having\n"
"to dig into source code or read the [ASAN paper](https://static."
"googleusercontent.com/media/research.google.com/en/pubs/archive/"
"37752.pdf).\n"
"\n"
"We use a stack-allocated 16 byte array and test un/poisoning\n"
"various ranges of bytes from different alignments to clarify the\n"
"poisoning behaviour of the API.\n"
"\n"
"This reveals that calling the API haphazardly, unaligned or\n"
"straddling boundaries can lead to gaps in poisoned memory and hide\n"
"potential leaks (as also demonstrated in [Manual ASAN poisoning and\n"
"alignment](https://github.com/mcgov/asan_alignment_example)).\n"
"\n"
"## References\n"
"\n"
"- [Manual ASAN poisoning and alignment](https://github.com/mcgov/asan_alignment_example) example by `mcgov`\n"
"- [Address Sanitizer: A Fast Address Sanity Checker](https://static.googleusercontent.com/media/research.google.com/en/pubs/archive/37752.pdf)\n"
"- [sanitizer/asan_interface.h](https://github.com/llvm-mirror/compiler-rt/blob/master/include/sanitizer/asan_interface.h)\n"
"\n"
"## Raw Test Results\n"
"Here we demonstrate that ASAN poison-ing will only poison the\n"
"byte region if the region meets an 8 byte boundary. It will only\n"
"poison bytes upto the 8 byte boundary, any bytes that straddle\n"
"the boundary that do not hit the next 8 byte boundary are not\n"
"poison-ed.\n"
"\n");
uint32_t const ASAN_ALIGNMENT = 8; uint32_t const ASAN_ALIGNMENT = 8;
uint32_t const REGION_WINDOW = 7; uint32_t const REGION_WINDOW = 7;
char array[16] = {}; char array[16] = {};
printf("```\n");
for (size_t poison_index = 0; poison_index < sizeof(array) - (REGION_WINDOW - 1); poison_index++) { for (size_t poison_index = 0; poison_index < sizeof(array) - (REGION_WINDOW - 1); poison_index++) {
assert(IsPowerOfTwo(array, ASAN_ALIGNMENT)); assert(IsPowerOfTwo(array, ASAN_ALIGNMENT));
@ -87,12 +152,15 @@ int main()
__asan_unpoison_memory_region(array, sizeof(array)); __asan_unpoison_memory_region(array, sizeof(array));
printf("\n"); printf("\n");
} }
printf("```\n");
printf( printf(
"Now we demonstrate that unpoison-ing 1 byte in the 8 byte window\n" "Now we demonstrate that unpoisoning 1 byte in the 8 byte window\n"
"will unpoison all bytes prior to it up until the start of the window\n" "will unpoison all bytes prior to it up until the previous 8 byte \n"
"until the previous 8 byte boundary.\n\n"); "boundary.\n"
"\n");
printf("```\n");
for (size_t unpoison_index = 0; unpoison_index < sizeof(array); unpoison_index++) { for (size_t unpoison_index = 0; unpoison_index < sizeof(array); unpoison_index++) {
assert(IsPowerOfTwo(array, ASAN_ALIGNMENT)); assert(IsPowerOfTwo(array, ASAN_ALIGNMENT));
@ -133,11 +201,14 @@ int main()
__asan_unpoison_memory_region(array, sizeof(array)); __asan_unpoison_memory_region(array, sizeof(array));
} }
printf("```\n");
printf( printf(
"Unpoison-ing across 8 byte boundaries may lead to undesired\n" "Unpoisoning across 8 byte boundaries may lead to undesired\n"
"behaviour, with all bytes on the left side of the boundary being\n" "behaviour, with all bytes on the left side of the boundary being\n"
"unpoisoned\n\n"); "unpoisoned\n\n");
printf("```\n");
{ {
// NOTE: Print byte array ================================================================== // NOTE: Print byte array ==================================================================
@ -171,12 +242,6 @@ int main()
PrintPoisonedBytes(4 /*step*/, array, sizeof(array)); PrintPoisonedBytes(4 /*step*/, array, sizeof(array));
} }
printf("```\n");
printf("\n\nTLDR:\n"
" __asan_poison_memory_region(ptr, size)\n"
" Poisons the byte region [ptr, AlignDown(ptr+size, 8))\n\n"
" __asan_unpoison_memory_region(ptr, size)\n"
" Unpoisons the byte region [AlignDown(ptr, 8), ptr+size)\n\n"
);
return 0; return 0;
} }

220
readme.md Normal file
View File

@ -0,0 +1,220 @@
# ASAN Manual Poisoning
## TLDR
`__asan_poison_memory_region(ptr, size)`
Poisons the byte region `[ptr, AlignDown(ptr+size, 8))`
`__asan_unpoison_memory_region(ptr, size)`
Unpoisons the byte region `[AlignDown(ptr, 8), ptr+size)`
Use the provided macros that are conditionally enabled if ASAN is
defined from `<sanitizer/asan_interface.h>`.
```
ASAN_POISON_MEMORY_REGION(addr, size)
ASAN_UNPOISON_MEMORY_REGION(addr, size)
```
If in doubt, use `__asan_address_is_poisoned` to sanity check the
ranges requested to be un/poisoned to avoid potential gaps in
marked-up memory that may lead to undetected read/writes.
## Overview
ASAN provides a way to manually markup ranges of bytes to
prohibit or permit reads to those addresses. There's a short
foot-note in Google's [AddressSanitizerManualPoisoning](https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning)
documentation that states:
```
If you have a custom allocation arena, the typical workflow would be
to poison the entire arena first, and then unpoison allocated chunks
of memory leaving poisoned redzones between them. The allocated
chunks should start with 8-aligned addresses.
```
This repository runs some simple tests to clarify the behaviour of
the API on un/aligned addresses at various sizes without having
to dig into source code or read the [ASAN paper](https://static.googleusercontent.com/media/research.google.com/en/pubs/archive/37752.pdf).
We use a stack-allocated 16 byte array and test un/poisoning
various ranges of bytes from different alignments to clarify the
poisoning behaviour of the API.
This reveals that calling the API haphazardly, unaligned or
straddling boundaries can lead to gaps in poisoned memory and hide
potential leaks (as also demonstrated in [Manual ASAN poisoning and
alignment](https://github.com/mcgov/asan_alignment_example) example
by `mcgov`.
## References
- [Manual ASAN poisoning and alignment](https://github.com/mcgov/asan_alignment_example) example by `mcgov`
- [Address Sanitizer: A Fast Address Sanity Checker](https://static.googleusercontent.com/media/research.google.com/en/pubs/archive/37752.pdf)
- [sanitizer/asan_interface.h](https://github.com/llvm-mirror/compiler-rt/blob/master/include/sanitizer/asan_interface.h)
## Raw Test Results
Here we demonstrate that ASAN poison-ing will only poison the
byte region if the region meets an 8 byte boundary. It will only
poison bytes upto the 8 byte boundary, any bytes that straddle
the boundary that do not hit the next 8 byte boundary are not
poison-ed.
```
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x |
2. __asan_address_is_poisoned |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x |
2. __asan_address_is_poisoned x x x x x x x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x | x
2. __asan_address_is_poisoned x x x x x x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x | x x
2. __asan_address_is_poisoned x x x x x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x | x x x
2. __asan_address_is_poisoned x x x x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x | x x x x
2. __asan_address_is_poisoned x x x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x | x x x x x
2. __asan_address_is_poisoned x x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x | x x x x x x
2. __asan_address_is_poisoned x |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region | x x x x x x x
2. __asan_address_is_poisoned |
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region | x x x x x x x
2. __asan_address_is_poisoned | x x x x x x x
```
Now we demonstrate that unpoisoning 1 byte in the 8 byte window
will unpoison all bytes prior to it up until the previous 8 byte
boundary.
```
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x x x x x x x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x x x x x x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x x x x x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x x x x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x x x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned x | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x |
4. __asan_address_is_poisoned | x x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x | x
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region | x
4. __asan_address_is_poisoned x x x x x x x x |
```
Unpoisoning across 8 byte boundaries may lead to undesired
behaviour, with all bytes on the left side of the boundary being
unpoisoned
```
Byte Array 00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15
1. __asan_poison_memory_region x x x x x x x x | x x x x x x x x
2. __asan_address_is_poisoned x x x x x x x x | x x x x x x x x
3. __asan_unpoison_memory_region x | x
4. __asan_address_is_poisoned | x x x x x x x
```