CryptoPkg/Readme.md

   1 # Crypto Package
   2
   3 This package provides cryptographic services that are used to implement firmware
   4 features such as UEFI Secure Boot, Measured Boot, firmware image authentication,
   5 and network boot. The cryptographic service implementation in this package uses
   6 services from the [OpenSSL](https://www.openssl.org/) project.
   7
   8 EDK II firmware modules/libraries that requires the use of cryptographic
   9 services can either statically link all the required services, or the EDK II
  10 firmware module/library can use a dynamic Protocol/PPI service to call
  11 cryptographic services. The dynamic Protocol/PPI services are only available to
  12 PEIMs, DXE Drivers, UEFI Drivers, and SMM Drivers, and only if the cryptographic
  13 modules are included in the platform firmware image.
  14
  15 There may be firmware image size differences between the static and dynamic
  16 options. Some experimentation may be required to find the solution that
  17 provides the smallest overall firmware overhead.
  18
  19 # Public Library Classes
  20
  21 * **BaseCryptLib** - Provides library functions for cryptographic primitives.
  22 * **TlsLib**       - Provides TLS library functions for EFI TLS protocol.
  23 * **HashApiLib**   - Provides Unified API for different hash implementations.
  24
  25 # Private Library Classes
  26
  27 * **OpensslLib**   - Provides library functions from the openssl project.
  28 * **IntrinsicLib** - Provides C runtime library (CRT) required by openssl.
  29
  30 # Private Protocols and PPIs
  31
  32 * **EDK II Crypto PPI**          - PPI that provides all the services from
  33                                    the BaseCryptLib and TlsLib library classes.
  34 * **EDK II Crypto Protocol**     - Protocol that provides all the services from
  35                                    the BaseCryptLib and TlsLib library classes.
  36 * **EDK II SMM Crypto Protocol** - SMM Protocol that provides all the services
  37                                    from the BaseCryptLib and TlsLib library
  38                                    classes.
  39
  40 ## Statically Linking Cryptographic Services
  41
  42 The figure below shows an example of a firmware module that requires the use of
  43 cryptographic services. The cryptographic services are provided by three library
  44 classes called BaseCryptLib, TlsLib, and HashApiLib. These library classes are
  45 implemented using APIs from the OpenSSL project that are abstracted by the
  46 private library class called OpensslLib. The OpenSSL project implementation
  47 depends on C runtime library services. The EDK II project does not provide a
  48 full C runtime library for firmware components. Instead, the CryptoPkg includes
  49 the smallest subset of services required to build the OpenSSL project in the
  50 private library class called IntrinsicLib.
  51
  52 The CryptoPkg provides several instances of the BaseCryptLib and OpensslLib with
  53 different cryptographic service features and performance optimizations. The
  54 platform developer must select the correct instances based on cryptographic
  55 service requirements in each UEFI/PI firmware phase (SEC, PEI, DXE, UEFI,
  56 UEFI RT, and SMM), firmware image size requirements, and firmware boot
  57 performance requirements.
  58
  59 ```
  60 +================================+
  61 | EDK II Firmware Module/Library |
  62 +================================+
  63      ^          ^         ^
  64      |          |         |
  65      |          |         v
  66      |          |   +============+
  67      |          |   | HashApiLib |
  68      |          |   +============+
  69      |          |         ^
  70      |          |         |
  71      v          v         v
  72 +========+  +====================+
  73 | TlsLib |  |    BaseCryptLib    |
  74 +========+  +====================+
  75      ^                ^
  76      |                |
  77      v                v
  78 +================================+
  79 |     OpensslLib (Private)       |
  80 +================================+
  81                ^
  82                |
  83                v
  84 +================================+
  85 |     IntrinsicLib (Private)     |
  86 +================================+
  87 ```
  88
  89 ## Dynamically Linking Cryptographic Services
  90
  91 The figure below shows the entire stack when dynamic linking is used with
  92 cryptographic services produced by the CryptoPei, CryptoDxe, or CryptoSmm module
  93 through a PPI/Protocol. This solution requires the CryptoPei, CryptoDxe, and
  94 CryptoSmm modules to be configured with the set of cryptographic services
  95 required by all the PEIMs, DXE Drivers, UEFI Drivers, and SMM Drivers. Dynamic
  96 linking is not available for SEC or UEFI RT modules.
  97
  98 The EDK II modules/libraries that require cryptographic services use the same
  99 BaseCryptLib/TlsLib/HashApiLib APIs. This means no source changes are required
 100 to use static linking or dynamic linking. It is a platform configuration option
 101 to select static linking or dynamic linking. This choice can be made globally,
 102 per firmware module type, or for individual modules.
 103
 104 ```
 105 +===================+    +===================+     +===================+
 106 |    EDK II PEI     |    |  EDK II DXE/UEFI  |     |     EDK II SMM    |
 107 |   Module/Library  |    |   Module/Library  |     |   Module/Library  |
 108 +===================+    +===================+     +===================+
 109   ^   ^        ^           ^   ^        ^            ^   ^        ^
 110   |   |        |           |   |        |            |   |        |
 111   |   |        v           |   |        v            |   |        v
 112   |   |  +==========+      |   |  +==========+       |   |  +==========+
 113   |   |  |HashApiLib|      |   |  |HashApiLib|       |   |  |HashApiLib|
 114   |   |  +==========+      |   |  +==========+       |   |  +==========+
 115   |   |        ^           |   |        ^            |   |        ^
 116   |   |        |           |   |        |            |   |        |
 117   v   v        v           v   v        v            v   v        v
 118 +===================+    +===================+     +===================+
 119 |TlsLib|BaseCryptLib|    |TlsLib|BaseCryptLib|     |TlsLib|BaseCryptLib|
 120 +-------------------+    +-------------------+     +-------------------+
 121 |   BaseCryptLib    |    |   BaseCryptLib    |     |   BaseCryptLib    |
 122 |   OnPpiProtocol/  |    |   OnPpiProtocol/  |     |   OnPpiProtocol/  |
 123 |  PeiCryptLib.inf  |    |   DxeCryptLib.inf |     |  SmmCryptLib.inf  |
 124 +===================+    +===================+     +===================+
 125            ^                      ^                         ^
 126           ||| (Dynamic)          ||| (Dynamic)             ||| (Dynamic)
 127            v                      v                         v
 128 +===================+    +===================+    +=====================+
 129 |     Crypto PPI    |    |  Crypto Protocol  |    | Crypto SMM Protocol |
 130 +-------------------|    |-------------------|    |---------------------|
 131 |     CryptoPei     |    |     CryptoDxe     |    |      CryptoSmm      |
 132 +===================+    +===================+    +=====================+
 133      ^       ^                ^       ^                 ^       ^
 134      |       |                |       |                 |       |
 135      v       |                v       |                 v       |
 136 +========+   |           +========+   |            +========+   |
 137 | TlsLib |   |           | TlsLib |   |            | TlsLib |   |
 138 +========+   v           +========+   v            +========+   v
 139   ^  +==============+      ^  +==============+       ^  +==============+
 140   |  | BaseCryptLib |      |  | BaseCryptLib |       |  | BaseCryptLib |
 141   |  +==============+      |  +==============+       |  +==============+
 142   |          ^             |          ^              |          ^
 143   |          |             |          |              |          |
 144   v          v             v          v              v          v
 145 +===================+    +===================+     +===================+
 146 |    OpensslLib     |    |    OpensslLib     |     |    OpensslLib     |
 147 +===================+    +===================+     +===================+
 148           ^                        ^                         ^
 149           |                        |                         |
 150           v                        v                         v
 151 +===================+    +===================+     +===================+
 152 |    IntrinsicLib   |    |    IntrinsicLib   |     |    IntrinsicLib   |
 153 +===================+    +===================+     +===================+
 154 ```
 155
 156 ## Supported Cryptographic Families and Services
 157
 158 The table below provides a summary of the supported cryptographic services. It
 159 indicates if the family or service is deprecated or recommended to not be used.
 160 It also shows which *CryptLib library instances support the family or service.
 161 If a cell is blank then the service or family is always disabled and the
 162 `PcdCryptoServiceFamilyEnable` setting for that family or service is ignored.
 163 If the cell is not blank, then the service or family is configurable using
 164 `PcdCryptoServiceFamilyEnable` as long as the correct OpensslLib or TlsLib is
 165 also configured.
 166
 167 |Key      | Description                                                                    |
 168 |---------|--------------------------------------------------------------------------------|
 169 | <blank> | Family or service is always disabled.                                          |
 170 | C       | Configurable using PcdCryptoServiceFamilyEnable.                               |
 171 | C-Tls   | Configurable using PcdCryptoServiceFamilyEnable. Requires TlsLib.inf.          |
 172 | C-Full  | Configurable using PcdCryptoServiceFamilyEnable. Requires OpensslLibFull*.inf. |
 173
 174 |Family/Service                   | Deprecated | Don't Use | SecCryptLib | PeiCryptLib | BaseCryptLib | SmmCryptLib | RuntimeCryptLib |
 175 |:--------------------------------|:----------:|:---------:|:-----------:|:-----------:|:------------:|:-----------:|:---------------:|
 176 | HmacMd5                         |     Y      |     Y     |             |             |              |             |                 |
 177 | HmacSha1                        |     Y      |     Y     |             |             |              |             |                 |
 178 | HmacSha256                      |     N      |     N     |             |      C      |      C       |      C      |        C        |
 179 | HmacSha384                      |     N      |     N     |             |      C      |      C       |      C      |        C        |
 180 | Md4                             |     Y      |     Y     |             |             |              |             |                 |
 181 | Md5                             |     Y      |     Y     |             |      C      |      C       |      C      |        C        |
 182 | Pkcs.Pkcs1v2Encrypt             |     N      |     N     |             |             |      C       |      C      |                 |
 183 | Pkcs.Pkcs5HashPassword          |     N      |     N     |             |             |      C       |      C      |                 |
 184 | Pkcs.Pkcs7Verify                |     N      |     N     |             |      C      |      C       |      C      |        C        |
 185 | Pkcs.VerifyEKUsInPkcs7Signature |     N      |     N     |             |      C      |      C       |      C      |                 |
 186 | Pkcs.Pkcs7GetSigners            |     N      |     N     |             |      C      |      C       |      C      |        C        |
 187 | Pkcs.Pkcs7FreeSigners           |     N      |     N     |             |      C      |      C       |      C      |        C        |
 188 | Pkcs.Pkcs7Sign                  |     N      |     N     |             |             |      C       |             |                 |
 189 | Pkcs.Pkcs7GetAttachedContent    |     N      |     N     |             |      C      |      C       |      C      |                 |
 190 | Pkcs.Pkcs7GetCertificatesList   |     N      |     N     |             |      C      |      C       |      C      |        C        |
 191 | Pkcs.AuthenticodeVerify         |     N      |     N     |             |             |      C       |             |                 |
 192 | Pkcs.ImageTimestampVerify       |     N      |     N     |             |             |      C       |             |                 |
 193 | Dh                              |     N      |     N     |             |             |      C       |             |                 |
 194 | Random                          |     N      |     N     |             |             |      C       |      C      |        C        |
 195 | Rsa.VerifyPkcs1                 |     Y      |     Y     |             |             |              |             |                 |
 196 | Rsa.New                         |     N      |     N     |             |      C      |      C       |      C      |        C        |
 197 | Rsa.Free                        |     N      |     N     |             |      C      |      C       |      C      |        C        |
 198 | Rsa.SetKey                      |     N      |     N     |             |      C      |      C       |      C      |        C        |
 199 | Rsa.GetKey                      |     N      |     N     |             |             |      C       |             |                 |
 200 | Rsa.GenerateKey                 |     N      |     N     |             |             |      C       |             |                 |
 201 | Rsa.CheckKey                    |     N      |     N     |             |             |      C       |             |                 |
 202 | Rsa.Pkcs1Sign                   |     N      |     N     |             |             |      C       |             |                 |
 203 | Rsa.Pkcs1Verify                 |     N      |     N     |             |      C      |      C       |      C      |        C        |
 204 | Sha1                            |     N      |     Y     |             |      C      |      C       |      C      |        C        |
 205 | Sha256                          |     N      |     N     |             |      C      |      C       |      C      |        C        |
 206 | Sha384                          |     N      |     N     |      C      |      C      |      C       |      C      |        C        |
 207 | Sha512                          |     N      |     N     |      C      |      C      |      C       |      C      |        C        |
 208 | X509                            |     N      |     N     |             |             |      C       |      C      |        C        |
 209 | Tdes                            |     Y      |     Y     |             |             |              |             |                 |
 210 | Aes.GetContextSize              |     N      |     N     |             |      C      |      C       |      C      |        C        |
 211 | Aes.Init                        |     N      |     N     |             |      C      |      C       |      C      |        C        |
 212 | Aes.EcbEncrypt                  |     Y      |     Y     |             |             |              |             |                 |
 213 | Aes.EcbDecrypt                  |     Y      |     Y     |             |             |              |             |                 |
 214 | Aes.CbcEncrypt                  |     N      |     N     |             |      C      |      C       |      C      |        C        |
 215 | Aes.CbcDecrypt                  |     N      |     N     |             |      C      |      C       |      C      |        C        |
 216 | Arc4                            |     Y      |     Y     |             |             |              |             |                 |
 217 | Sm3                             |     N      |     N     |             |      C      |      C       |      C      |        C        |
 218 | Hkdf                            |     N      |     N     |             |      C      |      C       |      C      |        C        |
 219 | Tls                             |     N      |     N     |             |             |    C-Tls     |             |                 |
 220 | TlsSet                          |     N      |     N     |             |             |    C-Tls     |             |                 |
 221 | TlsGet                          |     N      |     N     |             |             |    C-Tls     |             |                 |
 222 | RsaPss.Sign                     |     N      |     N     |             |             |      C       |             |                 |
 223 | RsaPss.Verify                   |     N      |     N     |             |      C      |      C       |      C      |                 |
 224 | ParallelHash                    |     N      |     N     |             |             |              |      C      |                 |
 225 | AeadAesGcm                      |     N      |     N     |             |             |      C       |             |                 |
 226 | Bn                              |     N      |     N     |             |             |      C       |             |                 |
 227 | Ec                              |     N      |     N     |             |             |    C-Full    |             |                 |
 228
 229 ## Platform Configuration of Cryptographic Services
 230
 231 Configuring the cryptographic services requires library mappings and PCD
 232 settings in a platform DSC file. This must be done for each of the firmware
 233 phases (SEC, PEI, DXE, UEFI, SMM, UEFI RT).
 234
 235 The following table can be used to help select the best OpensslLib instance for
 236 each phase. The Size column only shows the estimated size increase for a
 237 compressed IA32/X64 module that uses the cryptographic services with
 238 `OpensslLib.inf` as the baseline size. The actual size increase depends on the
 239 specific set of enabled cryptographic services. If ECC services are not
 240 required, then the size can be reduced by using OpensslLib.inf instead of
 241 `OpensslLibFull.inf`. Performance optimization requires a size increase.
 242
 243 | OpensslLib Instance     | SSL | ECC | Perf Opt | CPU Arch | Size  |
 244 |:------------------------|:---:|:---:|:--------:|:--------:|:-----:|
 245 | OpensslLibCrypto.inf    |  N  |  N  |    N     |   All    |   +0K |
 246 | OpensslLib.inf          |  Y  |  N  |    N     |   All    |   +0K |
 247 | OpensslLibAccel.inf     |  Y  |  N  |    Y     | IA32/X64 |  +20K |
 248 | OpensslLibFull.inf      |  Y  |  Y  |    N     |   All    | +115K |
 249 | OpensslLibFullAccel.inf |  Y  |  Y  |    Y     | IA32/X64 | +135K |
 250
 251 ### SEC Phase Library Mappings
 252
 253 The SEC Phase only supports static linking of cryptographic services. The
 254 following library mappings are recommended for the SEC Phase. It uses the SEC
 255 specific version of the BaseCryptLib and the null version of the TlsLib because
 256 TLS services are not typically used in SEC.
 257
 258 ```
 259 [LibraryClasses.common.SEC]
 260   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 261   BaseCryptLib|CryptoPkg/Library/BaseCryptLib/SecCryptLib.inf
 262   TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
 263   OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
 264   IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 265 ```
 266
 267 ### PEI Phase Library Mappings
 268
 269 The PEI Phase supports either static or dynamic linking of cryptographic
 270 services. The following library mappings are recommended for the PEI Phase. It
 271 uses the PEI specific version of the BaseCryptLib and the null version of the
 272 TlsLib because TLS services are not typically used in PEI.
 273
 274 ```
 275 [LibraryClasses.common.PEIM]
 276   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 277   BaseCryptLib|CryptoPkg/Library/BaseCryptLib/PeiCryptLib.inf
 278   TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
 279   OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
 280   IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 281 ```
 282
 283 If dynamic linking is used, then all PEIMs except CryptoPei use the following
 284 library mappings. The CryptoPei module uses the static linking settings.
 285
 286 ```
 287 [LibraryClasses.common.PEIM]
 288   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 289   BaseCryptLib|CryptoPkg/Library/BaseCryptLibOnProtocolPpi/PeiCryptLib.inf
 290
 291 [Components]
 292   CryptoPkg/Driver/CryptoPei.inf {
 293     <LibraryClasses>
 294       BaseCryptLib|CryptoPkg/Library/BaseCryptLib/PeiCryptLib.inf
 295       TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
 296       OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
 297       IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 298   }
 299 ```
 300
 301 ### DXE Phase, UEFI Driver, UEFI Application Library Mappings
 302
 303 The DXE/UEFI Phase supports either static or dynamic linking of cryptographic
 304 services. The following library mappings are recommended for the DXE/UEFI Phase.
 305 It uses the DXE specific version of the BaseCryptLib and the full version of the
 306 OpensslLib and TlsLib. If ECC services are not required then a smaller
 307 OpensslLib instance can be used.
 308
 309 ```
 310 [LibraryClasses.common.DXE_DRIVER, LibraryClasses.common.UEFI_DRIVER, LibraryClasses.common.UEFI_APPLICATION]
 311   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 312   BaseCryptLib|CryptoPkg/Library/BaseCryptLib/BaseCryptLib.inf
 313   TlsLib|CryptoPkg/Library/TlsLib/TlsLib.inf
 314   OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLibFull.inf
 315   IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 316 ```
 317
 318 If dynamic linking is used, then all DXE Drivers except CryptoDxe use the
 319 following library mappings. The CryptoDxe module uses the static linking
 320 settings.
 321
 322 ```
 323 [LibraryClasses.common.DXE_DRIVER, LibraryClasses.common.UEFI_DRIVER, LibraryClasses.common.UEFI_APPLICATION]
 324   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 325   BaseCryptLib|CryptoPkg/Library/BaseCryptLibOnProtocolPpi/DxeCryptLib.inf
 326
 327 [Components]
 328   CryptoPkg/Driver/CryptoDxe.inf {
 329     <LibraryClasses>
 330       BaseCryptLib|CryptoPkg/Library/BaseCryptLib/BaseCryptLib.inf
 331       TlsLib|CryptoPkg/Library/TlsLib/TlsLib.inf
 332       OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLibFull.inf
 333       IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 334   }
 335 ```
 336
 337 ### SMM Phase Library Mappings
 338
 339 The SMM Phase supports either static or dynamic linking of cryptographic
 340 services. The following library mappings are recommended for the SMM Phase. It
 341 uses the SMM specific version of the BaseCryptLib and the null version of the
 342 TlsLib.
 343
 344 ```
 345 [LibraryClasses.common.DXE_SMM_DRIVER]
 346   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 347   BaseCryptLib|CryptoPkg/Library/BaseCryptLib/SmmCryptLib.inf
 348   TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
 349   OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
 350   IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 351 ```
 352
 353 If dynamic linking is used, then all SMM Drivers except CryptoSmm use the
 354 following library mappings. The CryptoDxe module uses the static linking
 355 settings.
 356
 357 ```
 358 [LibraryClasses.common.DXE_SMM_DRIVER]
 359   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 360   BaseCryptLib|CryptoPkg/Library/BaseCryptLibOnProtocolPpi/SmmCryptLib.inf
 361
 362 [Components]
 363   CryptoPkg/Driver/CryptoSmm.inf {
 364     <LibraryClasses>
 365       BaseCryptLib|CryptoPkg/Library/BaseCryptLib/SmmCryptLib.inf
 366       TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
 367       OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
 368       IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 369   }
 370 ```
 371
 372 ### UEFI Runtime Driver Library Mappings
 373
 374 UEFI Runtime Drivers only support static linking of cryptographic services.
 375 The following library mappings are recommended for UEFI Runtime Drivers. They
 376 use the runtime specific version of the BaseCryptLib and the null version of the
 377 TlsLib because TLS services are not typically used at runtime.
 378
 379 ```
 380 [LibraryClasses.common.DXE_RUNTIME_DRIVER]
 381   HashApiLib|CryptoPkg/Library/BaseHashApiLib/BaseHashApiLib.inf
 382   BaseCryptLib|CryptoPkg/Library/BaseCryptLib/RuntimeCryptLib.inf
 383   TlsLib|CryptoPkg/Library/TlsLibNull/TlsLibNull.inf
 384   OpensslLib|CryptoPkg/Library/OpensslLib/OpensslLib.inf
 385   IntrinsicLib|CryptoPkg/Library/IntrinsicLib/IntrinsicLib.inf
 386 ```
 387
 388 ### PCD Configuration Settings
 389
 390 There are 2 PCD settings that are used to configure cryptographic services.
 391 `PcdHashApiLibPolicy` is used to configure the hash algorithm provided by the
 392 BaseHashApiLib library instance. `PcdCryptoServiceFamilyEnable` is used to
 393 configure the cryptographic services supported by the CryptoPei, CryptoDxe,
 394 and CryptoSmm modules.
 395
 396 * `gEfiCryptoPkgTokenSpaceGuid.PcdHashApiLibPolicy` - This PCD indicates the
 397   HASH algorithm to use in the BaseHashApiLib to calculate hash of data. The
 398   default hashing algorithm for BaseHashApiLib is set to HASH_ALG_SHA256.
 399   |  Setting   |    Algorithm     |
 400   |------------|------------------|
 401   | 0x00000001 | HASH_ALG_SHA1    |
 402   | 0x00000002 | HASH_ALG_SHA256  |
 403   | 0x00000004 | HASH_ALG_SHA384  |
 404   | 0x00000008 | HASH_ALG_SHA512  |
 405   | 0x00000010 | HASH_ALG_SM3_256 |
 406
 407 * `gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable` - Enable/Disable
 408    the families and individual services produced by the EDK II Crypto
 409    Protocols/PPIs. The default is all services disabled. This Structured PCD is
 410    associated with the `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` structure that is
 411    defined in `Include/Pcd/PcdCryptoServiceFamilyEnable.h`.
 412
 413    There are three layers of priority that determine if a specific family or
 414    individual cryptographic service is actually enabled in the CryptoPei,
 415    CryptoDxe, and CryptoSmm modules.
 416
 417    1) OpensslLib instance selection. When the CryptoPei, CryptoDxe, or CryptoSmm
 418       drivers are built, they are statically linked to an OpensslLib library
 419       instance. If the required cryptographic service is not enabled in the
 420       OpensslLib instance linked, then the service is always disabled.
 421    2) BaseCryptLib instance selection.
 422       * CryptoPei is always linked with the PeiCryptLib instance of the
 423         BaseCryptLib library class. The table above has a column for the
 424         PeiCryptLib. If the family or service is blank, then that family or
 425         service is always disabled.
 426       * CryptoDxe is always linked with the BaseCryptLib instance of the
 427         BaseCryptLib library class. The table above has a column for the
 428         BaseCryptLib. If the family or service is blank, then that family or
 429         service is always disabled.
 430       * CryptoSmm is always linked with the SmmCryptLib instance of the
 431         BaseCryptLib library class. The table above has a column for the
 432         SmmCryptLib. If the family or service is blank, then that family or
 433         service is always disabled.
 434    3) If a family or service is enabled in the OpensslLib instance and it is
 435       enabled in the BaseCryptLib instance, then it can be enabled/disabled
 436       using `PcdCryptoServiceFamilyEnable`. This structured PCD is associated
 437       with the `PCD_CRYPTO_SERVICE_FAMILY_ENABLE` data structure that contains
 438       bit fields for each family of services. All of the families are disabled
 439       by default. An entire family of services can be enabled by setting the
 440       family field to the value `PCD_CRYPTO_SERVICE_ENABLE_FAMILY`. Individual
 441       services can be enabled by setting a single service name (bit) to `TRUE`.
 442       Settings listed later in the DSC file have priority over settings listed
 443       earlier in the DSC file, so it is valid for an entire family to be enabled
 444       first and then for a few individual services to be disabled by setting
 445       those service names to `FALSE`.
 446
 447 #### Common PEI PcdCryptoServiceFamilyEnable Settings
 448
 449 ```
 450   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha256.Family                    | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 451   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha384.Family                    | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 452   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha1.Family                          | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 453   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha256.Family                        | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 454   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha384.Family                        | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 455   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha512.Family                        | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 456   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sm3.Family                           | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 457   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Family                           | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 458   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Pkcs1Verify             | TRUE
 459   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.New                     | TRUE
 460   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Free                    | TRUE
 461   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.SetKey                  | TRUE
 462   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.Pkcs5HashPassword      | TRUE
 463   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Hkdf.Family                          | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 464 ```
 465
 466 #### Common DXE and SMM PcdCryptoServiceFamilyEnable Settings
 467
 468 ```
 469   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha256.Family                        | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 470   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.HmacSha384.Family                        | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 471   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Hkdf.Family                              | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 472   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.Pkcs1v2Encrypt             | TRUE
 473   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.Pkcs5HashPassword          | TRUE
 474   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.Pkcs7Verify                | TRUE
 475   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.VerifyEKUsInPkcs7Signature | TRUE
 476   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.Pkcs7GetSigners            | TRUE
 477   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.Pkcs7FreeSigners           | TRUE
 478   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Pkcs.Services.AuthenticodeVerify         | TRUE
 479   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Random.Family                            | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 480   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Pkcs1Verify                 | TRUE
 481   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.New                         | TRUE
 482   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.Free                        | TRUE
 483   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.SetKey                      | TRUE
 484   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Rsa.Services.GetPublicKeyFromX509        | TRUE
 485   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha1.Family                              | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 486   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha256.Family                            | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 487   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Sha256.Services.HashAll                  | FALSE
 488   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.GetSubjectName             | TRUE
 489   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.GetCommonName              | TRUE
 490   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.GetOrganizationName        | TRUE
 491   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.X509.Services.GetTBSCert                 | TRUE
 492   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Tls.Family                               | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 493   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.TlsSet.Family                            | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 494   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.TlsGet.Family                            | PCD_CRYPTO_SERVICE_ENABLE_FAMILY
 495   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.GetContextSize              | TRUE
 496   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.Init                        | TRUE
 497   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.CbcEncrypt                  | TRUE
 498   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.Aes.Services.CbcDecrypt                  | TRUE
 499   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.AeadAesGcm.Services.Encrypt              | TRUE
 500   gEfiCryptoPkgTokenSpaceGuid.PcdCryptoServiceFamilyEnable.AeadAesGcm.Services.Decrypt              | TRUE
 501 ```