| /** @file |
| The UEFI Smart Card Reader Protocol provides an abstraction for device to provide |
| smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup |
| specifications and provides an API to applications willing to communicate with a |
| smart card or a smart card reader. |
| |
| Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| **/ |
| |
| #ifndef __SMART_CARD_READER_H__ |
| #define __SMART_CARD_READER_H__ |
| |
| #define EFI_SMART_CARD_READER_PROTOCOL_GUID \ |
| { \ |
| 0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \ |
| } |
| |
| typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL; |
| |
| // |
| // Codes for access mode |
| // |
| #define SCARD_AM_READER 0x0001 // Exclusive access to reader |
| #define SCARD_AM_CARD 0x0002 // Exclusive access to card |
| // |
| // Codes for card action |
| // |
| #define SCARD_CA_NORESET 0x0000 // Don't reset card |
| #define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset |
| #define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset |
| #define SCARD_CA_UNPOWER 0x0003 // Power off the card |
| #define SCARD_CA_EJECT 0x0004 // Eject the card |
| // |
| // Protocol types |
| // |
| #define SCARD_PROTOCOL_UNDEFINED 0x0000 |
| #define SCARD_PROTOCOL_T0 0x0001 |
| #define SCARD_PROTOCOL_T1 0x0002 |
| #define SCARD_PROTOCOL_RAW 0x0004 |
| // |
| // Codes for state type |
| // |
| #define SCARD_UNKNOWN 0x0000 /* state is unknown */ |
| #define SCARD_ABSENT 0x0001 /* Card is absent */ |
| #define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/ |
| #define SCARD_ACTIVE 0x0003 /* Card is present and powered */ |
| // |
| // Macro to generate a ControlCode & PC/SC part 10 control code |
| // |
| #define SCARD_CTL_CODE(code) (0x42000000 + (code)) |
| #define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400) |
| |
| /** |
| This function requests connection to the smart card or the reader, using the |
| appropriate reset type and protocol. |
| |
| The SCardConnectfunction requests access to the smart card or the reader. Upon |
| success, it is then possible to call SCardTransmit. |
| |
| If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to |
| SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function |
| fails with EFI_INVALID_PARAMETER. |
| |
| @param[in] This Indicates a pointer to the calling context. |
| @param[in] AccessMode Codes of access mode. |
| @param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or |
| SCARD_CA_WARMRESET. |
| @param[in] PreferredProtocols Bitmask of acceptable protocols. |
| @param[out] ActiveProtocol A flag that indicates the active protocol. |
| |
| @retval EFI_SUCCESS The requested command completed successfully. |
| @retval EFI_INVALID_PARAMETER This is NULL |
| @retval EFI_INVALID_PARAMETER AccessMode is not valid. |
| @retval EFI_INVALID_PARAMETER CardAction is not valid. |
| @retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/ |
| PreferredProtocols. |
| @retval EFI_NOT_READY A smart card is inserted but failed to return an ATR. |
| @retval EFI_UNSUPPORTED PreferredProtocols does not contain an available |
| protocol to use. |
| @retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is |
| no smart card inserted. |
| @retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall. |
| @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SMART_CARD_READER_CONNECT) ( |
| IN EFI_SMART_CARD_READER_PROTOCOL *This, |
| IN UINT32 AccessMode, |
| IN UINT32 CardAction, |
| IN UINT32 PreferredProtocols, |
| OUT UINT32 *ActiveProtocol |
| ); |
| |
| /** |
| This function releases a connection previously taken by SCardConnect. |
| |
| The SCardDisconnect function releases the lock previously taken by SCardConnect. |
| In case the smart card has been removed before this call, thisfunction |
| returns EFI_SUCCESS. If there is no previous call to SCardConnect, this |
| function returns EFI_SUCCESS. |
| |
| @param[in] This Indicates a pointer to the calling context. |
| @param[in] CardAction Codes for card action. |
| |
| @retval EFI_SUCCESS The requested command completed successfully. |
| @retval EFI_INVALID_PARAMETER This is NULL |
| @retval EFI_INVALID_PARAMETER CardAction value is unknown. |
| @retval EFI_UNSUPPORTED Reader does not support Eject card feature |
| (disconnect was not performed). |
| @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SMART_CARD_READER_DISCONNECT) ( |
| IN EFI_SMART_CARD_READER_PROTOCOL *This, |
| IN UINT32 CardAction |
| ); |
| |
| /** |
| This function retrieves some basic information about the smart card and reader. |
| |
| The SCardStatusfunction retrieves basic reader and card information. |
| |
| If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but |
| does not fill in such variables. |
| |
| If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered |
| as valid. |
| |
| @param[in] This Indicates a pointer to the calling context. |
| @param[out] ReaderName A pointer to a NULL terminated string that will |
| contain the reader name. |
| @param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the |
| maximal size, in bytes,of ReaderName. |
| On output, the required size, in bytes, for ReaderName. |
| @param[out] State Current state of the smart card reader. |
| @param[out] CardProtocol Current protocol used to communicate with the smart card. |
| @param[out] Atr A pointer to retrieve the ATR of the smart card. |
| @param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes, |
| of Atr(usually 33). |
| On output, the required size, inbytes, for the smart |
| card ATR. |
| |
| @retval EFI_SUCCESS The requested command completed successfully. |
| @retval EFI_INVALID_PARAMETER This is NULL |
| @retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL |
| @retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL |
| @retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name. |
| ReaderNameLength has been updated to the required value. |
| @retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR. |
| AtrLength has been updated to the required value. |
| @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SMART_CARD_READER_STATUS) ( |
| IN EFI_SMART_CARD_READER_PROTOCOL *This, |
| OUT CHAR16 *ReaderName OPTIONAL, |
| IN OUT UINTN *ReaderNameLength OPTIONAL, |
| OUT UINT32 *State OPTIONAL, |
| OUT UINT32 *CardProtocol OPTIONAL, |
| OUT UINT8 *Atr OPTIONAL, |
| IN OUT UINTN *AtrLength OPTIONAL |
| ); |
| |
| /** |
| This function sends a command to the card or reader and returns its response. |
| |
| The protocol to use to communicate with the smart card has been selected through |
| SCardConnectcall. |
| |
| In case RAPDULength indicates a buffer too small to holdthe response APDU, the |
| function fails with EFI_BUFFER_TOO_SMALL. |
| |
| @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. |
| @param[in] CAPDU A pointer to a byte array thatcontains the Command |
| APDU to send to the smart card or reader. |
| @param[in] CAPDULength Command APDU size, in bytes. |
| @param[out] RAPDU A pointer to a byte array that will contain the |
| Response APDU. |
| @param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response |
| APDU. |
| On output, the size, in bytes, of the Response APDU. |
| |
| @retval EFI_SUCCESS The requested command completed successfully. |
| @retval EFI_INVALID_PARAMETER This is NULL. |
| @retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0. |
| @retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU. |
| RAPDULength has been updated to the required value. |
| @retval EFI_NO_MEDIA There is no card in the reader. |
| @retval EFI_NOT_READY Card is not powered. |
| @retval EFI_PROTOCOL_ERROR A protocol error has occurred. |
| @retval EFI_TIMEOUT The reader did not respond. |
| @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. |
| @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SMART_CARD_READER_TRANSMIT) ( |
| IN EFI_SMART_CARD_READER_PROTOCOL *This, |
| IN UINT8 *CAPDU, |
| IN UINTN CAPDULength, |
| OUT UINT8 *RAPDU, |
| IN OUT UINTN *RAPDULength |
| ); |
| |
| /** |
| This function provides direct access to the reader. |
| |
| This function gives direct control to send commands to the driver or the reader. |
| The ControlCode to use is vendor dependant; the only standard code defined is |
| the one to get PC/SC part 10 features. |
| |
| InBuffer and Outbuffer may be NULL when ControlCode operation does not require |
| them. |
| |
| @param[in] This Indicates a pointer to the calling context. |
| @param[in] ControlCode The control code for the operation to perform. |
| @param[in] InBuffer A pointer to the input parameters. |
| @param[in] InBufferLength Size, in bytes, of input parameters. |
| @param[out] OutBuffer A pointer to the output parameters. |
| @param[in, out] OutBufferLength On input, maximal size, in bytes, to store output |
| parameters. |
| On output, the size, in bytes, of output parameters. |
| |
| @retval EFI_SUCCESS The requested command completed successfully. |
| @retval EFI_INVALID_PARAMETER This is NULL. |
| @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but: |
| InBuffer is NULL or InBufferLenth is NULL or |
| InBuffer is not NULL but InBufferLenth is less than |
| expected. |
| @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL. |
| @retval EFI_UNSUPPORTED ControlCode is not supported. |
| @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output |
| parameters. |
| OutBufferLength has been updated to the required value. |
| @retval EFI_NO_MEDIA There is no card in the reader and the control code |
| specified requires one. |
| @retval EFI_NOT_READY ControlCode requires a powered card to operate. |
| @retval EFI_PROTOCOL_ERROR A protocol error has occurred. |
| @retval EFI_TIMEOUT The reader did not respond. |
| @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. |
| @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SMART_CARD_READER_CONTROL) ( |
| IN EFI_SMART_CARD_READER_PROTOCOL *This, |
| IN UINT32 ControlCode, |
| IN UINT8 *InBuffer OPTIONAL, |
| IN UINTN InBufferLength OPTIONAL, |
| OUT UINT8 *OutBuffer OPTIONAL, |
| IN OUT UINTN *OutBufferLength OPTIONAL |
| ); |
| |
| /** |
| This function retrieves a reader or smart card attribute. |
| |
| Possibly supported attrib values are listed in "PC/SC specification, Part 3: |
| Requirements for PC-Connected Interface Devices". |
| |
| @param[in] This Indicates a pointer to the calling context. |
| @param[in] Attrib Identifier for the attribute to retrieve. |
| @param[out] OutBuffer A pointer to a buffer that will contain |
| attribute data. |
| @param[in, out] OutBufferLength On input, maximal size, in bytes, to store |
| attribute data. |
| On output, the size, in bytes, of attribute |
| data. |
| |
| @retval EFI_SUCCESS The requested command completed successfully. |
| @retval EFI_INVALID_PARAMETER This is NULL. |
| @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0. |
| @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output |
| parameters. |
| OutBufferLength has been updated to the required value. |
| @retval EFI_UNSUPPORTED Attribis not supported |
| @retval EFI_NO_MEDIA There is no card in the reader and Attrib value |
| requires one. |
| @retval EFI_NOT_READY Attrib requires a powered card to operate. |
| @retval EFI_PROTOCOL_ERROR A protocol error has occurred. |
| @retval EFI_TIMEOUT The reader did not respond. |
| @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB) ( |
| IN EFI_SMART_CARD_READER_PROTOCOL *This, |
| IN UINT32 Attrib, |
| OUT UINT8 *OutBuffer, |
| IN OUT UINTN *OutBufferLength |
| ); |
| |
| /// |
| /// Smart card aware application invokes this protocol to get access to an inserted |
| /// smart card in the reader or to the reader itself. |
| /// |
| struct _EFI_SMART_CARD_READER_PROTOCOL { |
| EFI_SMART_CARD_READER_CONNECT SCardConnect; |
| EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect; |
| EFI_SMART_CARD_READER_STATUS SCardStatus; |
| EFI_SMART_CARD_READER_TRANSMIT SCardTransmit; |
| EFI_SMART_CARD_READER_CONTROL SCardControl; |
| EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib; |
| }; |
| |
| extern EFI_GUID gEfiSmartCardReaderProtocolGuid; |
| |
| #endif |
| |