Use of `black_box` is not recommended for security uses

[AaronFeickert]

The library currently uses core::hint::black_box as a fallback optimization barrier when needed for architecture support. However, its documentation specifically recommends against its use for cryptographic or security-focused use cases.

It may be useful to add documentation warning against this for architectures that would use it.

[cesarb]

As explained in the large comment within the fallback implementation, black_box is not used alone as the optimization barrier; it also uses #[inline(never)] for that function. Unfortunately, that's the best we can do without some sort of assembly (either inline assembly, or separately compiled assembly files) or help from the compiler. The alternative that was used before black_box was made stable (using a volatile read trick) is also not guaranteed to block optimizations.

I'll think about adding a warning to the crate's module-level documentation.

[AaronFeickert]

Fair enough. I would certainly recommend more documentation about the nature of the optimization barriers used, so users can make a more informed decision based on use cases.