How to use macro for mbedtls_platform_zeroize() in Windows?

[irwir]

mbedtls/include/mbedtls/mbedtls_config.h

Lines 299 to 301 in 4122c16

	* if your platform has explicit_bzero() but `platform_util.c` does not
	* detect its presence, define `MBEDTLS_PLATFORM_ZEROIZE_ALT` to be
	* `explicit_bzero` to use that function as mbedtls_platform_zeroize().

Suppose the goal is to replace mbedtls_platform_zeroize with RtlSecureZeroMemory in MSVC.
The quoted text hints it is sufficient to write:
#define MBEDTLS_PLATFORM_ZEROIZE_ALT RtlSecureZeroMemory
Is this correct?

[tom-cosgrove-arm]

What's wrong with the SecureZeroMemory() it already uses on Windows? (Which is exactly the same, if I read the documentation correctly)

[irwir]

SecureZeroMemory is just a macro that expands to RtlSecureZeroMemory.
The idea is to avoid enveloped calls to the function and thus allow the compiler to make smaller and faster code.

[gilles-peskine-arm]

it is sufficient to write:
#define MBEDTLS_PLATFORM_ZEROIZE_ALT RtlSecureZeroMemory
Is this correct?

Yes, with one subtlety: MBEDTLS_PLATFORM_ZEROIZE_ALT(NULL, 0) must be valid (and do nothing). I'm not sure if we actually need that at the moment on platforms where calloc(0, 0) doesn't return NULL, but there's a lot of code in the library that accepts a null pointer for a zero-sized buffer.

By default, on Windows, mbedtls_platform_zeroize calls SecureZeroMemory, but only if the size is nonzero.

[irwir]

Yes, with one subtlety: MBEDTLS_PLATFORM_ZEROIZE_ALT(NULL, 0) must be valid (and do nothing).

With this definition the library compiles:
#define MBEDTLS_PLATFORM_ZEROIZE_ALT RtlSecureZeroMemory
Then building ssl_mail_client gives 46 link errors: unresolved external symbol mbedtls_platform_zeroize.

[gilles-peskine-arm]

Then building ssl_mail_client gives 46 link errors

That's odd. Is it just this program and no other? What build system are you using?

We do one test build with MBEDTLS_PLATFORM_ZEROIZE_ALT defined. It's on linux, with make.

[irwir]

Windows 11, Visual Studio 2022, library 3.5.0.

Edit. The symbol is undefined in the library, hence any program that needs to zeroize memory cannot be built.

[tom-cosgrove-arm]

Hmm, the doc says "Uncomment the macro to let Mbed TLS use your alternate implementation of mbedtls_platform_zeroize()", so - unlike many of the others - it's not #defined to the name of the function to use, but instead it gets #defined and then a separate mbedtls_platform_zeroize() function must be provided.

While the documentation goes on to say "For example, define MBEDTLS_PLATFORM_ZEROIZE_ALT to be explicit_bzero", that part is incorrect.

To actually use it as a #define, you'd have to do like we do in user-config-zeroize-memset.h, something like

#define mbedtls_platform_zeroize(buf, len) RtlSecureZeroMemory(buf, len)

and ensure the header needed for RtlSecureZeroMemory() is included everywhere it is needed

[irwir]

Has it ever been tested in Windows?

[irwir]

Yes, with one subtlety: MBEDTLS_PLATFORM_ZEROIZE_ALT(NULL, 0) must be valid (and do nothing). I'm not sure if we actually need that at the moment on platforms where calloc(0, 0) doesn't return NULL, but there's a lot of code in the library that accepts a null pointer for a zero-sized buffer.

Too much time passed since experiments with a pointer to memset trick, but probably this additional check for a null pointer was required for defeating optimizers - VS C++ compiler still was willing to skip memory cleaning otherwise.

[irwir]

While the documentation goes on to say "For example, define MBEDTLS_PLATFORM_ZEROIZE_ALT to be explicit_bzero", that part is incorrect.

Agreed.

To actually use it as a #define, you'd have to do like we do in user-config-zeroize-memset.h, something like

#define mbedtls_platform_zeroize(buf, len) RtlSecureZeroMemory(buf, len)

Also this part should be taken into account:

mbedtls/include/mbedtls/platform_util.h

Line 140 in 4122c16

#if !defined(MBEDTLS_TEST_DEFINES_ZEROIZE) //no-check-names

If mbedtls_platform_zeroize macro was defined, then this block either declares an undefined external symbol or redeclares the target cleaner - RtlSecureZeroMemory in this case.

and ensure the header needed for RtlSecureZeroMemory() is included everywhere it is needed

https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-rtlsecurezeromemory
Including Windows headers in random places and/or in wrong order leads to failed compilation.

[gilles-peskine-arm]

I'm labeling this [bug] with the objective of fixing the documentation. I want to make the platform interfaces consistent, but that's an API change which has to wait for a major version. Hopefully we'll do this in 4.0.

[irwir]

I'm labeling this [bug] with the objective of fixing the documentation.

Should the code be made at least working in more than a trivial test case? This might be beneficial even when the drastic future changes were applied.