From nobody Tue Feb 10 05:10:46 2026 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+95005+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+95005+1787277+3901457@groups.io; dmarc=fail(p=none dis=none) header.from=intel.com ARC-Seal: i=1; a=rsa-sha256; t=1665500726; cv=none; d=zohomail.com; s=zohoarc; b=brmeorhTN9Sr8ICFEftuYNCn+zFyNBcpluenK4ITz1wVVtvD6rCEzh1K3bF19sGdvQ3sTWAOJrwQwG9Z1/EgOR+IGkMLKPdcZOzFDRnPIONSPG1yLYf6/K+mfoNPJodypTO7SCZX5WgjHe2YOboh8I+XIspqexUCH9OtvrTivNc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1665500726; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:References:Sender:Subject:To; bh=lj06q6EPlDW/S6wxY+7f0HTklvzQS3hCANj8zipSNcI=; b=GcGCphElWUZd5bX+/AiQKGtiQPE7IC+I35j2hNViWv8Vmb9jDPqbM/p/EUjTdbyImfTMmz8N/lh6gwnpJnrBiAMFeg57jFLk57WtOUlOsN4JfkYIOrWOSc8W6qu1KZKesAf4rYxxVXGm6L+at9VnNqrL2TQqKnCghFTvNpwCsos= 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+95005+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 166550072664570.60940917981827; Tue, 11 Oct 2022 08:05:26 -0700 (PDT) Return-Path: X-Received: by 127.0.0.2 with SMTP id ztkbYY1788612xRX0NTylr38; Tue, 11 Oct 2022 08:05:25 -0700 X-Received: from mga06.intel.com (mga06.intel.com [134.134.136.31]) by mx.groups.io with SMTP id smtpd.web09.8668.1665500716182547303 for ; Tue, 11 Oct 2022 08:05:17 -0700 X-IronPort-AV: E=McAfee;i="6500,9779,10497"; a="366518359" X-IronPort-AV: E=Sophos;i="5.95,176,1661842800"; d="scan'208";a="366518359" X-Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga104.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 11 Oct 2022 08:04:10 -0700 X-IronPort-AV: E=McAfee;i="6500,9779,10497"; a="604172848" X-IronPort-AV: E=Sophos;i="5.95,176,1661842800"; d="scan'208";a="604172848" X-Received: from mdkinney-mobl2.amr.corp.intel.com ([10.209.79.249]) by orsmga006-auth.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 11 Oct 2022 08:04:09 -0700 From: "Michael D Kinney" To: devel@edk2.groups.io Cc: Jiewen Yao , Jian J Wang , Xiaoyu Lu , Guomin Jiang , Christopher Zurcher Subject: [edk2-devel] [Patch 12/12] CryptoPkg: Add Readme.md Date: Tue, 11 Oct 2022 08:03:58 -0700 Message-Id: <20221011150358.1332-13-michael.d.kinney@intel.com> In-Reply-To: <20221011150358.1332-1-michael.d.kinney@intel.com> References: <20221011150358.1332-1-michael.d.kinney@intel.com> MIME-Version: 1.0 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,michael.d.kinney@intel.com X-Gm-Message-State: xAzNm0ZVTG5Bvy99YtoxeMX2x1787277AA= Content-Transfer-Encoding: quoted-printable DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=groups.io; q=dns/txt; s=20140610; t=1665500725; bh=RO4pZJHZgRYSJWhNwHZB95v8RXYXaTAlKf6yqG17sHM=; h=Cc:Date:From:Reply-To:Subject:To; b=o848PdTKorsMJRLT4VqP5THCI9EXNpVytvKDpbe+vA5Pbb5Qhm7fsp08okgGbiw7Muy bZm14dD+1vYTnHxdz70DJcYZvbM9WnacTF/RincEPdO8UMkb/LkZ/ASeDgO+lUeFmeMnz YCx9gC7aYpMBiiUjHvrN92mopjpXRpvyGnw= X-ZohoMail-DKIM: pass (identity @groups.io) X-ZM-MESSAGEID: 1665500727241100002 Content-Type: text/plain; charset="utf-8" Add Readme.md that provides an overview of the CryptoPkg and how to configure the use of cryptographic services in a platform. Cc: Jiewen Yao Cc: Jian J Wang Cc: Xiaoyu Lu Cc: Guomin Jiang Cc: Christopher Zurcher Signed-off-by: Michael D Kinney --- CryptoPkg/Readme.md | 498 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 498 insertions(+) create mode 100644 CryptoPkg/Readme.md diff --git a/CryptoPkg/Readme.md b/CryptoPkg/Readme.md new file mode 100644 index 000000000000..a6f7531170ef --- /dev/null +++ b/CryptoPkg/Readme.md @@ -0,0 +1,498 @@ +# Crypto Package + +This package provides cryptographic services that are used to implement fi= rmware +features such as UEFI Secure Boot, Measured Boot, firmware image authentic= ation, +and network boot. The cryptographic service implementation in this package= uses +services from the [OpenSSL](https://www.openssl.org/) project. + +EDK II firmware modules/libraries that requires the use of cryptographic +services can either statically link all the required services, or the EDK = II +firmware module/library can use a dynamic Protocol/PPI service to call +cryptographic services. The dynamic Protocol/PPI services are only availab= le to +PEIMs, DXE Drivers, UEFI Drivers, and SMM Drivers, and only if the cryptog= raphic +modules are included in the platform firmware image. + +There may be firmware image size differences between the static and dynamic +options. Some experimentation may be required to find the solution that +provides the smallest overall firmware overhead. + +# Public Library Classes + +* **BaseCryptLib** - Provides library functions for cryptographic primitiv= es. +* **TlsLib** - Provides TLS library functions for EFI TLS protocol. +* **HashApiLib** - Provides Unified API for different hash implementatio= ns. + +# Private Library Classes + +* **OpensslLib** - Provides library functions from the openssl project. +* **IntrinsicLib** - Provides C runtime library (CRT) required by openssl. + +# Private Protocols and PPIs + +* **EDK II Crypto PPI** - PPI that provides all the services from + the BaseCryptLib and TlsLib library cla= sses. +* **EDK II Crypto Protocol** - Protocol that provides all the services= from + the BaseCryptLib and TlsLib library cla= sses. +* **EDK II SMM Crypto Protocol** - SMM Protocol that provides all the serv= ices + from the BaseCryptLib and TlsLib library + classes. + +## Statically Linking Cryptographic Services + +The figure below shows an example of a firmware modules that requires the = use 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 +private library class called OpensslLib. The OpenSSL project implementation +depends on C runtime library services. The EDK II project does not provide= a +full C runtime library for firmware components. Instead, the CryptoPkg inc= ludes +the smallest subset of services required to build the OpenSSL project in t= he +private library class called IntrinsicLib. + +The CryptoPkg provides several instances if 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, +UEFI RT, and SMM), firmware image size requirements, and firmware boot +performance requirements. + +``` ++=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+ +| EDK II Firmware Module/Library | ++=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+ + ^ ^ ^ + | | | + | | v + | | +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | | | HashApiLib | + | | +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D+ + | | ^ + | | | + v v v ++=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+ +| TlsLib | | BaseCryptLib | ++=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+ + ^ ^ + | | + v v ++=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+ +| OpensslLib (Private) | ++=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+ + ^ + | + v ++=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+ +| IntrinsicLib (Private) | ++=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+ +``` + +## Dynamically Linking Cryptographic Services + +The figure below shows the entire stack when dynamic linking is used with +cryptographic services produced by the CryptoPei, CryptoDxe, or CryptoSmm = module +through a PPI/Protocol. This solution requires the CryptoPei, CryptoDxe, a= nd +CryptoSmm modules to be configured with the set of cryptographic services +required by all the PEIMs, DXE Drivers, UEFI Drivers, and SMM Drivers. Dyn= amic +linking is not available for SEC or UEFI RT modules. + +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. + +``` ++=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+ +| EDK II PEI | | EDK II DXE/UEFI | | EDK II SMM | +| Module/Library | | Module/Library | | Module/Library | ++=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+ + ^ ^ ^ ^ ^ ^ ^ ^ ^ + | | | | | | | | | + | | v | | v | | v + | | +=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+ + | | |HashApiLib| | | |HashApiLib| | | |HashApiLib| + | | +=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+ + | | ^ | | ^ | | ^ + | | | | | | | | | + v v v v v v v v v ++=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+ +|TlsLib|BaseCryptLib| |TlsLib|BaseCryptLib| |TlsLib|BaseCryptLib| ++-------------------+ +-------------------+ +-------------------+ +| BaseCryptLib | | BaseCryptLib | | BaseCryptLib | +| OnPpiProtocol/ | | OnPpiProtocol/ | | OnPpiProtocol/ | +| PeiCryptLib.inf | | DxeCryptLib.inf | | SmmCryptLib.inf | ++=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+ + ^ ^ ^ + ||| (Dynamic) ||| (Dynamic) ||| (Dynamic) + v v v ++=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=3D=3D+ +| Crypto PPI | | Crypto Protocol | | Crypto SMM Protocol | ++-------------------| |-------------------| |---------------------| +| CryptoPei | | CryptoDxe | | CryptoSmm | ++=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=3D=3D+ + ^ ^ ^ ^ ^ ^ + | | | | | | + v | v | v | ++=3D=3D=3D=3D=3D=3D=3D=3D+ | +=3D=3D=3D=3D=3D=3D=3D=3D+ | = +=3D=3D=3D=3D=3D=3D=3D=3D+ | +| TlsLib | | | TlsLib | | | TlsLib | | ++=3D=3D=3D=3D=3D=3D=3D=3D+ v +=3D=3D=3D=3D=3D=3D=3D=3D+ v = +=3D=3D=3D=3D=3D=3D=3D=3D+ v + ^ +=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+ + | | BaseCryptLib | | | BaseCryptLib | | | BaseCryptLib | + | +=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+ + | ^ | ^ | ^ + | | | | | | + v v v v v v ++=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+ +| OpensslLib | | OpensslLib | | OpensslLib | ++=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+ + ^ ^ ^ + | | | + v v v ++=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+ +| IntrinsicLib | | IntrinsicLib | | IntrinsicLib | ++=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+ +``` + +## Supported Cryptographic Families and Services + +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 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. +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. + +|Key | Description = | +|---------|---------------------------------------------------------------= -----------------| +| | Family or service is always disabled. = | +| C | Configurable using PcdCryptoServiceFamilyEnable. = | +| C-Tls | Configurable using PcdCryptoServiceFamilyEnable. Requires TlsL= ib.inf. | +| C-Full | Configurable using PcdCryptoServiceFamilyEnable. Requires Open= sslLibFull*.inf. | + +|Family/Service | Deprecated | Don't Use | SecCryptLib |= PeiCryptLib | BaseCryptLib | SmmCryptLib | RuntimeCryptLib | +|:--------------------------------|:----------:|:---------:|:-----------:|= :-----------:|:------------:|:-----------:|:---------------:| +| HmacMd5 | Y | Y | |= | | | | +| HmacSha1 | Y | Y | |= | | | | +| HmacSha256 | N | N | |= C | C | C | C | +| HmacSha384 | N | N | |= C | C | C | C | +| Md4 | Y | Y | |= | | | | +| Md5 | Y | Y | |= C | C | C | C | +| Pkcs.Pkcs1v2Encrypt | N | N | |= | C | C | | +| Pkcs.Pkcs5HashPassword | N | N | |= | C | C | | +| Pkcs.Pkcs7Verify | N | N | |= C | C | C | C | +| Pkcs.VerifyEKUsInPkcs7Signature | N | N | |= C | C | C | | +| Pkcs.Pkcs7GetSigners | N | N | |= C | C | C | C | +| Pkcs.Pkcs7FreeSigners | N | N | |= C | C | C | C | +| Pkcs.Pkcs7Sign | N | N | |= | C | | | +| Pkcs.Pkcs7GetAttachedContent | N | N | |= C | C | C | | +| Pkcs.Pkcs7GetCertificatesList | N | N | |= C | C | C | C | +| Pkcs.AuthenticodeVerify | N | N | |= | C | | | +| Pkcs.ImageTimestampVerify | N | N | |= | C | | | +| Dh | N | N | |= | C | | | +| Random | N | N | |= | C | C | C | +| Rsa.VerifyPkcs1 | Y | Y | |= | | | | +| Rsa.New | N | N | |= C | C | C | C | +| Rsa.Free | N | N | |= C | C | C | C | +| Rsa.SetKey | N | N | |= C | C | C | C | +| Rsa.GetKey | N | N | |= | C | | | +| Rsa.GenerateKey | N | N | |= | C | | | +| Rsa.CheckKey | N | N | |= | C | | | +| Rsa.Pkcs1Sign | N | N | |= | C | | | +| Rsa.Pkcs1Verify | N | N | |= C | C | C | C | +| Sha1 | N | Y | |= C | C | C | C | +| Sha256 | N | N | |= C | C | C | C | +| Sha384 | N | N | C |= C | C | C | C | +| Sha512 | N | N | C |= C | C | C | C | +| X509 | N | N | |= | C | C | C | +| Tdes | Y | N | |= | | | | +| Aes.GetContextSize | N | N | |= | C | C | C | +| Aes.Init | N | N | |= | C | C | C | +| Aes.EcbEncrypt | Y | N | |= | | | | +| Aes.EcbDecrypt | Y | N | |= | | | | +| Aes.CbcEncrypt | N | N | |= | C | C | C | +| Aes.CbcDecrypt | N | N | |= | C | C | C | +| Arc4 | Y | N | |= | | | | +| Sm3 | N | N | |= C | C | C | C | +| Hkdf | N | N | |= C | C | | C | +| Tls | N | N | |= | C-Tls | | | +| TlsSet | N | N | |= | C-Tls | | | +| TlsGet | N | N | |= | C-Tls | | | +| RsaPss.Sign | N | N | |= | C | | | +| RsaPss.Verify | N | N | |= C | C | C | | +| ParallelHash | N | N | |= | | C | | +| AeadAesGcm | N | N | |= | C | | | +| Bn | N | N | |= | C | | | +| Ec | N | N | |= | C-Full | | | + +## Platform Configuration of Cryptographic Services + +Configuring the cryptographic services requires library mappings and PCD +settings in a platform DSC file. This must be done for each of the firmware +phases (SEC, PEI, DXE, UEFI, SMM, UEFI RT). + +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 +`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 +`OpensslLibFull.inf`. Performance optimization requires a size increase. + +| OpensslLib Instance | SSL | ECC | Perf Opt | CPU Arch | Size | +|:------------------------|:---:|:---:|:--------:|:--------:|:-----:| +| OpensslLibCrypto.inf | N | N | N | All | +0K | +| OpensslLib.inf | Y | N | N | All | +0K | +| OpensslLibAccel.inf | Y | N | Y | IA32/X64 | +20K | +| OpensslLibFull.inf | Y | Y | N | All | +115K | +| OpensslLibFullAccel.inf | Y | Y | Y | IA32/X64 | +135K | + +### SEC Phase Library Mappings + +The SEC Phase only supports static linking of cryptographic services. The +following library mappings are recommended for the SEC Phase. It uses the = SEC +specific version of the BaseCryptLib and the null version of the TlsLib be= cause +TLS services are not typically used in SEC. + +``` +[LibraryClasses.common.SEC] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/SecCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf +``` + +### PEI Phase Library Mappings + +The PEI Phase supports either static or dynamic linking of cryptographic +services. The following library mappings are recommended for the PEI Phase= . It +uses the PEI specific version of the BaseCryptLib and the null version of = the +TlsLib because TLS services are not typically used in PEI. + +``` +[LibraryClasses.common.PEIM] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/PeiCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf +``` + +If dynamic linking is used, then all PEIMs except CryptoPei use the follow= ing +library mappings. The CryptoPei module uses the static linking settings. + +``` +[LibraryClasses.common.PEIM] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLibOnProtocolPpi/PeiCryptLib.inf + +[Components] + CryptoPkg/Driver/CryptoPei.inf { + + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/PeiCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf + } +``` + +### DXE Phase, UEFI Driver, UEFI Application Library Mappings + +The DXE/UEFI Phase supports either static or dynamic linking of cryptograp= hic +services. The following library mappings are recommended for the DXE/UEFI = Phase. +It uses the DXE specific version of the BaseCryptLib and the full version = of the +OpensslLib and TlsLib. If ECC services are not required then a smaller +OpensslLib instance can be used. + +``` +[LibraryClasses.common.DXE_DRIVER, LibraryClasses.common.UEFI_DRIVER, Libr= aryClasses.common.UEFI_APPLICATION] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/BaseCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLib/TlsLib.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLibFull.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf +``` + +If dynamic linking is used, then all DXE Drivers except CryptoDxe use the +following library mappings. The CryptoDxe module uses the static linking +settings. + +``` +[LibraryClasses.common.DXE_DRIVER, LibraryClasses.common.UEFI_DRIVER, Libr= aryClasses.common.UEFI_APPLICATION] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLibOnProtocolPpi/DxeCryptLib.inf + +[Components] + CryptoPkg/Driver/CryptoDxe.inf { + + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/BaseCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLib/TlsLib.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLibFull.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf + } +``` + +### SMM Phase Library Mappings + +The SMM Phase supports either static or dynamic linking of cryptographic +services. The following library mappings are recommended for the SMM Phase= . It +uses the SMM specific version of the BaseCryptLib and the null version of = the +TlsLib. + +``` +[LibraryClasses.common.DXE_SMM_DRIVER] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/SmmCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf +``` + +If dynamic linking is used, then all SMM Drivers except CryptoSmm use the +following library mappings. The CryptoDxe module uses the static linking +settings. + +``` +[LibraryClasses.common.DXE_SMM_DRIVER] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLibOnProtocolPpi/SmmCryptLib.inf + +[Components] + CryptoPkg/Driver/CryptoSmm.inf { + + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/SmmCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf + } +``` + +### UEFI Runtime Driver Library Mappings + +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. + +``` +[LibraryClasses.common.DXE_RUNTIME_DRIVER] + HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf + BaseCryptLib|CryptoPkg/Library/BaseCryptLib/RuntimeCryptLib.inf + TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf + OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf + IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf +``` + +### 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 +BaseHashApiLib library instance. `PcdCryptoServiceFamilyEnable` is used to +configure the cryptographic services supported by the CryptoPei, CryptoDxe, +and CryptoSmm modules. + +* `gEfiCryptoPkgTokenSpaceGuid.PcdHashApiLibPolicy` - This PCD indicates t= he + HASH algorithm to to use in the BaseHashApiLib to calculate hash of data= . The + default hashing algorithm for BaseHashApiLib is set to HASH_ALG_SHA256. + | Setting | Algorithm | + |------------|------------------| + | 0x00000001 | HASH_ALG_SHA1 | + | 0x00000002 | HASH_ALG_SHA256 | + | 0x00000004 | HASH_ALG_SHA384 | + | 0x00000008 | HASH_ALG_SHA512 | + | 0x00000010 | HASH_ALG_SM3_256 | + +* `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`. + + There are three layers of priority that determine if a specific family = or + individual cryptographic service is actually enabled in the CryptoPei, + CryptoDxe, and CryptoSmm modules. + + 1) OpensslLib instance selection. When the CryptoPei, CryptoDxe, or Cry= ptoSmm + drivers are built, they are statically linked to an OpensslLib libra= ry + instance. If the required cryptographic service is not enabled in the + 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 + 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. 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 + 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 + enabled in the BaseCryptLib instance, then it can be enabled/disabled + using `PcdCryptoServiceFamilyEnable`. This structured PCD is associa= ted + with the `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` data structure that cont= ains + 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`. + +#### Common PEI PcdCryptoServiceFamilyEnable Settings + +``` + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha256.Fami= ly | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha384.Fami= ly | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha1.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha256.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha384.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha512.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sm3.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Pk= cs1Verify | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Ne= w | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Fr= ee | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Se= tKey | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.P= kcs5HashPassword | TRUE +``` + +#### Common DXE and SMM PcdCryptoServiceFamilyEnable Settings + +``` + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha256.Fami= ly | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha384.Fami= ly | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.P= kcs1v2Encrypt | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.P= kcs5HashPassword | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.P= kcs7Verify | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.V= erifyEKUsInPkcs7Signature | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.P= kcs7GetSigners | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.P= kcs7FreeSigners | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.A= uthenticodeVerify | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Random.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Pk= cs1Verify | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Ne= w | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Fr= ee | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Se= tKey | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Ge= tPublicKeyFromX509 | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha1.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha256.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha256.Services= .HashAll | FALSE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.G= etSubjectName | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.G= etCommonName | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.G= etOrganizationName | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.G= etTBSCert | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Tls.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.TlsSet.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.TlsGet.Family = | PCD_CRYPTO_SERVICE_ENABLE_FAMILY + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.Ge= tContextSize | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.In= it | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.Cb= cEncrypt | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.Cb= cDecrypt | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.AeadAesGcm.Serv= ices.Encrypt | TRUE + gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.AeadAesGcm.Serv= ices.Decrypt | TRUE +``` --=20 2.37.1.windows.1 -=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 (#95005): https://edk2.groups.io/g/devel/message/95005 Mute This Topic: https://groups.io/mt/94260752/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-