From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1g9sy7-0001Fx-KB for mharc-grub-devel@gnu.org; Tue, 09 Oct 2018 10:26:39 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:44234) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g9sy6-0001FA-12 for grub-devel@gnu.org; Tue, 09 Oct 2018 10:26:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g9sy0-0007y4-Vp for grub-devel@gnu.org; Tue, 09 Oct 2018 10:26:37 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:49914) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g9sy0-0007w2-ME for grub-devel@gnu.org; Tue, 09 Oct 2018 10:26:32 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w99EO2hl143196; Tue, 9 Oct 2018 14:26:30 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=date : from : to : cc : subject : message-id : references : mime-version : content-type : in-reply-to; s=corp-2018-07-02; bh=Di7DI8hYQHiR0rNG/0gq8FzNtPvjf62PLQ2l1DJA4sk=; b=00M8LaUuQKUYxuZv2XiVqP7HcB0IZ9v8vNQxmG+1Qhbrj/VxluKyyBQAJkehpiOE4xgV r/AY/F3iFFoNWoVCG6V9caCdFlNtyLWMS0mfHR1UCbNX90ztaV4+LTV5FLUN+czZ2LST i9lt+TB8x5qnotXZVh/haqqEckuTRmMuKqJiPIamg9159bHOK1xFDjHCk63XX5AWK/fY 7PJNIJSA6Ow66qV3V766cnyhb5ltK4/9ygaQB7UG3W8GBea/jpqjl3q1zUyQSnqamT+G +LILfbvjLqjvv5OTb30UKE/UqbnVGiPsACSI489elRk+Oep3hua/USekFtDj326qZVyE 8g== Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by userp2120.oracle.com with ESMTP id 2mxnpqwj99-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 09 Oct 2018 14:26:30 +0000 Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0021.oracle.com (8.14.4/8.14.4) with ESMTP id w99EQRvZ016126 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 9 Oct 2018 14:26:27 GMT Received: from abhmp0013.oracle.com (abhmp0013.oracle.com [141.146.116.19]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id w99EQRSH027371; Tue, 9 Oct 2018 14:26:27 GMT Received: from olila.i.net-space.pl (/10.175.174.86) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 09 Oct 2018 14:26:26 +0000 Date: Tue, 9 Oct 2018 16:26:20 +0200 From: Daniel Kiper To: Ross Philipson Cc: grub-devel@gnu.org, dpsmith.dev@gmail.com, eric.snowberg@oracle.com, javierm@redhat.com, jonmccune@google.com, kanth.ghatraju@oracle.com, keng-yu.lin@hpe.com, konrad.wilk@oracle.com, leif.lindholm@linaro.org, mjg59@srcf.ucam.org, phcoder@gmail.com, philip.b.tricca@intel.com Subject: Re: [PATCH v3 6/8] verifiers: Add the documentation Message-ID: <20181009142620.GG4472@olila.i.net-space.pl> References: <1538559415-6233-1-git-send-email-daniel.kiper@oracle.com> <1538559415-6233-7-git-send-email-daniel.kiper@oracle.com> <2b2c77e5-2e1b-7c2e-3c36-cc6018e74a56@oracle.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <2b2c77e5-2e1b-7c2e-3c36-cc6018e74a56@oracle.com> User-Agent: Mutt/1.5.21 (2010-09-15) X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9040 signatures=668706 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1807170000 definitions=main-1810090142 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 156.151.31.85 X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 09 Oct 2018 14:26:39 -0000 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 > > > > Signed-off-by: Vladimir Serbinenko > > Signed-off-by: Daniel Kiper > > --- > > 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