Re: [PATCH v3 6/8] verifiers: Add the documentation

[Ross Philipson]

On 10/03/2018 05:36 AM, Daniel Kiper wrote:
> From: Vladimir Serbinenko <address@hidden>
> 
> Signed-off-by: Vladimir Serbinenko <address@hidden>
> Signed-off-by: Daniel Kiper <address@hidden>
> ---
> 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.
>  
>  
> address@hidden Verifiers framework
> address@hidden 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}.

"... by the hash ..."

> +> +There are eesntially 2 ways of using it: hashing and whole-file
verification:

eesntially -> essentially

The first : could be replaced with a , or ; depending on your mood :)

> +
> +With hashing approach:

"With the hashing approach:"

> +During @samp{init} you decide whether you want to check given file and init 
> context.

"... check the given ..."

> +In @samp{write} you update you hashing state.

"you hashing" -> "your hasking"

> +In @samp{fini} you check that hash matches the expected value/passes some 
> check/...

"... that the hash ..."

> +
> +With whole-file verification:
> +During @samp{init} you decide whether you want to check given file and init 
> context.

"... check the given ..."

> +In @samp{write} you verify file and return error if it fails.

"... verify the file and return an error ..."

> +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
> +action.
> +
> +Detailed description of API:

"... of the API ..."

> +
> +Every time a file is opened your @samp{init} function is called with file 
> descriptor

"... a file descriptor..."

> +and file type. Your function can have following outcomes:

"... have the following ..."

> +
> address@hidden
> +
> address@hidden 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

others -> other

> +nobody cares or selected verifier fails
> +
> address@hidden 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

considered -> assumed

> +to have skipped verification
> +
> address@hidden returning error. Then opening of the file will fail due to 
> failed verification.
> +
> address@hidden 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

"... in the following ..."

> +
> address@hidden itemize
> +
> +In the fourth case your @samp{write} will be called with chunks of file. If 
> you need the whole file in a single

"... of the file ..."

> +chunk then during @samp{init} set bit @samp{GRUB_VERIFY_FLAGS_SINGLE_CHUNK} 
> in @samp{*flags}.

"... set the bit..."

> +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

You may need some commas around "if it exists" but I am not 100% sure
what is intended here.

> +no error during any of @samp{init}, @samp{write} and @samp{fini} then the 
> file is considered as having
> +succeded verification.
> +
>  @node Copying This Manual
>  @appendix Copying This Manual
>  
> 

Just my suggestions. Since the original text went back and forth between
complete grammar and abbreviated grammar, it is probably best to make it
all consistent.

Thanks
Ross