On 10/09/2018 10:26 AM, Daniel Kiper wrote:
> 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 <phco...@gmail.com>
>>>
>>> Signed-off-by: Vladimir Serbinenko <phco...@gmail.com>
>>> Signed-off-by: Daniel Kiper <daniel.ki...@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.
Understood. I will reply to the original patch with my suggested
corrections since this reply chain is getting ugly.
Thanks
>
> Daniel
>
_______________________________________________
Grub-devel mailing list
Grub-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/grub-devel
