Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id AF3D7C83F1A for ; Thu, 17 Jul 2025 17:22:05 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ucSHv-0006xd-Q3; Thu, 17 Jul 2025 13:20:55 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucPg9-0007rc-Jg for grub-devel@gnu.org; Thu, 17 Jul 2025 10:33:46 -0400 Received: from mx0b-001b2d01.pphosted.com ([148.163.158.5]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ucPg5-0005AV-BH for grub-devel@gnu.org; Thu, 17 Jul 2025 10:33:44 -0400 Received: from pps.filterd (m0353725.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.18.1.2/8.18.1.2) with ESMTP id 56HCWHaF009460; Thu, 17 Jul 2025 14:33:37 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ibm.com; h=cc :content-type:date:from:in-reply-to:message-id:mime-version :references:subject:to; s=pp1; bh=Whh63d9XWgDp3a4BoftTYTXuU7HVfE o1s6A28Tlch7s=; b=JHqXRXQedyI+74Y301Qtr0jNnTAxf1YqmpyYo2sn8k+eNd FwEtKjwrss4p6RM+OHSZRqEQvo0Cucf/Xh3c7u1JFjpt1F6N4O3zvcb04oKna6L/ FMv0P4ciT9dk+V/BdE4aY5GZW/JUbncXXDScddB/NNg5cijsRGfC9mDeag5DvOQ6 BWXkytduOJIgJrFe3X6SpCAa9KaMmqaHzJOcTTHH6xR9/BQwWE/LHP4CIoqvCZ2F QRzzcpFo1nzzC1mRNINbj9tRB1MxJdxL7HuUa5qjcGOc5so32JgYi0Q4NBXHCMxW KXnlHAfaOStygeXTkugq1fm0lwfTpi6RJTK0otzw== Received: from ppma12.dal12v.mail.ibm.com (dc.9e.1632.ip4.static.sl-reverse.com [50.22.158.220]) by mx0a-001b2d01.pphosted.com (PPS) with ESMTPS id 47ue4ube4x-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 17 Jul 2025 14:33:37 +0000 (GMT) Received: from pps.filterd (ppma12.dal12v.mail.ibm.com [127.0.0.1]) by ppma12.dal12v.mail.ibm.com (8.18.1.2/8.18.1.2) with ESMTP id 56HCA1E1031922; Thu, 17 Jul 2025 14:33:36 GMT Received: from smtprelay05.fra02v.mail.ibm.com ([9.218.2.225]) by ppma12.dal12v.mail.ibm.com (PPS) with ESMTPS id 47v21ucvp5-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 17 Jul 2025 14:33:35 +0000 Received: from smtpav01.fra02v.mail.ibm.com (smtpav01.fra02v.mail.ibm.com [10.20.54.100]) by smtprelay05.fra02v.mail.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id 56HEXW7x49217878 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 17 Jul 2025 14:33:32 GMT Received: from smtpav01.fra02v.mail.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 1E11B20040; Thu, 17 Jul 2025 14:33:32 +0000 (GMT) Received: from smtpav01.fra02v.mail.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 66F202004D; Thu, 17 Jul 2025 14:33:29 +0000 (GMT) Received: from smtpclient.apple (unknown [9.124.219.199]) by smtpav01.fra02v.mail.ibm.com (Postfix) with ESMTPS; Thu, 17 Jul 2025 14:33:29 +0000 (GMT) From: Sudhakar Kuppusamy Message-Id: Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3826.600.51.1.1\)) Subject: Re: [PATCH v5 13/21] appended signatures: Documentation Date: Thu, 17 Jul 2025 20:03:17 +0530 In-Reply-To: <20250716110611.2aqhoqbahz5avdia@tomti.i.net-space.pl> Cc: grub-devel@gnu.org, dja@axtens.net, jan.setjeeilers@oracle.com, julian.klode@canonical.com, mate.kukri@canonical.com, pjones@redhat.com, msuchanek@suse.com, mlewando@redhat.com, stefanb@linux.ibm.com, avnish@linux.ibm.com, nayna@linux.ibm.com, ssrish@linux.ibm.com To: Daniel Kiper References: <20250714173513.68324-1-sudhakar@linux.ibm.com> <20250714173513.68324-14-sudhakar@linux.ibm.com> <20250716110611.2aqhoqbahz5avdia@tomti.i.net-space.pl> X-Mailer: Apple Mail (2.3826.600.51.1.1) X-TM-AS-GCONF: 00 X-Authority-Analysis: v=2.4 cv=baBrUPPB c=1 sm=1 tr=0 ts=687909c1 cx=c_pps a=bLidbwmWQ0KltjZqbj+ezA==:117 a=bLidbwmWQ0KltjZqbj+ezA==:17 a=Wb1JkmetP80A:10 a=JuTF4qcAAAAA:8 a=VnNF1IyMAAAA:8 a=FuI4j-Ue4yoSatSrAJgA:9 a=QEXdDO2ut3YA:10 a=vNjDyzCvDDF4bOKAcggA:9 a=ngQ3yKAwOva-Gumv:21 a=_W_S_7VecoQA:10 a=WlT8qwTXB_Kj6um4hl3b:22 X-Proofpoint-GUID: 6GPnVvncaCnVsh7WZy9BufY7JCyVLdCb X-Proofpoint-Spam-Details-Enc: AW1haW4tMjUwNzE3MDEyNiBTYWx0ZWRfX+lZL9br3uHAi rqTFJzXX8sK/1+Ci3RhegMaCv+mZXC4/+HqE5st51gA7eIYwHAU4vkE6KZSrXoLluuOVmdbfdwE w8/aXX6lQFxjtT9ohA72nwL8L0Gqu9z7vj2R/AD8TTr8bLrJiojr1Aefi8UhaknfGI9AJlRyx5q kwWT//IFlUszs2tTnmQJz+KBz+dyFM+t8GkD9mIscCxhnl4ysvoVQjJNzgwyaDNOCI3qGTM3zyc ZFWBdqAdXGpSCCw5G7nUIRKBuwKQW0PkxicUcwunfpPR50mcWu4nviOiP7GQtljl9Ai1L0SgCjQ 6F2PNs63xzLLFNI/hmEefYvwb05g/SREvvckq5aM6sHhCV+BKHDM8k3IigW9rINxChieBrQJutf ic/RCh7LS7Nygu9DSLbRLB/6kZWwWLZRtkxn123vOybOAer6nSAosbnomeBTt9zvxxe+d4Kl X-Proofpoint-ORIG-GUID: 6GPnVvncaCnVsh7WZy9BufY7JCyVLdCb X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1099,Hydra:6.1.9,FMLib:17.12.80.40 definitions=2025-07-17_01,2025-07-17_02,2025-03-28_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 bulkscore=0 mlxlogscore=999 suspectscore=0 adultscore=0 impostorscore=0 phishscore=0 lowpriorityscore=0 priorityscore=1501 clxscore=1015 mlxscore=0 malwarescore=0 spamscore=0 classifier=spam authscore=0 authtc=n/a authcc= route=outbound adjust=0 reason=mlx scancount=1 engine=8.19.0-2505280000 definitions=main-2507170126 Received-SPF: pass client-ip=148.163.158.5; envelope-from=sudhakar@linux.ibm.com; helo=mx0b-001b2d01.pphosted.com X-Spam_score_int: -26 X-Spam_score: -2.7 X-Spam_bar: -- X-Spam_report: (-2.7 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: The development of GNU GRUB Content-Type: multipart/mixed; boundary="===============4278415708614248674==" Errors-To: grub-devel-bounces+grub-devel=archiver.kernel.org@gnu.org Sender: grub-devel-bounces+grub-devel=archiver.kernel.org@gnu.org --===============4278415708614248674== Content-Type: multipart/alternative; boundary="Apple-Mail=_CC230926-9E85-4717-90E1-26280B2ADF1B" --Apple-Mail=_CC230926-9E85-4717-90E1-26280B2ADF1B Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=utf-8 > On 16 Jul 2025, at 4:36=E2=80=AFPM, Daniel Kiper = wrote: >=20 > On Mon, Jul 14, 2025 at 11:05:05PM +0530, Sudhakar Kuppusamy wrote: >> From: Daniel Axtens >>=20 >> This explains how appended signatures can be used to form part of >> a secure boot chain, and documents the commands and variables >> introduced. >>=20 >> Signed-off-by: Daniel Axtens >> Signed-off-by: Sudhakar Kuppusamy >> Reviewed-by: Stefan Berger >> Reviewed-by: Avnish Chouhan >> --- >> docs/grub.texi | 189 = +++++++++++++++++++++++++++++++++++++++++++------ >> 1 file changed, 168 insertions(+), 21 deletions(-) >>=20 >> diff --git a/docs/grub.texi b/docs/grub.texi >> index d594e29bd..494e2eada 100644 >> --- a/docs/grub.texi >> +++ b/docs/grub.texi >> @@ -3281,6 +3281,7 @@ These variables have special meaning to GRUB. >>=20 >> @menu >> * biosnum:: >> +* check_appended_signatures:: >> * check_signatures:: >> * chosen:: >> * cmdpath:: >> @@ -3343,12 +3344,16 @@ this. >> For an alternative approach which also changes BIOS drive mappings = for the >> chain-loaded system, @pxref{drivemap}. >>=20 >> +@node check_appended_signatures >> +@subsection check_appended_signatures >> +This variable controls whether GRUB enforces appended signature = validation on >> +loaded vmlinux file. @xref{Using appended signatures}. >>=20 >> @node check_signatures >> @subsection check_signatures >>=20 >> -This variable controls whether GRUB enforces digital signature >> -validation on loaded files. @xref{Using digital signatures}. >> +This variable controls whether GRUB enforces GPG-style digital = signature >> +validation on loaded files. @xref{Using GPG-style digital = signatures}. >>=20 >> @node chosen >> @subsection chosen >> @@ -6414,6 +6419,10 @@ you forget a command, you can run the command = @command{help} >> @menu >> * [:: Check file types and compare values >> * acpi:: Load ACPI tables >> +* append_add_db_cert:: Add an X.509 certificate to the db = list >> +* append_list_db:: List trusted certificates from the = db list >> +* append_rm_dbx_cert:: Remove a certificate from the db = list >> +* append_verify:: Verify appended digital signature = using db list >> * authenticate:: Check whether user is in user list >> * background_color:: Set background color for active = terminal >> * background_image:: Load background image for active = terminal >> @@ -6535,6 +6544,68 @@ Note: The command is not allowed when lockdown = is enforced (@pxref{Lockdown}). >> unsigned code. >> @end deffn >>=20 >> +@node append_add_db_cert >> +@subsection append_add_db_cert >> + >> +@deffn Command append_add_db_cert X509_certificate >> +Read a DER-formatted X.509 certificate from the file = @var{X509_certificate} >> +and add it to GRUB's internal db list of trusted X.509 certificates. = These >> +certificates are used to validate appended signatures when the = environment >> +variable @code{check_appended_signatures} is set to @code{enforce}. >> + >> +Note that if @code{check_appended_signatures} is set to = @code{enforce} >> +when @command{append_add_db_cert} is executed, then = @var{X509_certificate} >> +must itself bear an appended signature. (It is not sufficient that >> +@var{X509_certificate} be signed by a trusted certificate according = to the >> +X.509 rules: GRUB does not include support for validating signatures = within X.509 >> +certificates themselves.) >> + >> +See @xref{Using appended signatures} for more information. >> +@end deffn >> + >> +@node append_list_db >> +@subsection append_list_db >> + >> +@deffn Command append_list_db >> +List all X.509 certificates trusted by GRUB for validating appended = signatures. >> +The output is a numbered list of certificates, showing the = certificate's serial >> +number and Common Name. >> + >> +The certificate number can be used as an argument to >> +@command{append_rm_dbx_cert} (@pxref{append_rm_dbx_cert}). >> + >> +See @xref{Using appended signatures} for more information. >> +@end deffn >> + >> +@node append_rm_dbx_cert >> +@subsection append_rm_dbx_cert >> + >> +@deffn Command append_rm_dbx_cert cert_number >> +Remove the X.509 certificate numbered @var{cert_number} from GRUB's = keyring of >> +db for verifying appended signatures. >> + >> +@var{cert_number} is the certificate number as listed by >> +@command{append_list_db} (@pxref{append_list_db}). >> + >> +These certificates are used to validate appended signatures when = environment >> +variable @code{check_appended_signatures} is set to @code{enforce} >> +(@pxref{check_appended_signatures}), and by @command{append_verify} >> +(@pxref{append_verify}). See @xref{Using appended signatures} for = more >> +information. >> +@end deffn >> + >> +@node append_verify >> +@subsection append_verify >> + >> +@deffn Command append_verify file >=20 > I suggest to use "<>" to mark arguments which gets a value, e.g.: = append_verify > Please fix this in whole documentation=E2=80=A6 Will do it. >=20 >> +Verifies an appended signature on @var{file} against the trusted = X.509 certificates >=20 > s/file/ Will do it. >=20 >> +known to GRUB (See @pxref{append_list_db}, = @pxref{append_add_db_cert}, and >> +@pxref{append_rm_dbx_cert}). >> +Exit code @code{$?} is set to 0 if the signature validates >> +successfully. If validation fails, it is set to a non-zero value. >> + >> +See @xref{Using appended signatures}, for more information. >> +@end deffn >>=20 >> @node authenticate >> @subsection authenticate >> @@ -6854,7 +6925,7 @@ These keys are used to validate signatures when = environment variable >> @code{check_signatures} is set to @code{enforce} >> (@pxref{check_signatures}), and by some invocations of >> @command{verify_detached} (@pxref{verify_detached}). @xref{Using >> -digital signatures}, for more information. >> +GPG-style digital signatures}, for more information. >> @end deffn >>=20 >> @node drivemap >> @@ -7250,7 +7321,6 @@ without any options, the @command{keystatus} = command returns true if and >> only if checking key modifier status is supported. >> @end deffn >>=20 >> - >> @node list_env >> @subsection list_env >>=20 >> @@ -7270,7 +7340,7 @@ The output is in GPG's v4 key fingerprint = format (i.e., the output of >> @code{gpg --fingerprint}). The least significant four bytes (last >> eight hexadecimal digits) can be used as an argument to >> @command{distrust} (@pxref{distrust}). >> -@xref{Using digital signatures}, for more information about uses for >> +@xref{Using GPG-style digital signatures}, for more information = about uses for >> these keys. >> @end deffn >>=20 >> @@ -7305,8 +7375,11 @@ When used with care, @option{--skip-sig} and = the whitelist enable an >> administrator to configure a system to boot only signed >> configurations, but to allow the user to select from among multiple >> configurations, and to enable ``one-shot'' boot attempts and >> -``savedefault'' behavior. @xref{Using digital signatures}, for more >> +``savedefault'' behavior. @xref{Using GPG-style digital = signatures}, for more >> information. >> +Extra care should be taken when combining this command with appended = signatures >> +(@pxref{Using appended signatures}), as this file is not validated = by an >> +appended signature and could set = @code{check_appended_signatures=3Dno}. >> @end deffn >>=20 >>=20 >> @@ -7677,7 +7750,7 @@ read. It is possible to modify a digitally = signed environment block >> file from within GRUB using this command, such that its signature = will >> no longer be valid on subsequent boots. Care should be taken in such >> advanced configurations to avoid rendering the system >> -unbootable. @xref{Using digital signatures}, for more information. >> +unbootable. @xref{Using GPG-style digital signatures}, for more = information. >=20 > I suggest to move all GPG documentation changes to separate patch. Will do it. >=20 >> @end deffn >>=20 >>=20 >> @@ -8167,11 +8240,10 @@ signatures when environment variable = @code{check_signatures} is set to >> must itself be properly signed. The @option{--skip-sig} option can = be >> used to disable signature-checking when reading @var{pubkey_file} >> itself. It is expected that @option{--skip-sig} is useful for testing >> -and manual booting. @xref{Using digital signatures}, for more >> +and manual booting. @xref{Using GPG-style digital signatures}, for = more >=20 > Ditto and below... >=20 >> information. >> @end deffn >>=20 >> - >=20 > This and similar cleanups can be a part of GPG change set but they = have > to be mentioned in the commit message. Will do it. >=20 >> @node unset >> @subsection unset >>=20 >> @@ -8190,7 +8262,6 @@ only on PC BIOS platforms. >> @end deffn >> @end ignore >>=20 >> - >=20 > Ditto... >=20 >> @node verify_detached >> @subsection verify_detached >>=20 >> @@ -8208,7 +8279,7 @@ tried. >>=20 >> Exit code @code{$?} is set to 0 if the signature validates >> successfully. If validation fails, it is set to a non-zero value. >> -@xref{Using digital signatures}, for more information. >> +@xref{Using GPG-style digital signatures}, for more information. >> @end deffn >>=20 >> @node videoinfo >> @@ -8668,14 +8739,15 @@ environment variables and commands are listed = in the same order. >> @chapter Security >>=20 >> @menu >> -* Authentication and authorisation:: Users and access control >> -* Using digital signatures:: Booting digitally signed code >> -* UEFI secure boot and shim:: Booting digitally signed PE = files >> -* Secure Boot Advanced Targeting:: Embedded information for = generation number based revocation >> -* Measured Boot:: Measuring boot components >> -* Lockdown:: Lockdown when booting on a = secure setup >> -* TPM2 key protector:: Managing disk key with TPM2 key = protector >> -* Signing GRUB itself:: Ensuring the integrity of the = GRUB core image >> +* Authentication and authorisation:: Users and access control >> +* Using GPG-style digital signatures:: Booting digitally signed code >> +* Using appended signatures:: An alternative approach to = booting digitally signed code >> +* UEFI secure boot and shim:: Booting digitally signed PE = files >> +* Secure Boot Advanced Targeting:: Embedded information for = generation number based revocation >> +* Measured Boot:: Measuring boot components >> +* Lockdown:: Lockdown when booting on a = secure setup >> +* TPM2 key protector:: Managing disk key with TPM2 = key protector >> +* Signing GRUB itself:: Ensuring the integrity of the = GRUB core image >> @end menu >>=20 >> @node Authentication and authorisation >> @@ -8751,8 +8823,8 @@ generating configuration files with = authentication. You can use >> adding @kbd{set superusers=3D} and @kbd{password} or = @kbd{password_pbkdf2} >> commands. >>=20 >> -@node Using digital signatures >> -@section Using digital signatures in GRUB >> +@node Using GPG-style digital signatures >> +@section Using GPG-style digital signatures in GRUB >>=20 >> GRUB's @file{core.img} can optionally provide enforcement that all = files >> subsequently read from disk are covered by a valid digital signature. >> @@ -8835,6 +8907,81 @@ or BIOS) configuration to cause the machine to = boot from a different >> (attacker-controlled) device. GRUB is at best only one link in a >> secure boot chain. >>=20 >> +@node Using appended signatures >> +@section Using appended signatures in GRUB >> + >> +GRUB supports verifying Linux-style 'appended signatures' for secure = boot. >> +Appended signatures are PKCS#7 messages containing a signature over = the >> +contents of a file, plus some metadata, appended to the end of a = file. A file >> +with an appended signature ends with the magic string: >> + >> +@example >> +~Module signature appended~\n >> +@end example >> + >> +where @code{\n} represents the line feed character, @code{0x0a}. >> + >> +To enable appended signature verification, load the appendedsig = module and an >> +x509 certificate for verification. Building the appendedsig module = into the >> +core grub image is recommended. >=20 > s/grub/GRUB/=E2=80=A6 Will do it. >=20 >> +Certificates can be managed at boot time using the = @pxref{append_add_db_cert}, >> +@pxref{append_rm_dbx_cert} and @pxref{append_list_db} commands. >> +Certificates can also be built in to the core image using the = @code{--x509} >> +parameter to @command{grub-install} or @command{grub-mkimage}. >> +A file can be explicitly verified using the @pxref{append_verify} = command. >> + >> +Only signatures made with the SHA-256 or SHA-512 hash algorithm are = supported, >> +and only RSA signatures are supported. >> + >> +A file can be signed with the @command{sign-file} utility supplied = with the >> +Linux kernel source. For example, if you have @code{signing.key} as = the private >> +key and @code{certificate.der} as the x509 certificate containing = the public key: >> + >> +@example >> +sign-file SHA256 signing.key certificate.der vmlinux vmlinux.signed >> +@end example >> + >> +Enforcement of signature verification is controlled by the >> +@code{check_appended_signatures} variable. Verification will only = take place >> +when files are loaded if the variable is set to @code{enforce}. If a >> +certificate is built into the grub core image with the @code{--x509} = parameter, >> +the variable will be automatically set to @code{enforce} when the = appendedsig >> +module is loaded. >> + >> +Unlike GPG-style signatures, not all files loaded by GRUB are = required to be >> +signed. Once verification is turned on, the following file types = must carry >> +appended signatures: >> + >> +@enumerate >> +@item Linux, Multiboot, BSD, XNU and Plan9 kernels >> +@item Grub modules, except those built in to the core image >=20 > s/Grub/GRUB/=E2=80=A6 Will do it. >=20 >> +@item Any new certificate files to be trusted >> +@end enumerate >> + >> +ACPI tables and Device Tree images will not be checked for appended = signatures >> +but must be verified by another mechanism such as GPG-style = signatures before >> +they will be loaded. >> + >> +No attempt is made to validate any other file type. In particular, >> +chain-loaded binaries are not verified - if your platform supports >> +chain-loading and this cannot be disabled, consider an alternative = secure >> +boot mechanism. >> + >> +As with GPG-style appended signatures, signature checking does = @strong{not} >> +stop an attacker with console access from dropping manually to the = GRUB >> +console and executing: >> + >> +@example >> +set check_appended_signatures=3Dno >> +@end example >> + >> +Refer to the section on password-protecting GRUB = (@pxref{Authentication >> +and authorisation}) for more information on preventing this. >> + >> +Additionally, special care must be taken around the = @command{loadenv} command, >> +which can be used to turn off @code{check_appended_signature}. >> + >> @node UEFI secure boot and shim >> @section UEFI secure boot and shim support >=20 > May I ask you to put all documentation patches in one group at the end > of the patch set? Same applies to tests patches. I think they should = land > before documentation patches=E2=80=A6 Will do it. Thank you Daniel. Thanks, Sudhakar >=20 > Daniel --Apple-Mail=_CC230926-9E85-4717-90E1-26280B2ADF1B Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=utf-8

