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