From patchwork Fri Jun 16 11:34:26 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stefan Herbrechtsmeier X-Patchwork-Id: 1795871 X-Patchwork-Delegate: xypron.glpk@gmx.de Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=weidmueller.onmicrosoft.com header.i=@weidmueller.onmicrosoft.com header.a=rsa-sha256 header.s=selector1-weidmueller-onmicrosoft-com header.b=E43TeIJl; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4QjHDN4q5qz20X8 for ; Fri, 16 Jun 2023 21:36:20 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id F27FE862AE; Fri, 16 Jun 2023 13:35:07 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=weidmueller.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=weidmueller.onmicrosoft.com header.i=@weidmueller.onmicrosoft.com header.b="E43TeIJl"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id DEB7D8624B; Fri, 16 Jun 2023 13:34:47 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-0.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FORGED_SPF_HELO,SPF_HELO_PASS,T_SCC_BODY_TEXT_LINE, T_SPF_PERMERROR autolearn=no autolearn_force=no version=3.4.2 Received: from EUR05-VI1-obe.outbound.protection.outlook.com (mail-vi1eur05on20608.outbound.protection.outlook.com [IPv6:2a01:111:f400:7d00::608]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 1FCA1847B6 for ; Fri, 16 Jun 2023 13:34:43 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=weidmueller.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=stefan.herbrechtsmeier-oss@weidmueller.com ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Xr/BQUjlNA0jI4bJERkOARiXQJLtaqB9Mx6Gq1yY4miHNyEF3KEJagCGdiah5L2w0xiijKbWPCwdiEew1+ZKcXSW7XP++MlO0voJ1cwBrLD7XHIVWq9AzJUdkys+CLkFR3vVgi4ZzgOtcVqI+9uRVa5myHCuoY/5WpeLXa6x8INQ20HvBrQn30Bn8Q60z8yk8qad1PVQID86fLqGgv/2eLYbej6puxRrCffRnTcTs8b9x9UUHL6JSWbEWj6pVJNhA94B4FkwJz79lrtWXxy8A5X5cKbXw7vWIRkogr8NXdTSP3q33cKFUeBjdTOg6+95ScNx5D2ZIxzByNDgT8Edlw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=4YWziZEgp27dWQ9kSAVSeEVPcb/h1WBPFX3JlScqCT0=; b=aHIKpbDNqldnFgFVfleJrsjiFj4EA/r06fex7CaihM+OijGXGG3OJCKU8oZEomNrElMnjwdqH+yUWyJwoNRXJpAu6JGKqeVNmB46OKccXn4Kb/gnhVPUNn7FpjEStBJHP6sgrD8knCdxBRSbnpn50kxMqLPx/SN/pbEfJfQfSAMtrfyG7E9zj8affahh5vsb0/Pq/qZMMmEAIamvU7A2U/hzLEC7vY+hmht4HMQkzGeEbXdsHGPpK9XvCZVHPXMg90JGy4hCb+pnL3joZyklcTMV5vsVnZxcQYMeCUAnua2bHjsWbGRez65PuO9X5GLFdHcXyxwLltdFKQc5CKawRA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=weidmueller.com; dmarc=pass action=none header.from=weidmueller.com; dkim=pass header.d=weidmueller.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=weidmueller.onmicrosoft.com; s=selector1-weidmueller-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=4YWziZEgp27dWQ9kSAVSeEVPcb/h1WBPFX3JlScqCT0=; b=E43TeIJl3rGQNMT0ycJe/P6R7MnSVbPTwXe/xGgENr/1sHu2nBGxsq5z+JajI1/Xf4x0gj16eOkbzJjlZxBhBycVa5p+gJl6PRizciK2+R9jWy2Nw1Rpmq0P/8QN0BwVYMeHBW0tQMX5KgC7FgNCivJk0bwZEmMocZM6bnoilsE= Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=weidmueller.com; Received: from PAXPR08MB6969.eurprd08.prod.outlook.com (2603:10a6:102:1d8::23) by DB9PR08MB6444.eurprd08.prod.outlook.com (2603:10a6:10:23c::11) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6500.29; Fri, 16 Jun 2023 11:34:42 +0000 Received: from PAXPR08MB6969.eurprd08.prod.outlook.com ([fe80::7501:6f07:8ffe:f389]) by PAXPR08MB6969.eurprd08.prod.outlook.com ([fe80::7501:6f07:8ffe:f389%4]) with mapi id 15.20.6500.025; Fri, 16 Jun 2023 11:34:42 +0000 From: Stefan Herbrechtsmeier To: u-boot@lists.denx.de Cc: Malte Schmidt , Sughosh Ganu , Malte Schmidt , Stefan Herbrechtsmeier , Heinrich Schuchardt , Ilias Apalodimas Subject: [PATCH 5/5] doc: uefi: clarify capsule concept Date: Fri, 16 Jun 2023 13:34:26 +0200 Message-Id: <20230616113426.13976-6-stefan.herbrechtsmeier-oss@weidmueller.com> X-Mailer: git-send-email 2.30.2 In-Reply-To: <20230616113426.13976-1-stefan.herbrechtsmeier-oss@weidmueller.com> References: <20230616113426.13976-1-stefan.herbrechtsmeier-oss@weidmueller.com> X-ClientProxiedBy: FR2P281CA0174.DEUP281.PROD.OUTLOOK.COM (2603:10a6:d10:9f::11) To PAXPR08MB6969.eurprd08.prod.outlook.com (2603:10a6:102:1d8::23) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: PAXPR08MB6969:EE_|DB9PR08MB6444:EE_ X-MS-Office365-Filtering-Correlation-Id: 7d53a65c-d55b-40aa-644b-08db6e5dad17 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: 7r8Jr076zkb9Q4uuISRnlxqa8g5YQZZJVpkfo3SyEoPbcDbPB2CxTSyzcuqHPEq0akhCi7Y2594q9ts2iYMkLqHcUmimckbDiwuFDbisLgB5Z/SrAe2nG6MEhPmpTWFdUEaK6LdDNCxWWSX94cGaX76cmPUtOR9SHNm0LKrTV9ZAqufLiN7igpXPmwixJhH7NEg3NXsiep+ZMZx5+Bqrz7cjDCCZPie8tpwgLUDUILjTay4kvx8AaUJRxF35m5zpJJLxRQ92A6t6qiSgeyVVJbkA9H/b14vtSArk3VfqQJEtJ2zUCuwwPRDlHFjGkEnfVkklQIy6z5o59qRp5V/4zE494uEot8jsZieDKKIuUH8dyLcBfBQxZ1rItMzXsDlibYUwAxiYpBP4Tvk2kixOZWBsS24sGQRxUbomMhmbMcG1qeiPxHMm1y/+CIe7aPbxd+LRh3pt2x3j0/UzR9BQJqvmiCDphX98rkgWJyS5OddtOFJ/V/Clwyc/SH5KRiWC5VJyWavAiy7e+bNCMPndu+wex1Yzogqqu7bsSKHmdouobKjeZGVhoIV+/5RslclNS1gfR7qPcW5F5CwLXac2Cw6kZChJGFTrNK3MjX8GZ28= X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:PAXPR08MB6969.eurprd08.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230028)(4636009)(136003)(346002)(366004)(39860400002)(376002)(396003)(451199021)(5660300002)(54906003)(41300700001)(6486002)(8676002)(8936002)(316002)(6666004)(966005)(52116002)(186003)(6506007)(26005)(6512007)(478600001)(4326008)(6916009)(66556008)(66476007)(66946007)(86362001)(1076003)(38100700002)(38350700002)(2616005)(83380400001)(36756003)(2906002); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: CKezpDLfzd1dwXnQu4mvHXsv0yzLIIriv7nswBd37o8Br+GpxIqghuVovznn7cA8npTcoUMrP3PITlc1qs7Z9EAMuXjjwhNdL7J/JPme9sH40cQOpNoks4VGj/g4BehWgjenr9XmRQ+c6aVWugK4dbBqnTw63BLYE6Vk5cv2eDoQvBmeOmRtteQ15rqU2SHHU0DCOaboQQlrag6euZ4fLozTRe3EqT7sqZQP8EhMkpoATAKiNPUUsbs61sEBodniTe0tC4P7DZR/LULmtDLv0VKtdudcX/t4EPQQ/bFsCG9DFkQk2Oa85zmojIhr3rFHG5XnlG7J+4OTmGToXhg/NlehGK2eelpTPZqCefgNuMNQ4mTbvQ5baRVxwHIjMg5d2KfPtFfS+pmTpOGT/md8XqOUAywSkhZDIvPrzvR7cIvAbRMjl+6F1f0N3T+eyF8cO9fw+DQVHeDZSa1kfLDtpY/oYPSAkFbRbbFMZwjocEC/XacGBnJPIHyDo9O6Ri7hJuG3lsbNzN3med5g66t2jKI2+Nq45y8iD1ak08AWvgxOa9OLfIRYczUlC303CAvUMoLIKXIFkQgYFBT3rBTSUI1QHJB7/B9KdtZKSvQ1REAwRZc0IQH1tklEk8rMNK410AvSvs/E5CUnT7vt55/PWgoNfB1Z6SoRtqrSkLjdbAPcWV2dMvxutiB1rrSV0Pt+W+8oZ6RUemQrL+UvG20I1K1fzT1TtqazJmuRSe10NC1Pw2n/MfEtZw9ORH09gjGMRldFGKYENAV+9drH6EBHSMKAOdcGu5IBzpTlqzykFyun+LS3TD9EQQJbRXVbENvwLbUdim7ZSwNcV04l34mcD77eKNh7AhAhCoYi+JQ6UQMEqF0IaA7A2kGlk8eTqjj+Ph3Vb5n4JWktfwcyHIO5gotLsvIAwQX0VxO/y2Qlg14xKANQlenIIRGUGsXwTnAgidUGianDg7OHH+Ly9TXgyAAGY+hPWpWQ9evHBTQ883EuZCxe4TEfDiLnjDiFwm3/gGuDUdtzeD6UhmMRuACV4h/fVpENhxebsNfxiCmhv3DwwUsD//ZGsPkBHZNw8BmmtixLngojuPRh3IRSp+P51m1uOyIP+H9O6Yt/ObQB9vesrG499yda+y84WwTT8mLmnVC+ULbcXfpjVL+p4MA3dgvd+nap5NWiCVUaOEFwewyGoxc84a/MokN7ehXZRCJRQR7lflxS7JsNlYa7EZTMqw+i9UMp4xb46xcYKBV+hNzxng/a+Wgfrb7qrmx/kpDQSF7H9CDrshT99M7WpJimloG3JvMOXlBnvwD2/NrkzHJ1EnmlhWqLoTaTp9VNZpwTs++4wfdh0CKDPnyHQtC5Iuv4MbboMXbH+euZRJh7CMXMEfTnUjhk2Kfi27KpHaqRbjPhw85Qduygj0n+vE015n5hSlzT3Hq/OE0KkBmUCSBX8jFRsnHkgZ60sX82pXHMmzaffUYWW5P/WLHrY+dBCbdUoBLTazd/zEWqMB5RWwkagJWUIzs9JR6GuhBr00NtX+BDWFO+uVoyWRJhHYzJ9sw6/McY39kC3ktvkDKKdE7HeamsZHjZ8kvwXy8RmJwW4hNn7TvuQ7R275TG03FcUg== X-OriginatorOrg: weidmueller.com X-MS-Exchange-CrossTenant-Network-Message-Id: 7d53a65c-d55b-40aa-644b-08db6e5dad17 X-MS-Exchange-CrossTenant-AuthSource: PAXPR08MB6969.eurprd08.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 16 Jun 2023 11:34:41.9836 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: e4289438-1c5f-4c95-a51a-ee553b8b18ec X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: ZABUiOFyOB2KsuHazm9DbHajWRNPnVR2ORjYnoZ3rDbXyUDAxkVujWBwIUV9nGs3dBwvA4/LbuVBh0mHqH4oRA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB9PR08MB6444 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.8 at phobos.denx.de X-Virus-Status: Clean From: Malte Schmidt There seems to be some misused or inaccurate namings regarding the capsule concept. Set the naming straight and add a table showing the naming conventions. This table is based on the images found in chapter 23 of the UEFI 2.10 specifications [1]. The table should help to build a common understanding between the authors and readers of the documentation. [1] https://uefi.org/specs/UEFI/2.10/index.html Signed-off-by: Malte Schmidt Signed-off-by: Stefan Herbrechtsmeier --- doc/develop/uefi/uefi.rst | 42 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index b513934d31..56188c5b10 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -300,6 +300,42 @@ not present are ignored when determining the active boot option. Please note that capsules will be applied in the alphabetic order of capsule file names. +Structure of a capsule file +*************************** + +The strucutre of a firmware management capsule as defined in [1] is shown +below. The tools/mkeficapsule program supports creating firmware management +capsules with multiple payloads and optionally with firmware image +authentication. + +.. code-block:: text + + +-------------------------------------------------------------------------+ + | EFI_CAPSULE_HEADER | + +--------------+----------------------------------------------------------+ + | Capsule Body | EFI_FIRMWARE_MANAGEMENT_CAPSULE_HEADER | + | +----------------------------------------------------------+ + | | Optional Driver 1 | + | +----------------------------------------------------------+ + | | Optional Driver 2 | + | +----------------------------------------------------------+ + | | ... | + | +-----------+----------------------------------------------+ + | | Payload 1 | EFI_FIRMWARE_MANAGEMENT_CAPSULE_IMAGE_HEADER | + | | +----------------------------------------------+ + | | | Firmware Image Authentication (optional) | + | | +----------------------------------------------+ + | | | Dependency Expression (optional) | + | | +----------------------------------------------+ + | | | Firmware Image | + | +-----------+----------------------------------------------+ + | | Payload 2 | + | +----------------------------------------------------------+ + | | ... | + | +----------------------------------------------------------+ + | | Payload n | + +--------------+----------------------------------------------------------+ + Creating a capsule file *********************** @@ -482,9 +518,9 @@ following command can be issued Enabling Capsule Authentication ******************************* -The UEFI specification defines a way of authenticating the capsule to -be updated by verifying the capsule signature. The capsule signature -is computed and prepended to the capsule payload at the time of +The UEFI specification defines a way of authenticating the capsule payload +to be updated by verifying the signature of each capsule payload. The payload +signature is computed and prepended to the capsule payload at the time of capsule generation. This signature is then verified by using the public key stored as part of the X509 certificate. This certificate is in the form of an efi signature list (esl) file, which is embedded in