On 16 Jul 2025, at 4:36=E2=80=AFPM, Daniel Kiper = <dkiper@net-space.pl> wrote:

On Mon, Jul 14, 2025 at = 11:05:05PM +0530, Sudhakar Kuppusamy wrote:
From: Daniel Axtens = <dja@axtens.net>

This explains how appended signatures can = be used to form part of
a secure boot chain, and documents the = commands and variables
introduced.

Signed-off-by: Daniel = Axtens <dja@axtens.net>
Signed-off-by: Sudhakar Kuppusamy = <sudhakar@linux.ibm.com>
Reviewed-by: Stefan Berger = <stefanb@linux.ibm.com>
Reviewed-by: Avnish Chouhan = <avnish@linux.ibm.com>
---
docs/grub.texi | 189 = +++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 168 = insertions(+), 21 deletions(-)

diff --git a/docs/grub.texi = b/docs/grub.texi
index d594e29bd..494e2eada 100644
--- = a/docs/grub.texi
+++ b/docs/grub.texi
@@ -3281,6 +3281,7 @@ These = variables have special meaning to GRUB.

@menu
* = biosnum::
+* check_appended_signatures::
* check_signatures::
* = chosen::
* cmdpath::
@@ -3343,12 +3344,16 @@ this.
For an = alternative approach which also changes BIOS drive mappings for = the
chain-loaded system, @pxref{drivemap}.

