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