Improve documentation of caveats - zeroize zeroes only "final" location of the struct

[ppershing]

Hi, While this crate is helpful, I fear that it might give off people false sense of security, especially for mid-level programmers who don't know exactly what they are doing. I believe the documentation should be more forthcoming about the limitations, especially about rust specifics of secure memory management.

In particular, what I want to point out is that managing memory secrets securely in rust is hard. Really hard. The main reason is move semantics - the compiler is allowed to move (i.e. memcpy) data around at its will. And this will inevitable happen unless the user specifically ensures the placement of the data on the heap from the start, but even then it is unclear how to actually fill the location with the secret without leaving traces of it somewhere.

So it would be really nice to document safe practices on actually how to use this crate without shooting yourself in the foot unknowingly.

[tarcieri]

Everything you've talked about is covered in the existing documentation, although there are some things that could be added.

In particular, what I want to point out is that managing memory secrets securely in rust is hard. Really hard.

The documentation says as much here: https://docs.rs/zeroize/latest/zeroize/#about

The main reason is move semantics - the compiler is allowed to move (i.e. memcpy) data around at its will.

This is covered here: https://docs.rs/zeroize/latest/zeroize/#stackheap-zeroing-notes

That list could probably be expanded to include stack spilling.

Unfortunately there's little more advice that can be offered except "don't do that". It notes Pin is one possible option, though a more comprehensive example of that might be in order.

At the end of the day zeroize is a low-level library which focuses entirely on zeroing memory rather than providing a comprehensive solution for secret management. The latter is provided better by secrecy, but really there's no way to provide anything high-assurance at the library level, at least in stable Rust

See also #659.

[ppershing]

Oh, my mistake - you are right, thanks for pointing out. My mistake - I did escalate this a bit too quickly without thoroughly reading the whole documentation to the end :facepalm: Still, it probably might be a good idea to include link to "guarantees" section early in the "about" section - right now the section reads as if the only problem that exists is making sure the zeroing is not optimized out by the compiler and the rust caveats are somehow hidden too deep into the documentation.

[newpavlov]

I think we can close this issue. We will be happy to receive documentation improvement PRs.

[tarcieri]

I've been meaning to rewrite the zeroize docs. Would like to get to this at some point (though happy to accept any PRs in the meantime)