+@node = check_appended_signatures
+@subsection = check_appended_signatures
+This variable controls whether GRUB = enforces appended signature validation on
+loaded vmlinux file. = @xref{Using appended signatures}.

@node = check_signatures
@subsection check_signatures

-This variable = controls whether GRUB enforces digital signature
-validation on = loaded files. @xref{Using digital signatures}.
+This variable = controls whether GRUB enforces GPG-style digital = signature
+validation on loaded files. @xref{Using GPG-style digital = signatures}.

@node chosen
@subsection chosen
@@ -6414,6 = +6419,10 @@ you forget a command, you can run the command = @command{help}
@menu
* [:: =             &n= bsp;           &nbs= p; Check file types and compare values
* acpi:: =             &n= bsp;          Load = ACPI tables
+* append_add_db_cert:: =          Add an X.509 = certificate to the db list
+* append_list_db:: =             &n= bsp;List trusted certificates from the db list
+* = append_rm_dbx_cert:: =          Remove a = certificate from the db list
+* append_verify:: =             &n= bsp; Verify appended digital signature using db list
* = authenticate:: =             &n= bsp;  Check whether user is in user list
* = background_color:: =            Set = background color for active terminal
* background_image:: =            Load = background image for active terminal
@@ -6535,6 +6544,68 @@ Note: The = command is not allowed when lockdown is enforced = (@pxref{Lockdown}).
      unsigned = code.
@end deffn

+@node append_add_db_cert
+@subsection = append_add_db_cert
+
+@deffn Command append_add_db_cert = X509_certificate
+Read a DER-formatted X.509 certificate from the = file @var{X509_certificate}
+and add it to GRUB's internal db list of = trusted X.509 certificates. These
+certificates are used to validate = appended signatures when the environment
+variable = @code{check_appended_signatures} is set to @code{enforce}.
+
+Note = that if @code{check_appended_signatures} is set to = @code{enforce}
+when @command{append_add_db_cert} is executed, then = @var{X509_certificate}
+must itself bear an appended signature. (It = is not sufficient that
+@var{X509_certificate} be signed by a trusted = certificate according to the
+X.509 rules: GRUB does not include = support for validating signatures within X.509
+certificates = themselves.)
+
+See @xref{Using appended signatures} for more = information.
+@end deffn
+
+@node = append_list_db
+@subsection append_list_db
+
+@deffn Command = append_list_db
+List all X.509 certificates trusted by GRUB for = validating appended signatures.
+The output is a numbered list of = certificates, showing the certificate's serial
+number and Common = Name.
+
+The certificate number can be used as an argument = to
+@command{append_rm_dbx_cert} = (@pxref{append_rm_dbx_cert}).
+
+See @xref{Using appended = signatures} for more information.
+@end deffn
+
+@node = append_rm_dbx_cert
+@subsection append_rm_dbx_cert
+
+@deffn = Command append_rm_dbx_cert cert_number
+Remove the X.509 certificate = numbered @var{cert_number} from GRUB's keyring of
+db for verifying = appended signatures.
+
+@var{cert_number} is the certificate = number as listed by
+@command{append_list_db} = (@pxref{append_list_db}).
+
+These certificates are used to = validate appended signatures when environment
+variable = @code{check_appended_signatures} is set to = @code{enforce}
+(@pxref{check_appended_signatures}), and by = @command{append_verify}
+(@pxref{append_verify}). See @xref{Using = appended signatures} for more
+information.
+@end = deffn
+
+@node append_verify
+@subsection = append_verify
+
+@deffn Command append_verify = file

I = suggest to use "<>" to mark arguments which gets a value, e.g.: = append_verify <file>
Please = fix this in whole documentation=E2=80=A6
Will = do it.

+Verifies an appended signature on @var{file} = against the trusted X.509 certificates

s/file/<file>
Will do it.

+known to GRUB (See @pxref{append_list_db}, = @pxref{append_add_db_cert}, = and
+@pxref{append_rm_dbx_cert}).
+Exit code @code{$?} is set to 0 = if the signature validates
+successfully.  If validation fails, = it is set to a non-zero value.
+
+See @xref{Using appended = signatures}, for more information.
+@end deffn

@node = authenticate
@subsection authenticate
@@ -6854,7 +6925,7 @@ These = keys are used to validate signatures when environment = variable
@code{check_signatures} is set to = @code{enforce}
(@pxref{check_signatures}), and by some invocations = of
@command{verify_detached} (@pxref{verify_detached}). =  @xref{Using
-digital signatures}, for more = information.
+GPG-style digital signatures}, for more = information.
@end deffn

@node drivemap
@@ -7250,7 +7321,6 = @@ without any options, the @command{keystatus} command returns true if = and
only if checking key modifier status is supported.
@end = deffn

-
@node list_env
@subsection list_env

@@ = -7270,7 +7340,7 @@ The output is in GPG's v4 key fingerprint format = (i.e., the output of
@code{gpg --fingerprint}).  The least = significant four bytes (last
eight hexadecimal digits) can be used as = an argument to
@command{distrust} (@pxref{distrust}).
-@xref{Using = digital signatures}, for more information about uses for
+@xref{Using = GPG-style digital signatures}, for more information about uses = for
these keys.
@end deffn

@@ -7305,8 +7375,11 @@ When used = with care, @option{--skip-sig} and the whitelist enable = an
administrator to configure a system to boot only = signed
configurations, but to allow the user to select from among = multiple
configurations, and to enable ``one-shot'' boot attempts = and
-``savedefault'' behavior.  @xref{Using digital signatures}, = for more
+``savedefault'' behavior.  @xref{Using GPG-style = digital signatures}, for more
information.
+Extra care should be = taken when combining this command with appended = signatures
+(@pxref{Using appended signatures}), as this file is not = validated by an
+appended signature and could set = @code{check_appended_signatures=3Dno}.
@end deffn


