[prev in list] [next in list] [prev in thread] [next in thread]
List: grub-devel
Subject: Re: [PATCH v3 6/8] verifiers: Add the documentation
From: Daniel Kiper <daniel.kiper () oracle ! com>
Date: 2018-10-09 14:26:20
Message-ID: 20181009142620.GG4472 () olila ! i ! net-space ! pl
[Download RAW message or body]
On Fri, Oct 05, 2018 at 12:43:08PM -0400, Ross Philipson wrote:
> On 10/03/2018 05:36 AM, Daniel Kiper wrote:
> > From: Vladimir Serbinenko <phcoder@gmail.com>
> >
> > Signed-off-by: Vladimir Serbinenko <phcoder@gmail.com>
> > Signed-off-by: Daniel Kiper <daniel.kiper@oracle.com>
> > ---
> > v3 - suggestions/fixes:
> > - improve the documentation.
> > ---
> > docs/grub-dev.texi | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> > 1 file changed, 57 insertions(+)
> >
> > diff --git a/docs/grub-dev.texi b/docs/grub-dev.texi
> > index a9f4de6..ad72705 100644
> > --- a/docs/grub-dev.texi
> > +++ b/docs/grub-dev.texi
> > @@ -84,6 +84,7 @@ This edition documents version @value{VERSION}.
> > * Video Subsystem::
> > * PFF2 Font File Format::
> > * Graphical Menu Software Design::
> > +* Verifiers framework::
> > * Copying This Manual:: Copying This Manual
> > * Index::
> > @end menu
> > @@ -1949,6 +1950,62 @@ the graphics mode that was in use before \
> > @code{grub_video_setup()} was called might fix some of the problems.
> >
> >
> > +@node Verifiers framework
> > +@chapter Verifiers framework
> > +
> > +To register your own verifier call @samp{grub_verifier_register} with a
> > +structure pointing to your functions.
> > +
> > +The interface is inspired by hash interface with \
> > @samp{init}/@samp{write}/@samp{fini}. +
> > +There are eesntially 2 ways of using it: hashing and whole-file verification:
>
> First : should be a ;
>
> > +
> > +With hashing approach:
> > +During @samp{init} you decide whether you want to check given file and init \
> > context. +In @samp{write} you update you hashing state.
>
> "update your..."
>
> > +In @samp{fini} you check that hash matches the expected value/passes some \
> > check/... +
> > +With whole-file verification:
> > +During @samp{init} you decide whether you want to check given file and init \
> > context. +In @samp{write} you verify file and return error if it fails.
> > +You don't have @samp{fini}.
> > +
> > +Additional @samp{verify_string} receives various strings like kernel parameters \
> > to +verify. Returning no error means successful verification and an error stops \
> > the current
>
> s/and/or maybe?
>
> > +action.
> > +
> > +Detailed description of API:
> > +
> > +Every time a file is opened your @samp{init} function is called with file \
> > descriptor +and file type. Your function can have following outcomes:
> > +
> > +@itemize
> > +
> > +@item returning no error and setting @samp{*flags} to \
> > @samp{GRUB_VERIFY_FLAGS_DEFER}. +In this case verification is deferred to others \
> > active verifiers. Verification fails if +nobody cares or selected verifier fails
> > +
> > +@item returning no error and setting @samp{*flags} to \
> > @samp{GRUB_VERIFY_FLAGS_SKIP_VERIFICATION}. +In this case your verifier will not \
> > be called anymore and your verifier is considered +to have skipped verification
> > +
> > +@item returning error. Then opening of the file will fail due to failed \
> > verification. +
> > +@item returning no error and not setting @samp{*flags} to \
> > @samp{GRUB_VERIFY_FLAGS_SKIP_VERIFICATION} +In this case verification is done as \
> > described in following section +
> > +@end itemize
> > +
> > +In the fourth case your @samp{write} will be called with chunks of file. If you \
> > need the whole file in a single +chunk then during @samp{init} set bit \
> > @samp{GRUB_VERIFY_FLAGS_SINGLE_CHUNK} in @samp{*flags}. +During @samp{init} you \
> > may set @samp{*context} if you need additional context. At every iteration you \
> > may return +an error and the the file will be considered as having failed the \
> > verification. If you return no error then +verification continues.
> > +
> > +Optionally at the end of the file @samp{fini} if it exists is called with just \
> > the context. If you return +no error during any of @samp{init}, @samp{write} and \
> > @samp{fini} then the file is considered as having +succeded verification.
>
> succeeded
>
> > +
> > @node Copying This Manual
> > @appendix Copying This Manual
> >
> >
>
> I noticed a lot of the text is missing articles, mainly "the" in a lot
> of places. Not sure if this was intentional to keep the text more
> abbreviated or not.
Ohhh... At least in my case it was not intentional. Well, from my POV,
as not native speaker, I do not care... :-))) Both things work for me.
I do not see the difference (my English teacher would kill me here).
Hence, it is difficult for me to use articles correctly (FYI I am
working on that). However, I am aware that this is very important for
native speakers. So, if you can add the missing stuff for me I will be
more than happy.
Daniel
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic