Received: from list by lists.gnu.org with archive (Exim 4.90_1) id 1lyVmT-0000pG-BT for mharc-grub-devel@gnu.org; Wed, 30 Jun 2021 04:41:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:53798) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lyVmR-0000kv-Sw for grub-devel@gnu.org; Wed, 30 Jun 2021 04:41:11 -0400 Received: from mail-pf1-x434.google.com ([2607:f8b0:4864:20::434]:39655) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lyVmO-0003ik-Sg for grub-devel@gnu.org; Wed, 30 Jun 2021 04:41:11 -0400 Received: by mail-pf1-x434.google.com with SMTP id b12so641903pfv.6 for ; Wed, 30 Jun 2021 01:41:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=axtens.net; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=9SxfKe8q27cp4NzsJGMoqhHcBHU0oeDFHux40AKtqdc=; b=UFig1L3470ooZ6C/dYsJrE5j2jw5VCe6r5HU9A5RaF7w6MYLcHskKe+XYNicjd+D6b hreogkJXaE/BWYw1wVQ+7D6ALSlr5bVrftuwK1VoTHC37A1pyiY1mAlWy0R4tKmQWAhg aJBhxH65hDQf90Bo5qPIvHxfaPsAt1+fp5mI0= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=9SxfKe8q27cp4NzsJGMoqhHcBHU0oeDFHux40AKtqdc=; b=fDFPR1RiCaX3ljOD9BiqnqDpvsIkQ5i6GdgpKAbPTwki7cS9JbOt41f6j8veQRwfao Gjtin93GfSRB19XhpK3nIymkDJX6u3UMLiDFfdeJ8f5HA5EVYPFGwgc5b11LNxYyettr P7pWekwo6UMhO4qEslyWPqDB6i+hPGehZEbLFs5NLJYx91vIng7G3u9gXsc4agJLzJpw Jx4qe9PriF/PyXrpLmnA+BKrPRnx/JMIxH6nt0BKP5cw/TNqPJFKHlbpRxlqqNiWwZyv ebTNgxCLQUbIXQDVeIFSn1YAFXvWFucaNedAuKRzwNb14E+Gi4gKjlYrKStOMX8WvF7w oNbA== X-Gm-Message-State: AOAM531rF9yOdlqECNYyi62c+MHwPjB7LXgi2YIPCh50R8QXOwChCi3B 4ow/GDQ4m7rwHv5riHKZRbB0TrfEdDrCPw== X-Google-Smtp-Source: ABdhPJym5Aj5Jo6X9bgd4JBUA+JGgTxeggjHRNxCO1R7weyc/vfeTu9MtX7ytxugv47o8MpgWzKx4A== X-Received: by 2002:a05:6a00:1348:b029:30f:201d:6b76 with SMTP id k8-20020a056a001348b029030f201d6b76mr5029932pfu.55.1625042467407; Wed, 30 Jun 2021 01:41:07 -0700 (PDT) Received: from localhost ([203.206.29.204]) by smtp.gmail.com with ESMTPSA id u24sm21388196pfm.200.2021.06.30.01.41.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 30 Jun 2021 01:41:07 -0700 (PDT) From: Daniel Axtens To: grub-devel@gnu.org Cc: rashmica.g@gmail.com, alastair@d-silva.org, nayna@linux.ibm.com, Daniel Axtens Subject: [PATCH v2 06/22] docs/grub: Document signing grub with an appended signature Date: Wed, 30 Jun 2021 18:40:15 +1000 Message-Id: <20210630084031.2663622-7-dja@axtens.net> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20210630084031.2663622-1-dja@axtens.net> References: <20210630084031.2663622-1-dja@axtens.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=2607:f8b0:4864:20::434; envelope-from=dja@axtens.net; helo=mail-pf1-x434.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, 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.23 Precedence: list List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 30 Jun 2021 08:41:12 -0000 Signing grub for firmware that verifies an appended signature is a bit fiddly. I don't want people to have to figure it out from scratch so document it here. Signed-off-by: Daniel Axtens --- docs/grub.texi | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/grub.texi b/docs/grub.texi index 2ffc3b417312..bed565371460 100644 --- a/docs/grub.texi +++ b/docs/grub.texi @@ -6055,6 +6055,48 @@ image works under UEFI secure boot and can maintain the secure-boot chain. It will also be necessary to enrol the public key used into a relevant firmware key database. +@section Signing GRUB with an appended signature + +The @file{core.img} itself can be signed with a Linux kernel module-style +appended signature. + +To support IEEE1275 platforms where the boot image is often loaded directly +from a disk partition rather than from a file system, the @file{core.img} +can specify the size and location of the appended signature with an ELF +note added by @command{grub-install}. + +An image can be signed this way using the @command{sign-file} command from +the Linux kernel: + +@example +@group +# grub.key is your private key and certificate.der is your public key + +# Determine the size of the appended signature. It depends on the signing +# certificate and the hash algorithm +touch empty +sign-file SHA256 grub.key certificate.der empty empty.sig +SIG_SIZE=`stat -c '%s' empty.sig` +rm empty empty.sig + +# Build a grub image with $SIG_SIZE reserved for the signature +grub-install --appended-signature-size $SIG_SIZE --modules="..." ... + +# Replace the reserved size with a signature: +# cut off the last $SIG_SIZE bytes with truncate's minus modifier +truncate -s -$SIG_SIZE /boot/grub/powerpc-ieee1275/core.elf core.elf.unsigned +# sign the trimmed file with an appended signature, restoring the correct size +sign-file SHA256 grub.key certificate.der core.elf.unsigned core.elf.signed + +# Don't forget to install the signed image as required +# (e.g. on powerpc-ieee1275, to the PReP partition) +@end group +@end example + +As with UEFI secure boot, it is necessary to build in the required modules, +or sign them separately. + + @node Platform limitations @chapter Platform limitations -- 2.30.2