@@ = -7677,7 +7750,7 @@ read.  It is possible to modify a digitally = signed environment block
file from within GRUB using this command, = such that its signature will
no longer be valid on subsequent boots. =  Care should be taken in such
advanced configurations to avoid = rendering the system
-unbootable. @xref{Using digital signatures}, = for more information.
+unbootable. @xref{Using GPG-style digital = signatures}, for more information.

I suggest to move all = GPG documentation changes to separate patch.
Will do it.

@end deffn


@@ -8167,11 +8240,10 @@ = signatures when environment variable @code{check_signatures} is set = to
must itself be properly signed.  The @option{--skip-sig} = option can be
used to disable signature-checking when reading = @var{pubkey_file}
itself. It is expected that @option{--skip-sig} is = useful for testing
-and manual booting. @xref{Using digital = signatures}, for more
+and manual booting. @xref{Using GPG-style = digital signatures}, for more

Ditto = and below...

information.
@end = deffn

-

This = and similar cleanups can be a part of GPG change set but they = have
to be mentioned in the = commit message.
Will do it.

@node unset
@subsection unset

@@ = -8190,7 +8262,6 @@ only on PC BIOS platforms.
@end deffn
@end = ignore

-

Ditto...

@node verify_detached
@subsection = verify_detached

@@ -8208,7 +8279,7 @@ tried.

