From mboxrd@z Thu Jan 1 00:00:00 1970 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.web08.1730.1667815759875039598 for ; Mon, 07 Nov 2022 02:09:20 -0800 Authentication-Results: mx.groups.io; dkim=pass header.i=@redhat.com header.s=mimecast20190719 header.b=R4gb9Tqc; spf=pass (domain: redhat.com, ip: 170.10.129.124, mailfrom: lersek@redhat.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1667815758; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3yz0yBafV/37jy4XUtld036JVL9CNgFmqQwH5+ijuXU=; b=R4gb9TqcznuzWCm73S6ntkS2oSY10XSNgsyOtr75asizhF0GHTuYhPbOjLYOLI3a6n5Gi6 /j5DB3DnX6hfs/K9EHIeMIirUPrGPP0SBIgBXCzMnEYAYOfEdNM2gaJSFIGOBB/jPcOhCw dotJ33nvLqlhMwoum1hIdAAI75pEKAs= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-113-39xAmb_VNwu6VgccXp6A_Q-1; Mon, 07 Nov 2022 05:09:15 -0500 X-MC-Unique: 39xAmb_VNwu6VgccXp6A_Q-1 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 00A54811E7A; Mon, 7 Nov 2022 10:09:15 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (unknown [10.39.193.82]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 270A440C2064; Mon, 7 Nov 2022 10:09:12 +0000 (UTC) Subject: Re: [PATCH v2] CryptoPkg/Readme.md: typo and grammar fixes To: "Yao, Jiewen" , "Kinney, Michael D" , "devel@edk2.groups.io" Cc: "Zurcher, Christopher" , "Jiang, Guomin" , "Wang, Jian J" , "Lu, Xiaoyu1" References: <20221104120214.12123-1-lersek@redhat.com> From: "Laszlo Ersek" Message-ID: <9765a129-659f-1dc4-043c-60af24b6600b@redhat.com> Date: Mon, 7 Nov 2022 11:09:11 +0100 MIME-Version: 1.0 In-Reply-To: X-Scanned-By: MIMEDefang 3.1 on 10.11.54.1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit On 11/06/22 02:19, Yao, Jiewen wrote: > Acked-by: Jiewen Yao Thanks for the ACKs; Jiewen, can you please merge the patch? Thanks Laszlo > >> -----Original Message----- >> From: Kinney, Michael D >> Sent: Friday, November 4, 2022 11:29 PM >> To: Laszlo Ersek ; devel@edk2.groups.io; Kinney, >> Michael D >> Cc: Zurcher, Christopher ; Jiang, >> Guomin ; Wang, Jian J ; >> Yao, Jiewen ; Lu, Xiaoyu1 >> Subject: RE: [PATCH v2] CryptoPkg/Readme.md: typo and grammar fixes >> >> Reviewed-by: Michael D Kinney >> >> >>> -----Original Message----- >>> From: Laszlo Ersek >>> Sent: Friday, November 4, 2022 5:02 AM >>> To: devel@edk2.groups.io; lersek@redhat.com >>> Cc: Zurcher, Christopher ; Jiang, >> Guomin ; Wang, Jian J >>> ; Yao, Jiewen ; Kinney, >> Michael D ; Lu, Xiaoyu1 >>> >>> Subject: [PATCH v2] CryptoPkg/Readme.md: typo and grammar fixes >>> >>> 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 >>> --- >>> >>> Notes: >>> v2: >>> >>> - URL: >>> >> https://pagure.io/lersek/edk2/c/8d7b26bfb6a1?branch=cryptopkg_readm >> e_typos_v2 >>> >>> - v1 was at: >>> - https://listman.redhat.com/archives/edk2-devel-archive/2022- >> November/055153.html >>> - msgid <20221102093637.9132-1-lersek@redhat.com> >>> >>> - keep referring to the singular HashApiLib algorithm that >>> PcdHashApiLibPolicy exposes for configuration in singular [Mike] >>> >>> - still fix the duplicated "to" typo >>> >>> - range-diff against v1 (i.e., first hunk dropped, second hunk updated): >>> >>> > 1: a7269f170437 ! 1: 8d7b26bfb6a1 CryptoPkg/Readme.md: typo >> and grammar fixes >>> > @@ -94,18 +94,11 @@ >>> > ``` >>> > [LibraryClasses.common.DXE_RUNTIME_DRIVER] >>> > @@ >>> > - ### PCD Configuration Settings >>> > - >>> > - There are 2 PCD settings that are used to configure cryptographic >> services. >>> > --`PcdHashApiLibPolicy` is used to configure the hash algorithm >> provided 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 >> hash of data. The >>> > -+ HASH algorithms to use in the BaseHashApiLib to calculate hash >> 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_ALG_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. >>> >>> ## Statically Linking Cryptographic Services >>> >>> -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 use of >>> cryptographic services. The cryptographic services are provided by three >> library >>> 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 >> the >>> private library class called IntrinsicLib. >>> >>> -The CryptoPkg provides several instances if the BaseCryptLib and >> OpensslLib with >>> +The CryptoPkg provides several instances of the BaseCryptLib and >> OpensslLib 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. >>> >>> The EDK II modules/libraries that require cryptographic services use the >> same >>> BaseCryptLib/TlsLib/HashApiLib APIs. This means no source changes are >> required >>> -to use static linking or dynamic linking. It is a platform configuration >> options >>> -to select static linking or dynamic linking. This choice can be make >> globally, >>> -per firmware module type, or individual modules. >>> +to use static linking or dynamic linking. It is a platform configuration >> option >>> +to select static linking or dynamic linking. This choice can be made >> globally, >>> +per firmware module type, or for individual modules. >>> >>> ``` >>> +===================+ +===================+ >> +===================+ >>> @@ -159,7 +159,7 @@ The table below provides a summary of the >> supported cryptographic 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 >> service. >>> If a cell is blank then the service or family is always disabled and the >>> -`PcdCryptoServiceFamilyEnable` settings for that family or service is >> ignored. >>> +`PcdCryptoServiceFamilyEnable` setting for that family or service is >> ignored. >>> 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). >>> >>> The following table can be used to help select the best OpensslLib >> instance 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. >>> >>> | OpensslLib Instance | SSL | ECC | Perf Opt | CPU Arch | Size | >>> @@ -371,10 +371,10 @@ settings. >>> >>> ### UEFI Runtime Driver Library Mappings >>> >>> -UEFI Runtime Drivers only supports static linking of cryptographic >> services. >>> -The following library mappings are recommended for UEFI Runtime >> Drivers. It uses >>> -the runtime specific version of the BaseCryptLib and the null version of >> the >>> -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. They >>> +use the runtime specific version of the BaseCryptLib and the null version >> of the >>> +TlsLib because TLS services are not typically used at runtime. >>> >>> ``` >>> [LibraryClasses.common.DXE_RUNTIME_DRIVER] >>> @@ -394,7 +394,7 @@ 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 hash 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_ALG_SHA256. >>> | Setting | Algorithm | >>> |------------|------------------| >>> @@ -407,8 +407,8 @@ and CryptoSmm modules. >>> * `gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable` - >> Enable/Disable >>> the families and individual services produced by the EDK II Crypto >>> Protocols/PPIs. The default is all services disabled. This Structured PCD >> is >>> - associated with `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` structure >> that defined in >>> - `Include/Pcd/PcdCryptoServiceFamilyEnable.h`. >>> + associated with the `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` >> structure that is >>> + defined in `Include/Pcd/PcdCryptoServiceFamilyEnable.h`. >>> >>> 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 disabled >>> by default. An entire family of services can be enabled by setting the >>> family field to the value `PCD_CRYPTO_SERVICE_ENABLE_FAMILY`. >> Individual >>> - services can be enabled by setting a single service name to `TRUE`. >>> - Settings listed later in the DSC file have priority over settings earlier >>> - in the DSC file, so it is legal for an entire family to be enabled first >>> - and then a few individual services disabled by setting the service >> name to >>> - `FALSE`. >>> + services can be enabled by setting a single service name (bit) to >> `TRUE`. >>> + Settings listed later in the DSC file have priority over settings listed >>> + earlier in the DSC file, so it is valid for an entire family to be enabled >>> + first and then for a few individual services to be disabled by setting >>> + those service names to `FALSE`. >>> >>> #### Common PEI PcdCryptoServiceFamilyEnable Settings >>>