On Tue, Jun 13, 2023 at 9:22 PM Eric Biggers <ebiggers@xxxxxxxxxx> wrote: > > On Tue, Jun 13, 2023 at 12:34:10PM +0300, Amir Goldstein wrote: > > > > > > In general the proposed documentation reads like the audience is overlayfs > > > developers. > > > > I never considered that overlayfs.rst is for an audience other than > > overlayfs developers or people that want to become overlayfs > > developers. It is not a user guide. If it were, it would have been a > > very bad one. > > > > > It doesn't describe the motivation for the feature or how to use it > > > in each of the two use cases. Maybe that is intended, but it's not what I had > > > expected to see. > > > > > > > Yeh, that's a valid point. > > That is what I wanted to know - what exactly is missing. > > I guess this is the documented motivation: > > Sure, but even if the document is just for kernel developers, it should still > describe motivation and use cases, as those are important for userstanding. > > > "This may then be used to verify the content of the source file at the time > > the file is opened" > > > > but it does not tell a complete chain of trust story. > > > > How about something along the lines of: > > > > "In the case that the upper layer can be trusted not to be tampered > > with while overlayfs is offline > > So *online* tampering of the upper layer is fine? No, for the sake of this section, it would be easier to say that upper is completely trusted and completely under our control and that the feature only hardens overlayfs when lower is not under our full control. In the case of composefs it's actually two lower layers, one trusted and one not trusted (and an optional trusted upper), but it does not matter IMO for the sake of explaining the basic feature. > > > and some of the lower layers cannot > > be trusted not to be tampered with, the "verity" feature can protect > > against offline modification to lower files > > Data of lower files, not simply "lower files", right? Right. > > Are *online* modifications to lower files indeed not in scope? They are. doc should not mention online. > > If the feature "can protect", then under what circumstances does it protect, and > under what circumstances what does it not protect? > > It would also be helpful to explain what specifically is meant by "protect". > Does it mean that overlayfs prevents modifications to lower file data, or does > it mean that overlayfs detects modifications to lower file data after they > happen? If the latter, what happens when overlayfs detects a modification? > What do userspace programs experience? > > > , whose metadata has been > > copied up to the upper layer (a.k.a "metacopy" files) ...." > > > > It's generic language that what the patches do, regardless of the > > trust model of composefs and how it composes an overlayfs layers. > > It's better, but it could use some more detail. See my comments above. > Fair enough. Alex, Please incorporate Eric's feedback above to come up with a more detailed description than: +This can be useful as a way to validate that a lower directory matches +the correct upper when it is re-mounted later. In case you can +guarantee that a overlayfs directory with verity xattrs is not +tampered with (for example using dm-verity or fs-verity) this can even +be used to guarantee the validity of an untrusted lower directory. + On the specific points that Eric mentioned. Thanks, Amir.