Exit code = @code{$?} is set to 0 if the signature validates
successfully. =  If validation fails, it is set to a non-zero = value.
-@xref{Using digital signatures}, for more = information.
+@xref{Using GPG-style digital signatures}, for more = information.
@end deffn

@node videoinfo
@@ -8668,14 = +8739,15 @@ environment variables and commands are listed in the same = order.
@chapter Security

@menu
-* Authentication and = authorisation:: Users and access control
-* Using digital = signatures::         Booting = digitally signed code
-* UEFI secure boot and shim:: =        Booting digitally signed PE = files
-* Secure Boot Advanced Targeting::   Embedded = information for generation number based revocation
-* Measured Boot:: =             &n= bsp;      Measuring boot components
-* = Lockdown:: =             &n= bsp;           Lock= down when booting on a secure setup
-* TPM2 key protector:: =             &n= bsp; Managing disk key with TPM2 key protector
-* Signing GRUB = itself:: =             &n= bsp;Ensuring the integrity of the GRUB core image
+* Authentication = and authorisation::   Users and access control
+* Using = GPG-style digital signatures:: Booting digitally signed code
+* Using = appended signatures:: =          An alternative = approach to booting digitally signed code
+* UEFI secure boot and = shim::          Booting = digitally signed PE files
+* Secure Boot Advanced Targeting:: =     Embedded information for generation number based = revocation
+* Measured Boot:: =             &n= bsp;        Measuring boot = components
+* Lockdown:: =             &n= bsp;           &nbs= p; Lockdown when booting on a secure setup
+* TPM2 key = protector:: =             &n= bsp;   Managing disk key with TPM2 key protector
+* = Signing GRUB itself:: =             &n= bsp;  Ensuring the integrity of the GRUB core image
@end = menu

