From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1g7dbC-0003V2-A5 for mharc-grub-devel@gnu.org; Wed, 03 Oct 2018 05:37:42 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:54396) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g7db6-0003Rt-Ty for grub-devel@gnu.org; Wed, 03 Oct 2018 05:37:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g7db2-0007vC-Km for grub-devel@gnu.org; Wed, 03 Oct 2018 05:37:36 -0400 Received: from userp2130.oracle.com ([156.151.31.86]:37298) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g7db2-0007rH-97 for grub-devel@gnu.org; Wed, 03 Oct 2018 05:37:32 -0400 Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w939SxAr011369; Wed, 3 Oct 2018 09:37:30 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : cc : subject : date : message-id : in-reply-to : references; s=corp-2018-07-02; bh=Qwm0nShKhwYhG26cLPNb9Kx+sUryQ935Z1DvM2uBXVg=; b=Ums6NUkHb+NfU72tTs6895qbYH5mPfQfdAKVa7XmL+drmq0iAKhC+C6srrKTqdxpXcvW fI8J8ZTV+VdR9j4CHZ7gr+H/FpY+mIcRs968FiwLFsJdb/r5ONIZe7j1Y1X8AI4Q4CGy f0/MheFOWMOJS7aI1UtZyPcr3xGq/W9kvHSD4icmtsQav3b5uAG4mTQy7gF0TWlNtYGp agYq9bN/2xfXalwKVM377mA4CbCrHKdWBezfd28FACPcSot6cq+Dt595S+BwT7DZuOIg sOhJWTZPVUbMpdv0tidBJZ6suolDyKBjkm6Jl+RzJvRPsUvEWCV/y0xbVRpkgy7QQRjQ 7w== Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp2130.oracle.com with ESMTP id 2mt0tttrv0-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 03 Oct 2018 09:37:30 +0000 Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w939bTvZ018808 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Wed, 3 Oct 2018 09:37:29 GMT Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w939bTCb032226; Wed, 3 Oct 2018 09:37:29 GMT Received: from olila.i.net-space.pl (/10.175.216.132) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Wed, 03 Oct 2018 09:37:28 +0000 From: Daniel Kiper To: grub-devel@gnu.org Cc: 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, ross.philipson@oracle.com Subject: [PATCH v3 6/8] verifiers: Add the documentation Date: Wed, 3 Oct 2018 11:36:53 +0200 Message-Id: <1538559415-6233-7-git-send-email-daniel.kiper@oracle.com> X-Mailer: git-send-email 1.7.10.4 In-Reply-To: <1538559415-6233-1-git-send-email-daniel.kiper@oracle.com> References: <1538559415-6233-1-git-send-email-daniel.kiper@oracle.com> X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=9034 signatures=668707 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 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-1810030096 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 156.151.31.86 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: Wed, 03 Oct 2018 09:37:38 -0000 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: + +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. +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 +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. + @node Copying This Manual @appendix Copying This Manual -- 1.7.10.4