From nobody Sun May 5 04:16:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) client-ip=66.175.222.108; envelope-from=bounce+27952+95952+1787277+3901457@groups.io; helo=mail02.groups.io; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+95952+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1667563342; cv=none; d=zohomail.com; s=zohoarc; b=QlWDs6tudzhN/IByQ6NPukOoXWJbSpWil4oLCfYz05JDMNCwHLglGwXHBbmM9C9DxD7nVF2x2bZKWrdUv0TxKAstr88n/Y4UPm5pjSh7LUiC8Yjlp75JOxXAwR/+nfIE2YtjwLhZ2ZTwiYuNRsnmNwAXmTcWBXUWU1BdGnLjjjQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1667563342; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Sender:Subject:To; bh=y2rrAK6iAw4Ps/pMdACO/xwfg+saSIXNiaIeJPvHGro=; b=c/b+3aJDeaAWqeGmpl6VvX4ZWil4lLJQDHHcZFOTEeysY+vIOG1aGr64qgGmDdtmcQR8P7oXEuzW7BjZTi91o/KatpjVZ5b7LKjepCWsX9x+McRNC1yitSVIuKsTDc8r4pL8zEOCpxWUSeu4I2gfqnl/7O9HDNhNL+P9lXStTnU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of groups.io designates 66.175.222.108 as permitted sender) smtp.mailfrom=bounce+27952+95952+1787277+3901457@groups.io; dmarc=fail header.from= (p=none dis=none) Received: from mail02.groups.io (mail02.groups.io [66.175.222.108]) by mx.zohomail.com with SMTPS id 1667563342583714.6153092132686; Fri, 4 Nov 2022 05:02:22 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id cUB1YY1788612xwFO5Yfl3Hc; Fri, 04 Nov 2022 05:02:22 -0700 X-Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.groups.io with SMTP id smtpd.web12.10181.1667563341477203305 for ; Fri, 04 Nov 2022 05:02:21 -0700 X-Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-57-sQoA5fx2NH20VnpsMErlPg-1; Fri, 04 Nov 2022 08:02:17 -0400 X-MC-Unique: sQoA5fx2NH20VnpsMErlPg-1 X-Received: from smtp.corp.redhat.com (int-mx09.intmail.prod.int.rdu2.redhat.com [10.11.54.9]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 0396A1C08987; Fri, 4 Nov 2022 12:02:17 +0000 (UTC) X-Received: from lacos-laptop-7.usersys.redhat.com (unknown [10.39.192.90]) by smtp.corp.redhat.com (Postfix) with ESMTP id 6124E4A9254; Fri, 4 Nov 2022 12:02:15 +0000 (UTC) From: "Laszlo Ersek" To: devel@edk2.groups.io, lersek@redhat.com Cc: Christopher Zurcher , Guomin Jiang , Jian J Wang , Jiewen Yao , Michael D Kinney , Xiaoyu Lu Subject: [edk2-devel] [PATCH v2] CryptoPkg/Readme.md: typo and grammar fixes Date: Fri, 4 Nov 2022 13:02:14 +0100 Message-Id: <20221104120214.12123-1-lersek@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.9 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Precedence: Bulk List-Unsubscribe: List-Subscribe: List-Help: Sender: devel@edk2.groups.io List-Id: Mailing-List: list devel@edk2.groups.io; contact devel+owner@edk2.groups.io Reply-To: devel@edk2.groups.io,lersek@redhat.com X-Gm-Message-State: ytsMub8CoVxvEQAGm0MmMzlux1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1667563342; bh=y2rrAK6iAw4Ps/pMdACO/xwfg+saSIXNiaIeJPvHGro=; h=Cc:Content-Type:Date:From:Reply-To:Subject:To; b=QR55aQEsj2YrjEHgh56tpDSU/2hmVatig6ia2WG9BzF/mp7+Qh1eY4KJ8jhYtIkIRaJ u9L/t9cmeb637zu2BI31iM2j0enpqqAoxcOxa5QMAE/x5BTyjh2w3IYiuDCVcNfYieaA6 4TnPvIuiaMHJXx0MljpjPcFiL02BHdJM74s= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1667563344076100003 Content-Type: text/plain; charset="utf-8"; x-default="true" Commit 244ce33bdd2f ("CryptoPkg: Add Readme.md", 2022-10-24) had added the long-awaited documentation on the dynamic crypto services. Fix some of the typos and arguable grammar errors in "Readme.md". A few light clarifications are also snuck in. Cc: Christopher Zurcher Cc: Guomin Jiang Cc: Jian J Wang Cc: Jiewen Yao Cc: Michael D Kinney Cc: Xiaoyu Lu Signed-off-by: Laszlo Ersek Acked-by: Jiewen Yao Reviewed-by: Christopher Zurcher Reviewed-by: Michael D Kinney --- Notes: v2: =20 - URL: https://pagure.io/lersek/edk2/c/8d7b26bfb6a1?branch=3Dcryptopkg_readm= e_typos_v2 =20 - v1 was at: - https://listman.redhat.com/archives/edk2-devel-archive/2022-Novembe= r/055153.html - msgid <20221102093637.9132-1-lersek@redhat.com> =20 - keep referring to the singular HashApiLib algorithm that PcdHashApiLibPolicy exposes for configuration in singular [Mike] =20 - still fix the duplicated "to" typo =20 - range-diff against v1 (i.e., first hunk dropped, second hunk updated): =20 > 1: a7269f170437 ! 1: 8d7b26bfb6a1 CryptoPkg/Readme.md: typo and gra= mmar fixes > @@ -94,18 +94,11 @@ > ``` > [LibraryClasses.common.DXE_RUNTIME_DRIVER] > @@ > - ### PCD Configuration Settings > - > - There are 2 PCD settings that are used to configure cryptograph= ic services. > --`PcdHashApiLibPolicy` is used to configure the hash algorithm p= rovided by the > -+`PcdHashApiLibPolicy` is used to configure the hash algorithms = provided by the > - BaseHashApiLib library instance. `PcdCryptoServiceFamilyEnable`= is used to > - configure the cryptographic services supported by the CryptoPei= , CryptoDxe, > and CryptoSmm modules. > > * `gEfiCryptoPkgTokenSpaceGuid.PcdHashApiLibPolicy` - This PCD = indicates the > - HASH algorithm to to use in the BaseHashApiLib to calculate h= ash of data. The > -+ HASH algorithms to use in the BaseHashApiLib to calculate has= h of data. The > ++ HASH algorithm to use in the BaseHashApiLib to calculate hash= of data. The > default hashing algorithm for BaseHashApiLib is set to HASH_A= LG_SHA256. > | Setting | Algorithm | > |------------|------------------| CryptoPkg/Readme.md | 46 ++++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/CryptoPkg/Readme.md b/CryptoPkg/Readme.md index 946aa1e99e7d..067465b8eb7d 100644 --- a/CryptoPkg/Readme.md +++ b/CryptoPkg/Readme.md @@ -39,7 +39,7 @@ provides the smallest overall firmware overhead. =20 ## Statically Linking Cryptographic Services =20 -The figure below shows an example of a firmware modules that requires the = use of +The figure below shows an example of a firmware module that requires the u= se of cryptographic services. The cryptographic services are provided by three l= ibrary classes called BaseCryptLib, TlsLib, and HashApiLib. These library classes= are implemented using APIs from the OpenSSL project that are abstracted by the @@ -49,7 +49,7 @@ full C runtime library for firmware components. Instead, = the CryptoPkg includes the smallest subset of services required to build the OpenSSL project in t= he private library class called IntrinsicLib. =20 -The CryptoPkg provides several instances if the BaseCryptLib and OpensslLi= b with +The CryptoPkg provides several instances of the BaseCryptLib and OpensslLi= b with different cryptographic service features and performance optimizations. The platform developer must select the correct instances based on cryptographic service requirements in each UEFI/PI firmware phase (SEC, PEI, DXE, UEFI, @@ -97,9 +97,9 @@ linking is not available for SEC or UEFI RT modules. =20 The EDK II modules/libraries that require cryptographic services use the s= ame BaseCryptLib/TlsLib/HashApiLib APIs. This means no source changes are requ= ired -to use static linking or dynamic linking. It is a platform configuration o= ptions -to select static linking or dynamic linking. This choice can be make globa= lly, -per firmware module type, or individual modules. +to use static linking or dynamic linking. It is a platform configuration o= ption +to select static linking or dynamic linking. This choice can be made globa= lly, +per firmware module type, or for individual modules. =20 ``` +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ +=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ +=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ @@ -159,7 +159,7 @@ The table below provides a summary of the supported cry= ptographic services. It indicates if the family or service is deprecated or recommended to not be = used. It also shows which *CryptLib library instances support the family or serv= ice. If a cell is blank then the service or family is always disabled and the -`PcdCryptoServiceFamilyEnable` settings for that family or service is igno= red. +`PcdCryptoServiceFamilyEnable` setting for that family or service is ignor= ed. If the cell is not blank, then the service or family is configurable using `PcdCryptoServiceFamilyEnable` as long as the correct OpensslLib or TlsLib= is also configured. @@ -234,10 +234,10 @@ phases (SEC, PEI, DXE, UEFI, SMM, UEFI RT). =20 The following table can be used to help select the best OpensslLib instanc= e for each phase. The Size column only shows the estimated size increase for a -compressed IA32/X64 modules that uses the cryptographic services with +compressed IA32/X64 module that uses the cryptographic services with `OpensslLib.inf` as the baseline size. The actual size increase depends on= the specific set of enabled cryptographic services. If ECC services are not -required, then size can be reduced by using OpensslLib.inf instead of +required, then the size can be reduced by using OpensslLib.inf instead of `OpensslLibFull.inf`. Performance optimization requires a size increase. =20 | OpensslLib Instance | SSL | ECC | Perf Opt | CPU Arch | Size | @@ -371,10 +371,10 @@ settings. =20 ### UEFI Runtime Driver Library Mappings =20 -UEFI Runtime Drivers only supports static linking of cryptographic service= s. -The following library mappings are recommended for UEFI Runtime Drivers. I= t uses -the runtime specific version of the BaseCryptLib and the null version of t= he -TlsLib because TLS services are not typically used in runtime. +UEFI Runtime Drivers only support static linking of cryptographic services. +The following library mappings are recommended for UEFI Runtime Drivers. T= hey +use the runtime specific version of the BaseCryptLib and the null version = of the +TlsLib because TLS services are not typically used at runtime. =20 ``` [LibraryClasses.common.DXE_RUNTIME_DRIVER] @@ -394,7 +394,7 @@ configure the cryptographic services supported by the C= ryptoPei, CryptoDxe, and CryptoSmm modules. =20 * `gEfiCryptoPkgTokenSpaceGuid.PcdHashApiLibPolicy` - This PCD indicates t= he - HASH algorithm to to use in the BaseHashApiLib to calculate hash of data= . The + HASH algorithm to use in the BaseHashApiLib to calculate hash of data. T= he default hashing algorithm for BaseHashApiLib is set to HASH_ALG_SHA256. | Setting | Algorithm | |------------|------------------| @@ -407,8 +407,8 @@ and CryptoSmm modules. * `gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable` - Enable/Disa= ble the families and individual services produced by the EDK II Crypto Protocols/PPIs. The default is all services disabled. This Structured P= CD is - associated with `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` structure that defin= ed in - `Include/Pcd/PcdCryptoServiceFamilyEnable.h`. + associated with the `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` structure that is + defined in `Include/Pcd/PcdCryptoServiceFamilyEnable.h`. =20 There are three layers of priority that determine if a specific family = or individual cryptographic service is actually enabled in the CryptoPei, @@ -420,15 +420,15 @@ and CryptoSmm modules. OpensslLib instance linked, then the service is always disabled. 2) BaseCryptLib instance selection. * CryptoPei is always linked with the PeiCryptLib instance of the - BaseCryptLib library class. The table above have a column for the + BaseCryptLib library class. The table above has a column for the PeiCryptLib. If the family or service is blank, then that family or service is always disabled. * CryptoDxe is always linked with the BaseCryptLib instance of the - BaseCryptLib library class. The table above have a column for the + BaseCryptLib library class. The table above has a column for the BaseCryptLib. If the family or service is blank, then that family = or service is always disabled. * CryptoSmm is always linked with the SmmCryptLib instance of the - BaseCryptLib library class. The table above have a column for the + BaseCryptLib library class. The table above has a column for the SmmCryptLib. If the family or service is blank, then that family or service is always disabled. 3) If a family or service is enabled in the OpensslLib instance and it = is @@ -438,11 +438,11 @@ and CryptoSmm modules. bit fields for each family of services. All of the families are disa= bled by default. An entire family of services can be enabled by setting t= he family field to the value `PCD_CRYPTO_SERVICE_ENABLE_FAMILY`. Indivi= dual - services can be enabled by setting a single service name to `TRUE`. - Settings listed later in the DSC file have priority over settings ea= rlier - in the DSC file, so it is legal for an entire family to be enabled f= irst - and then a few individual services disabled by setting the service n= ame to - `FALSE`. + services can be enabled by setting a single service name (bit) to `T= RUE`. + Settings listed later in the DSC file have priority over settings li= sted + earlier in the DSC file, so it is valid for an entire family to be e= nabled + first and then for a few individual services to be disabled by setti= ng + those service names to `FALSE`. =20 #### Common PEI PcdCryptoServiceFamilyEnable Settings =20 -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D- Groups.io Links: You receive all messages sent to this group. View/Reply Online (#95952): https://edk2.groups.io/g/devel/message/95952 Mute This Topic: https://groups.io/mt/94803700/1787277 Group Owner: devel+owner@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [importer@patchew.org] -=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-=3D-