]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Protocol/SmartCardEdge.h
projects / mirror_edk2.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
MdePkg: Replace BSD License with BSD+Patent License
[mirror_edk2.git] / MdePkg / Include / Protocol / SmartCardEdge.h
CommitLineData
21bd4958
FT		 1/** @file\r
2 The Smart Card Edge Protocol provides an abstraction for device to provide Smart\r
3 Card support.\r
4\r
5 This protocol allows UEFI applications to interface with a Smart Card during\r
6 boot process for authentication or data signing/decryption, especially if the\r
7 application has to make use of PKI.\r
8\r
497a5fb1 9 Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR>\r
9344f092 10 SPDX-License-Identifier: BSD-2-Clause-Patent\r
21bd4958 11\r
497a5fb1
SZ		 12 @par Revision Reference:\r
13 This Protocol was introduced in UEFI Specification 2.5.\r
14\r
21bd4958
FT		 15**/\r
16\r
17#ifndef __SMART_CARD_EDGE_H__\r
18#define __SMART_CARD_EDGE_H__\r
19\r
20#define EFI_SMART_CARD_EDGE_PROTOCOL_GUID \\r
21 { \\r
22 0xd317f29b, 0xa325, 0x4712, {0x9b, 0xf1, 0xc6, 0x19, 0x54, 0xdc, 0x19, 0x8c} \\r
23 }\r
24\r
25typedef struct _EFI_SMART_CARD_EDGE_PROTOCOL EFI_SMART_CARD_EDGE_PROTOCOL;\r
26\r
27//\r
28// Maximum size for a Smart Card AID (Application IDentifier)\r
29//\r
30#define SCARD_AID_MAXSIZE 0x0010\r
31//\r
32// Size of CSN (Card Serial Number)\r
33//\r
34#define SCARD_CSN_SIZE 0x0010\r
35//\r
36// Current specification version 1.00\r
37//\r
38#define SMART_CARD_EDGE_PROTOCOL_VERSION_1 0x00000100\r
39//\r
40// Parameters type definition\r
41//\r
42typedef UINT8 SMART_CARD_AID[SCARD_AID_MAXSIZE];\r
43typedef UINT8 SMART_CARD_CSN[SCARD_CSN_SIZE];\r
44\r
45//\r
46// Type of data elements in credentials list\r
47//\r
48// value of tag field for header, the number of containers\r
49//\r
50#define SC_EDGE_TAG_HEADER 0x0000\r
51//\r
52// value of tag field for certificate\r
53//\r
54#define SC_EDGE_TAG_CERT 0x0001\r
55//\r
56// value of tag field for key index associated with certificate\r
57//\r
58#define SC_EDGE_TAG_KEY_ID 0x0002\r
59//\r
60// value of tag field for key type\r
61//\r
62#define SC_EDGE_TAG_KEY_TYPE 0x0003\r
63//\r
64// value of tag field for key size\r
65//\r
66#define SC_EDGE_TAG_KEY_SIZE 0x0004\r
67\r
68//\r
69// Length of L fields of TLV items\r
70//\r
71//\r
72// size of L field for header\r
73//\r
74#define SC_EDGE_L_SIZE_HEADER 1\r
75//\r
76// size of L field for certificate (big endian)\r
77//\r
78#define SC_EDGE_L_SIZE_CERT 2\r
79//\r
80// size of L field for key index\r
81//\r
82#define SC_EDGE_L_SIZE_KEY_ID 1\r
83//\r
84// size of L field for key type\r
85//\r
86#define SC_EDGE_L_SIZE_KEY_TYPE 1\r
87//\r
88// size of L field for key size (big endian)\r
89//\r
90#define SC_EDGE_L_SIZE_KEY_SIZE 2\r
91\r
92//\r
93// Some TLV items have a fixed value for L field\r
94//\r
95// value of L field for header\r
96//\r
97#define SC_EDGE_L_VALUE_HEADER 1\r
98//\r
99// value of L field for key index\r
100//\r
101#define SC_EDGE_L_VALUE_KEY_ID 1\r
102//\r
103// value of L field for key type\r
104//\r
105#define SC_EDGE_L_VALUE_KEY_TYPE 1\r
106//\r
107// value of L field for key size\r
108//\r
109#define SC_EDGE_L_VALUE_KEY_SIZE 2\r
110\r
111//\r
112// Possible values for key type\r
113//\r
114//\r
115// RSA decryption\r
116//\r
117#define SC_EDGE_RSA_EXCHANGE 0x01\r
118//\r
119// RSA signature\r
120//\r
121#define SC_EDGE_RSA_SIGNATURE 0x02\r
122//\r
123// ECDSA signature\r
124//\r
125#define SC_EDGE_ECDSA_256 0x03\r
126//\r
127// ECDSA signature\r
128//\r
129#define SC_EDGE_ECDSA_384 0x04\r
130//\r
131// ECDSA signature\r
132//\r
133#define SC_EDGE_ECDSA_521 0x05\r
134//\r
135// ECDH agreement\r
136//\r
137#define SC_EDGE_ECDH_256 0x06\r
138//\r
139// ECDH agreement\r
140//\r
141#define SC_EDGE_ECDH_384 0x07\r
142//\r
143// ECDH agreement\r
144//\r
145#define SC_EDGE_ECDH_521 0x08\r
146\r
147//\r
148// Padding methods GUIDs for signature\r
149//\r
150//\r
151// RSASSA- PKCS#1-V1.5 padding method, for signature\r
152//\r
153#define EFI_PADDING_RSASSA_PKCS1V1P5_GUID \\r
154 { \\r
155 0x9317ec24, 0x7cb0, 0x4d0e, {0x8b, 0x32, 0x2e, 0xd9, 0x20, 0x9c, 0xd8, 0xaf} \\r
156 }\r
157\r
158extern EFI_GUID gEfiPaddingRsassaPkcs1V1P5Guid;\r
159\r
160//\r
161// RSASSA-PSS padding method, for signature\r
162//\r
163#define EFI_PADDING_RSASSA_PSS_GUID \\r
164 { \\r
165 0x7b2349e0, 0x522d, 0x4f8e, {0xb9, 0x27, 0x69, 0xd9, 0x7c, 0x9e, 0x79, 0x5f} \\r
166 }\r
167\r
168extern EFI_GUID gEfiPaddingRsassaPssGuid;\r
169\r
170//\r
171// Padding methods GUIDs for decryption\r
172//\r
173//\r
174// No padding, for decryption\r
175//\r
176#define EFI_PADDING_NONE_GUID \\r
177 { \\r
178 0x3629ddb1, 0x228c, 0x452e, {0xb6, 0x16, 0x09, 0xed, 0x31, 0x6a, 0x97, 0x00} \\r
179 }\r
180\r
181extern EFI_GUID gEfiPaddingNoneGuid;\r
182\r
183//\r
184// RSAES-PKCS#1-V1.5 padding, for decryption\r
185//\r
186#define EFI_PADDING_RSAES_PKCS1V1P5_GUID \\r
187 { \\r
188 0xe1c1d0a9, 0x40b1, 0x4632, {0xbd, 0xcc, 0xd9, 0xd6, 0xe5, 0x29, 0x56, 0x31} \\r
189 }\r
190\r
191extern EFI_GUID gEfiPaddingRsaesPkcs1V1P5Guid;\r
192\r
193//\r
194// RSAES-OAEP padding, for decryption\r
195//\r
196#define EFI_PADDING_RSAES_OAEP_GUID \\r
197 { \\r
198 0xc1e63ac4, 0xd0cf, 0x4ce6, {0x83, 0x5b, 0xee, 0xd0, 0xe6, 0xa8, 0xa4, 0x5b} \\r
199 }\r
200\r
201extern EFI_GUID gEfiPaddingRsaesOaepGuid;\r
202\r
203/**\r
204 This function retrieves the context driver.\r
205\r
206 The GetContextfunction returns the context of the protocol, the application\r
207 identifiers supported by the protocol and the number and the CSN unique identifier\r
208 of Smart Cards that are present and supported by protocol.\r
209\r
210 If AidTableSize, AidTable, CsnTableSize, CsnTable or VersionProtocol is NULL,\r
211 the function does not fail but does not fill in such variables.\r
212\r
213 In case AidTableSize indicates a buffer too small to hold all the protocol AID table,\r
214 only the first AidTableSize items of the table are returned in AidTable.\r
215\r
216 In case CsnTableSize indicates a buffer too small to hold the entire table of\r
217 Smart Card CSN present, only the first CsnTableSize items of the table are returned\r
218 in CsnTable.\r
219\r
220 VersionScEdgeProtocol returns the version of the EFI_SMART_CARD_EDGE_PROTOCOL this\r
221 driver uses. For this protocol specification value is SMART_CARD_EDGE_PROTOCOL_VERSION_1.\r
222\r
223 In case of Smart Card removal the internal CSN list is immediately updated, even if\r
224 a connection is opened with that Smart Card.\r
225\r
226 @param[in] This Indicates a pointer to the calling context.\r
227 @param[out] NumberAidSupported Number of AIDs this protocol supports.\r
228 @param[in, out] AidTableSize On input, number of items allocated for the\r
229 AID table. On output, number of items returned\r
230 by protocol.\r
231 @param[out] AidTable Table of the AIDs supported by the protocol.\r
232 @param[out] NumberSCPresent Number of currently present Smart Cards that\r
233 are supported by protocol.\r
234 @param[in, out] CsnTableSize On input, the number of items the buffer CSN\r
235 table can contain. On output, the number of\r
236 items returned by the protocol.\r
237 @param[out] CsnTable Table of the CSN of the Smart Card present and\r
238 supported by protocol.\r
239 @param[out] VersionScEdgeProtocol EFI_SMART_CARD_EDGE_PROTOCOL version.\r
240\r
241 @retval EFI_SUCCESS The requested command completed successfully.\r
242 @retval EFI_INVALID_PARAMETER This is NULL.\r
243 @retval EFI_INVALID_PARAMETER NumberSCPresent is NULL.\r
244\r
245**/\r
246typedef\r
247EFI_STATUS\r
248(EFIAPI *EFI_SMART_CARD_EDGE_GET_CONTEXT) (\r
249 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
250 OUT UINTN *NumberAidSupported,\r
251 IN OUT UINTN *AidTableSize OPTIONAL,\r
252 OUT SMART_CARD_AID *AidTable OPTIONAL,\r
253 OUT UINTN *NumberSCPresent,\r
254 IN OUT UINTN *CsnTableSize OPTIONAL,\r
255 OUT SMART_CARD_CSN *CsnTable OPTIONAL,\r
256 OUT UINT32 *VersionScEdgeProtocol OPTIONAL\r
257 );\r
258\r
259/**\r
260 This function establish a connection with a Smart Card the protocol support.\r
261\r
262 In case of success the SCardHandle can be used.\r
263\r
264 If the ScardCsn is NULL the connection is established with the first Smart Card\r
265 the protocol finds in its table of Smart Card present and supported. Else it\r
266 establish context with the Smart Card whose CSN given by ScardCsn.\r
267\r
268 If ScardAid is not NULL the function returns the Smart Card AID the protocol supports.\r
269 After a successful connect the SCardHandle will remain existing even in case Smart Card\r
270 removed from Smart Card reader, but all function invoking this SCardHandle will fail.\r
271 SCardHandle is released only on Disconnect.\r
272\r
273 @param[in] This Indicates a pointer to the calling context.\r
274 @param[out] SCardHandle Handle on Smart Card connection.\r
275 @param[in] ScardCsn CSN of the Smart Card the connection has to be\r
276 established.\r
277 @param[out] ScardAid AID of the Smart Card the connection has been\r
278 established.\r
279\r
280 @retval EFI_SUCCESS The requested command completed successfully.\r
281 @retval EFI_INVALID_PARAMETER This is NULL.\r
282 @retval EFI_INVALID_PARAMETER SCardHandle is NULL.\r
283 @retval EFI_NO_MEDIA No Smart Card supported by protocol is present,\r
284 Smart Card with CSN ScardCsn or Reader has been\r
285 removed. A Disconnect should be performed.\r
286\r
287**/\r
288typedef\r
289EFI_STATUS\r
290(EFIAPI *EFI_SMART_CARD_EDGE_CONNECT) (\r
291 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
292 OUT EFI_HANDLE *SCardHandle,\r
293 IN UINT8 *ScardCsn OPTIONAL,\r
294 OUT UINT8 *ScardAid OPTIONAL\r
295 );\r
296\r
297/**\r
298 This function releases a connection previously established by Connect.\r
299\r
300 The Disconnect function releases the connection previously established by\r
301 a Connect. In case the Smart Card or the Smart Card reader has been removed\r
302 before this call, this function returns EFI_SUCCESS.\r
303\r
304 @param[in] This Indicates a pointer to the calling context.\r
305 @param[in] SCardHandle Handle on Smart Card connection to release.\r
306\r
307 @retval EFI_SUCCESS The requested command completed successfully.\r
308 @retval EFI_INVALID_PARAMETER This is NULL.\r
309 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
310\r
311**/\r
312typedef\r
313EFI_STATUS\r
314(EFIAPI *EFI_SMART_CARD_EDGE_DISCONNECT) (\r
315 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
316 IN EFI_HANDLE SCardHandle\r
317 );\r
318\r
319/**\r
320 This function returns the Smart Card serial number.\r
321\r
322 @param[in] This Indicates a pointer to the calling context.\r
323 @param[in] SCardHandle Handle on Smart Card connection.\r
324 @param[out] Csn The Card Serial number, 16 bytes array.\r
325\r
326 @retval EFI_SUCCESS The requested command completed successfully.\r
327 @retval EFI_INVALID_PARAMETER This is NULL.\r
328 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
329 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
330 has been removed. A Disconnect should be performed.\r
331\r
332**/\r
333typedef\r
334EFI_STATUS\r
335(EFIAPI *EFI_SMART_CARD_EDGE_GET_CSN) (\r
336 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
337 IN EFI_HANDLE SCardHandle,\r
338 OUT UINT8 Csn[SCARD_CSN_SIZE]\r
339 );\r
340\r
341/**\r
342 This function returns the name of the Smart Card reader used for this connection.\r
343\r
344 @param[in] This Indicates a pointer to the calling context.\r
345 @param[in] SCardHandle Handle on Smart Card connection.\r
346 @param[in, out] ReaderNameLength On input, a pointer to the variable that holds\r
347 the maximal size, in bytes, of ReaderName.\r
348 On output, the required size, in bytes, for ReaderName.\r
349 @param[out] ReaderName A pointer to a NULL terminated string that will\r
350 contain the reader name.\r
351\r
352 @retval EFI_SUCCESS The requested command completed successfully.\r
353 @retval EFI_INVALID_PARAMETER This is NULL.\r
354 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
355 @retval EFI_INVALID_PARAMETER ReaderNameLength is NULL.\r
356 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
357 has been removed. A Disconnect should be performed.\r
358\r
359**/\r
360typedef\r
361EFI_STATUS\r
362(EFIAPI *EFI_SMART_CARD_EDGE_GET_READER_NAME) (\r
363 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
364 IN EFI_HANDLE SCardHandle,\r
365 IN OUT UINTN *ReaderNameLength,\r
366 OUT CHAR16 *ReaderName OPTIONAL\r
367 );\r
368\r
369/**\r
370 This function authenticates a Smart Card user by presenting a PIN code.\r
371\r
372 The VerifyPinfunction presents a PIN code to the Smart Card.\r
373\r
374 If Smart Card found the PIN code correct the user is considered authenticated\r
375 to current application, and the function returns TRUE.\r
376\r
377 Negative or null PinSize value rejected if PinCodeis not NULL.\r
378\r
379 A NULL PinCodebuffer means the application didn't know the PIN, in that case:\r
380 - If PinSize value is negative the caller only wants to know if the current\r
381 chain of the elements Smart Card Edge protocol, Smart Card Reader protocol\r
382 and Smart Card Reader supports the Secure Pin Entry PCSC V2 functionality.\r
383 - If PinSize value is positive or null the caller ask to perform the verify\r
384 PIN using the Secure PIN Entry functionality.\r
385\r
386 In PinCode buffer, the PIN value is always given in plaintext, in case of secure\r
387 messaging the SMART_CARD_EDGE_PROTOCOL will be in charge of all intermediate\r
388 treatments to build the correct Smart Card APDU.\r
389\r
390 @param[in] This Indicates a pointer to the calling context.\r
391 @param[in] SCardHandle Handle on Smart Card connection.\r
392 @param[in] PinSize PIN code buffer size.\r
393 @param[in] PinCode PIN code to present to the Smart Card.\r
394 @param[out] PinResult Result of PIN code presentation to the Smart Card.\r
395 TRUE when Smard Card founds the PIN code correct.\r
396 @param[out] RemainingAttempts Number of attempts still possible.\r
397\r
398 @retval EFI_SUCCESS The requested command completed successfully.\r
399 @retval EFI_UNSUPPORTED Pinsize < 0 and Secure PIN Entry functionality not\r
400 supported.\r
401 @retval EFI_INVALID_PARAMETER This is NULL.\r
402 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
403 @retval EFI_INVALID_PARAMETER Bad value for PinSize: value not supported by Smart\r
404 Card or, negative with PinCode not null.\r
405 @retval EFI_INVALID_PARAMETER PinResult is NULL.\r
406 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
407 has been removed. A Disconnect should be performed.\r
408\r
409**/\r
410typedef\r
411EFI_STATUS\r
412(EFIAPI *EFI_SMART_CARD_EDGE_VERIFY_PIN) (\r
413 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
414 IN EFI_HANDLE SCardHandle,\r
415 IN INT32 PinSize,\r
416 IN UINT8 *PinCode,\r
417 OUT BOOLEAN *PinResult,\r
418 OUT UINT32 *RemainingAttempts OPTIONAL\r
419 );\r
420\r
421/**\r
422 This function gives the remaining number of attempts for PIN code presentation.\r
423\r
424 The number of attempts to present a correct PIN is limited and depends on Smart\r
425 Card and on PIN.\r
426\r
427 This function will retrieve the number of remaining possible attempts.\r
428\r
429 @param[in] This Indicates a pointer to the calling context.\r
430 @param[in] SCardHandle Handle on Smart Card connection.\r
431 @param[out] RemainingAttempts Number of attempts still possible.\r
432\r
433 @retval EFI_SUCCESS The requested command completed successfully.\r
434 @retval EFI_INVALID_PARAMETER This is NULL.\r
435 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
436 @retval EFI_INVALID_PARAMETER RemainingAttempts is NULL.\r
437 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
438 has been removed. A Disconnect should be performed.\r
439\r
440**/\r
441typedef\r
442EFI_STATUS\r
443(EFIAPI *EFI_SMART_CARD_EDGE_GET_PIN_REMAINING) (\r
444 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
445 IN EFI_HANDLE SCardHandle,\r
446 OUT UINT32 *RemainingAttempts\r
447 );\r
448\r
449/**\r
450 This function returns a specific data from Smart Card.\r
451\r
452 The function is generic for any kind of data, but driver and application must\r
453 share an EFI_GUID that identify the data.\r
454\r
455 @param[in] This Indicates a pointer to the calling context.\r
456 @param[in] SCardHandle Handle on Smart Card connection.\r
457 @param[in] DataId The type identifier of the data to get.\r
458 @param[in, out] DataSize On input, in bytes, the size of Data. On output,\r
459 in bytes, the size of buffer required to store\r
460 the specified data.\r
461 @param[out] Data The data buffer in which the data is returned.\r
462 The type of the data buffer is associated with\r
463 the DataId. Ignored if *DataSize is 0.\r
464\r
465 @retval EFI_SUCCESS The requested command completed successfully.\r
466 @retval EFI_INVALID_PARAMETER This is NULL.\r
467 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
468 @retval EFI_INVALID_PARAMETER DataId is NULL.\r
469 @retval EFI_INVALID_PARAMETER DataSize is NULL.\r
470 @retval EFI_INVALID_PARAMETER Data is NULL, and *DataSize is not zero.\r
471 @retval EFI_NOT_FOUND DataId unknown for this driver.\r
472 @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the specified\r
473 data and the required size is returned in DataSize.\r
474 @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled.\r
475 PIN not verified.\r
476 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
477 has been removed. A Disconnect should be performed.\r
478\r
479**/\r
480typedef\r
481EFI_STATUS\r
482(EFIAPI *EFI_SMART_CARD_EDGE_GET_DATA) (\r
483 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
484 IN EFI_HANDLE SCardHandle,\r
485 IN EFI_GUID *DataId,\r
486 IN OUT UINTN *DataSize,\r
487 OUT VOID *Data OPTIONAL\r
488 );\r
489\r
490/**\r
491 This function retrieve credentials store into the Smart Card.\r
492\r
493 The function returns a series of items in TLV (Tag Length Value) format.\r
494\r
495 First TLV item is the header item that gives the number of following\r
496 containers (0x00, 0x01, Nb containers).\r
497\r
498 All these containers are a series of 4 TLV items:\r
499 - The certificate item (0x01, certificate size, certificate)\r
500 - The Key identifier item (0x02, 0x01, key index)\r
501 - The key type item (0x03, 0x01, key type)\r
502 - The key size item (0x04, 0x02, key size), key size in number of bits.\r
503 Numeric multi-bytes values are on big endian format, most significant byte first:\r
504 - The L field value for certificate (2 bytes)\r
505 - The L field value for key size (2 bytes)\r
506 - The value field for key size (2 bytes)\r
507\r
508 @param[in] This Indicates a pointer to the calling context.\r
509 @param[in] SCardHandle Handle on Smart Card connection.\r
510 @param[in, out] CredentialSize On input, in bytes, the size of buffer to store\r
511 the list of credential.\r
512 On output, in bytes, the size of buffer required\r
513 to store the entire list of credentials.\r
514\r
515 @param[out] CredentialList List of credentials stored into the Smart Card.\r
516 A list of TLV (Tag Length Value) elements organized\r
517 in containers array.\r
518\r
519 @retval EFI_SUCCESS The requested command completed successfully.\r
520 @retval EFI_INVALID_PARAMETER This is NULL.\r
521 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
522 @retval EFI_INVALID_PARAMETER CredentialSize is NULL.\r
523 @retval EFI_INVALID_PARAMETER CredentialList is NULL, if CredentialSize is not zero.\r
524 @retval EFI_BUFFER_TOO_SMALL The size of CredentialList is too small for the\r
525 specified data and the required size is returned in\r
526 CredentialSize.\r
527 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
528 has been removed. A Disconnect should be performed.\r
529\r
530**/\r
531typedef\r
532EFI_STATUS\r
533(EFIAPI *EFI_SMART_CARD_EDGE_GET_CREDENTIAL) (\r
534 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
535 IN EFI_HANDLE SCardHandle,\r
536 IN OUT UINTN *CredentialSize,\r
537 OUT UINT8 *CredentialList OPTIONAL\r
538 );\r
539\r
540/**\r
541 This function signs an already hashed data with a Smart Card private key.\r
542\r
543 This function signs data, actually it is the hash of these data that is given\r
544 to the function.\r
545\r
546 SignatureData buffer shall be big enough for signature. Signature size is\r
547 function key size and key type.\r
548\r
549 @param[in] This Indicates a pointer to the calling context.\r
550 @param[in] SCardHandle Handle on Smart Card connection.\r
551 @param[in] KeyId Identifier of the key container, retrieved\r
552 in a key index item of credentials.\r
553 @param[in] KeyType The key type, retrieved in a key type item of\r
554 credentials.\r
555\r
556 @param[in] HashAlgorithm Hash algorithm used to hash the, one of:\r
557 - EFI_HASH_ALGORITHM_SHA1_GUID\r
558 - EFI_HASH_ALGORITHM_SHA256_GUID\r
559 - EFI_HASH_ALGORITHM_SHA384_GUID\r
560 - EFI_HASH_ALGORITHM_SHA512_GUID\r
561 @param[in] PaddingMethod Padding method used jointly with hash algorithm,\r
562 one of:\r
563 - EFI_PADDING_RSASSA_PKCS1V1P5_GUID\r
564 - EFI_PADDING_RSASSA_PSS_GUID\r
565 @param[in] HashedData Hash of the data to sign. Size is function of the\r
566 HashAlgorithm.\r
567\r
568 @param[out] SignatureData Resulting signature with private key KeyId. Size\r
569 is function of the KeyType and key size retrieved\r
570 in the associated key size item of credentials.\r
571\r
572 @retval EFI_SUCCESS The requested command completed successfully.\r
573 @retval EFI_INVALID_PARAMETER This is NULL.\r
574 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
575 @retval EFI_INVALID_PARAMETER KeyId is not valid.\r
576 @retval EFI_INVALID_PARAMETER KeyType is not valid or not corresponding to KeyId.\r
577 @retval EFI_INVALID_PARAMETER HashAlgorithm is NULL.\r
578 @retval EFI_INVALID_PARAMETER HashAlgorithm is not valid.\r
579 @retval EFI_INVALID_PARAMETER PaddingMethod is NULL.\r
580 @retval EFI_INVALID_PARAMETER PaddingMethod is not valid.\r
581 @retval EFI_INVALID_PARAMETER HashedData is NULL.\r
582 @retval EFI_INVALID_PARAMETER SignatureData is NULL.\r
583 @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled.\r
584 PIN not verified.\r
585 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
586 has been removed. A Disconnect should be performed.\r
587\r
588**/\r
589typedef\r
590EFI_STATUS\r
591(EFIAPI *EFI_SMART_CARD_EDGE_SIGN_DATA) (\r
592 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
593 IN EFI_HANDLE SCardHandle,\r
594 IN UINTN KeyId,\r
595 IN UINTN KeyType,\r
596 IN EFI_GUID *HashAlgorithm,\r
597 IN EFI_GUID *PaddingMethod,\r
598 IN UINT8 *HashedData,\r
599 OUT UINT8 *SignatureData\r
600 );\r
601\r
602/**\r
603 This function decrypts data with a PKI/RSA Smart Card private key.\r
604\r
605 The function decrypts some PKI/RSA encrypted data with private key securely\r
606 stored into the Smart Card.\r
607\r
608 The KeyId must reference a key of type SC_EDGE_RSA_EXCHANGE.\r
609\r
610 @param[in] This Indicates a pointer to the calling context.\r
611 @param[in] SCardHandle Handle on Smart Card connection.\r
612 @param[in] KeyId Identifier of the key container, retrieved\r
613 in a key index item of credentials.\r
614 @param[in] HashAlgorithm Hash algorithm used to hash the, one of:\r
615 - EFI_HASH_ALGORITHM_SHA1_GUID\r
616 - EFI_HASH_ALGORITHM_SHA256_GUID\r
617 - EFI_HASH_ALGORITHM_SHA384_GUID\r
618 - EFI_HASH_ALGORITHM_SHA512_GUID\r
619 @param[in] PaddingMethod Padding method used jointly with hash algorithm,\r
620 one of:\r
621 - EFI_PADDING_NONE_GUID\r
622 - EFI_PADDING_RSAES_PKCS1V1P5_GUID\r
623 - EFI_PADDING_RSAES_OAEP_GUID\r
624 @param[in] EncryptedSize Size of data to decrypt.\r
625 @param[in] EncryptedData Data to decrypt\r
626 @param[in, out] PlaintextSize On input, in bytes, the size of buffer to store\r
627 the decrypted data.\r
628 On output, in bytes, the size of buffer required\r
629 to store the decrypted data.\r
630 @param[out] PlaintextData Buffer for decrypted data, padding removed.\r
631\r
632 @retval EFI_SUCCESS The requested command completed successfully.\r
633 @retval EFI_INVALID_PARAMETER This is NULL.\r
634 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
635 @retval EFI_INVALID_PARAMETER KeyId is not valid or associated key not of type\r
636 SC_EDGE_RSA_EXCHANGE.\r
637 @retval EFI_INVALID_PARAMETER HashAlgorithm is NULL.\r
638 @retval EFI_INVALID_PARAMETER HashAlgorithm is not valid.\r
639 @retval EFI_INVALID_PARAMETER PaddingMethod is NULL.\r
640 @retval EFI_INVALID_PARAMETER PaddingMethod is not valid.\r
641 @retval EFI_INVALID_PARAMETER EncryptedSize is 0.\r
642 @retval EFI_INVALID_PARAMETER EncryptedData is NULL.\r
643 @retval EFI_INVALID_PARAMETER PlaintextSize is NULL.\r
644 @retval EFI_INVALID_PARAMETER PlaintextData is NULL.\r
645 @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled.\r
646 PIN not verified.\r
647 @retval EFI_BUFFER_TOO_SMALL PlaintextSize is too small for the plaintext data\r
648 and the required size is returned in PlaintextSize.\r
649 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
650 has been removed. A Disconnect should be performed.\r
651\r
652**/\r
653typedef\r
654EFI_STATUS\r
655(EFIAPI *EFI_SMART_CARD_EDGE_DECRYPT_DATA) (\r
656 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
657 IN EFI_HANDLE SCardHandle,\r
658 IN UINTN KeyId,\r
659 IN EFI_GUID *HashAlgorithm,\r
660 IN EFI_GUID *PaddingMethod,\r
661 IN UINTN EncryptedSize,\r
662 IN UINT8 *EncryptedData,\r
663 IN OUT UINTN *PlaintextSize,\r
664 OUT UINT8 *PlaintextData\r
665 );\r
666\r
667/**\r
668 This function performs a secret Diffie Hellman agreement calculation that would\r
669 be used to derive a symmetric encryption / decryption key.\r
670\r
671 The function compute a DH agreement that should be diversified togenerate a symmetric\r
672 key to proceed encryption or decryption.\r
673\r
674 The application and the Smart Card shall agree on the diversification process.\r
675\r
676 The KeyId must reference a key of one of the types: SC_EDGE_ECDH_256, SC_EDGE_ECDH_384\r
677 or SC_EDGE_ECDH_521.\r
678\r
679 @param[in] This Indicates a pointer to the calling context.\r
680 @param[in] SCardHandle Handle on Smart Card connection.\r
681 @param[in] KeyId Identifier of the key container, retrieved\r
682 in a key index item of credentials.\r
683 @param[in] dataQx Public key x coordinate. Size is the same as\r
684 key size for KeyId. Stored in big endian format.\r
685 @param[in] dataQy Public key y coordinate. Size is the same as\r
686 key size for KeyId. Stored in big endian format.\r
687 @param[out] DHAgreement Buffer for DH agreement computed. Size must be\r
688 bigger or equal to key size for KeyId.\r
689\r
690 @retval EFI_SUCCESS The requested command completed successfully.\r
691 @retval EFI_INVALID_PARAMETER This is NULL.\r
692 @retval EFI_INVALID_PARAMETER No connection for SCardHandle value.\r
693 @retval EFI_INVALID_PARAMETER KeyId is not valid.\r
694 @retval EFI_INVALID_PARAMETER dataQx is NULL.\r
695 @retval EFI_INVALID_PARAMETER dataQy is NULL.\r
696 @retval EFI_INVALID_PARAMETER DHAgreement is NULL.\r
697 @retval EFI_ACCESS_DENIED Operation not performed, conditions not fulfilled.\r
698 PIN not verified.\r
699 @retval EFI_NO_MEDIA Smart Card or Reader of SCardHandle connection\r
700 has been removed. A Disconnect should be performed.\r
701\r
702**/\r
703typedef\r
704EFI_STATUS\r
705(EFIAPI *EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT) (\r
706 IN EFI_SMART_CARD_EDGE_PROTOCOL *This,\r
707 IN EFI_HANDLE SCardHandle,\r
708 IN UINTN KeyId,\r
709 IN UINT8 *dataQx,\r
710 IN UINT8 *dataQy,\r
711 OUT UINT8 *DHAgreement\r
712 );\r
713\r
714///\r
715/// Smart card aware application invokes this protocol to get access to an inserted\r
716/// smart card in the reader or to the reader itself.\r
717///\r
718struct _EFI_SMART_CARD_EDGE_PROTOCOL {\r
719 EFI_SMART_CARD_EDGE_GET_CONTEXT GetContext;\r
720 EFI_SMART_CARD_EDGE_CONNECT Connect;\r
721 EFI_SMART_CARD_EDGE_DISCONNECT Disconnect;\r
722 EFI_SMART_CARD_EDGE_GET_CSN GetCsn;\r
723 EFI_SMART_CARD_EDGE_GET_READER_NAME GetReaderName;\r
724 EFI_SMART_CARD_EDGE_VERIFY_PIN VerifyPin;\r
725 EFI_SMART_CARD_EDGE_GET_PIN_REMAINING GetPinRemaining;\r
726 EFI_SMART_CARD_EDGE_GET_DATA GetData;\r
727 EFI_SMART_CARD_EDGE_GET_CREDENTIAL GetCredential;\r
728 EFI_SMART_CARD_EDGE_SIGN_DATA SignData;\r
729 EFI_SMART_CARD_EDGE_DECRYPT_DATA DecryptData;\r
730 EFI_SMART_CARD_EDGE_BUILD_DH_AGREEMENT BuildDHAgreement;\r
731};\r
732\r
733extern EFI_GUID gEfiSmartCardEdgeProtocolGuid;\r
734\r
735#endif\r
736\r
EFI Development Kit II mirror for PVE