@node Authentication and authorisation
@@ -8751,8 +8823,8 = @@ generating configuration files with authentication.  You can = use
adding @kbd{set superusers=3D} and @kbd{password} or = @kbd{password_pbkdf2}
commands.

-@node Using digital = signatures
-@section Using digital signatures in GRUB
+@node Using = GPG-style digital signatures
+@section Using GPG-style digital = signatures in GRUB

GRUB's @file{core.img} can optionally provide = enforcement that all files
subsequently read from disk are covered by = a valid digital signature.
@@ -8835,6 +8907,81 @@ or BIOS) = configuration to cause the machine to boot from a = different
(attacker-controlled) device.  GRUB is at best only = one link in a
secure boot chain.

+@node Using appended = signatures
+@section Using appended signatures in GRUB
+
+GRUB = supports verifying Linux-style 'appended signatures' for secure = boot.
+Appended signatures are PKCS#7 messages containing a signature = over the
+contents of a file, plus some metadata, appended to the end = of a file. A file
+with an appended signature ends with the magic = string:
+
+@example
+~Module signature appended~\n
+@end = example
+
+where @code{\n} represents the line feed character, = @code{0x0a}.
+
+To enable appended signature verification, load = the appendedsig module and an
+x509 certificate for verification. = Building the appendedsig module into the
+core grub image is = recommended.

s/grub/GRUB/=E2=80=A6
Will do = it.

+Certificates can be managed at boot time using = the @pxref{append_add_db_cert},
+@pxref{append_rm_dbx_cert} and = @pxref{append_list_db} commands.
+Certificates can also be built in = to the core image using the @code{--x509}
+parameter to = @command{grub-install} or @command{grub-mkimage}.
+A file can be = explicitly verified using the @pxref{append_verify} = command.
+
+Only signatures made with the SHA-256 or SHA-512 hash = algorithm are supported,
+and only RSA signatures are = supported.
+
+A file can be signed with the @command{sign-file} = utility supplied with the
+Linux kernel source. For example, if you = have @code{signing.key} as the private
+key and = @code{certificate.der} as the x509 certificate containing the public = key:
+
+@example
+sign-file SHA256 signing.key certificate.der = vmlinux vmlinux.signed
+@end example
+
+Enforcement of = signature verification is controlled by = the
+@code{check_appended_signatures} variable. Verification will = only take place
+when files are loaded if the variable is set to = @code{enforce}. If a
+certificate is built into the grub core image = with the @code{--x509} parameter,
+the variable will be automatically = set to @code{enforce} when the appendedsig
+module is = loaded.
+
+Unlike GPG-style signatures, not all files loaded by = GRUB are required to be
+signed. Once verification is turned on, the = following file types must carry
+appended = signatures:
+
+@enumerate
+@item Linux, Multiboot, BSD, XNU and = Plan9 kernels
+@item Grub modules, except those built in to the core = image

s/Grub/GRUB/=E2=80=A6
Will do = it.

+@item Any new certificate files to be = trusted
+@end enumerate
+
+ACPI tables and Device Tree images = will not be checked for appended signatures
+but must be verified by = another mechanism such as GPG-style signatures before
+they will be = loaded.
+
+No attempt is made to validate any other file type. In = particular,
+chain-loaded binaries are not verified - if your = platform supports
+chain-loading and this cannot be disabled, = consider an alternative secure
+boot mechanism.
+
+As with = GPG-style appended signatures, signature checking does = @strong{not}
+stop an attacker with console access from dropping = manually to the GRUB
+console and = executing:
+
+@example
+set = check_appended_signatures=3Dno
+@end example
+
+Refer to the = section on password-protecting GRUB (@pxref{Authentication
+and = authorisation}) for more information on preventing = this.
+
+Additionally, special care must be taken around the = @command{loadenv} command,
+which can be used to turn off = @code{check_appended_signature}.
+
@node UEFI secure boot and = shim
@section UEFI secure boot and shim support

May I ask you to put all = documentation patches in one group at the end
of the patch set? Same = applies to tests patches. I think they should land
before documentation = patches=E2=80=A6
Will do = it.

Thank you = Daniel.

Thanks,
Sudhakar

Daniel

= --Apple-Mail=_CC230926-9E85-4717-90E1-26280B2ADF1B-- --===============4278415708614248674== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: inline X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KR3J1Yi1kZXZl bCBtYWlsaW5nIGxpc3QKR3J1Yi1kZXZlbEBnbnUub3JnCmh0dHBzOi8vbGlzdHMuZ251Lm9yZy9t YWlsbWFuL2xpc3RpbmZvL2dydWItZGV2ZWwK --===============4278415708614248674==--