1 /** @file 2 The UEFI Smart Card Reader Protocol provides an abstraction for device to provide 3 smart card reader support. This protocol is very close to Part 5 of PC/SC workgroup 4 specifications and provides an API to applications willing to communicate with a 5 smart card or a smart card reader. 6 7 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> 8 SPDX-License-Identifier: BSD-2-Clause-Patent 9 10 **/ 11 12 #ifndef __SMART_CARD_READER_H__ 13 #define __SMART_CARD_READER_H__ 14 15 #define EFI_SMART_CARD_READER_PROTOCOL_GUID \ 16 { \ 17 0x2a4d1adf, 0x21dc, 0x4b81, {0xa4, 0x2f, 0x8b, 0x8e, 0xe2, 0x38, 0x00, 0x60} \ 18 } 19 20 typedef struct _EFI_SMART_CARD_READER_PROTOCOL EFI_SMART_CARD_READER_PROTOCOL; 21 22 // 23 // Codes for access mode 24 // 25 #define SCARD_AM_READER 0x0001 // Exclusive access to reader 26 #define SCARD_AM_CARD 0x0002 // Exclusive access to card 27 // 28 // Codes for card action 29 // 30 #define SCARD_CA_NORESET 0x0000 // Don't reset card 31 #define SCARD_CA_COLDRESET 0x0001 // Perform a cold reset 32 #define SCARD_CA_WARMRESET 0x0002 // Perform a warm reset 33 #define SCARD_CA_UNPOWER 0x0003 // Power off the card 34 #define SCARD_CA_EJECT 0x0004 // Eject the card 35 // 36 // Protocol types 37 // 38 #define SCARD_PROTOCOL_UNDEFINED 0x0000 39 #define SCARD_PROTOCOL_T0 0x0001 40 #define SCARD_PROTOCOL_T1 0x0002 41 #define SCARD_PROTOCOL_RAW 0x0004 42 // 43 // Codes for state type 44 // 45 #define SCARD_UNKNOWN 0x0000 /* state is unknown */ 46 #define SCARD_ABSENT 0x0001 /* Card is absent */ 47 #define SCARD_INACTIVE 0x0002 /* Card is present and not powered*/ 48 #define SCARD_ACTIVE 0x0003 /* Card is present and powered */ 49 // 50 // Macro to generate a ControlCode & PC/SC part 10 control code 51 // 52 #define SCARD_CTL_CODE(code) (0x42000000 + (code)) 53 #define CM_IOCTL_GET_FEATURE_REQUEST SCARD_CTL_CODE(3400) 54 55 /** 56 This function requests connection to the smart card or the reader, using the 57 appropriate reset type and protocol. 58 59 The SCardConnectfunction requests access to the smart card or the reader. Upon 60 success, it is then possible to call SCardTransmit. 61 62 If AccessMode is set to SCARD_AM_READER, PreferredProtocols must be set to 63 SCARD_PROTOCOL_UNDEFINED and CardAction to SCARD_CA_NORESET else function 64 fails with EFI_INVALID_PARAMETER. 65 66 @param[in] This Indicates a pointer to the calling context. 67 @param[in] AccessMode Codes of access mode. 68 @param[in] CardAction SCARD_CA_NORESET, SCARD_CA_COLDRESET or 69 SCARD_CA_WARMRESET. 70 @param[in] PreferredProtocols Bitmask of acceptable protocols. 71 @param[out] ActiveProtocol A flag that indicates the active protocol. 72 73 @retval EFI_SUCCESS The requested command completed successfully. 74 @retval EFI_INVALID_PARAMETER This is NULL 75 @retval EFI_INVALID_PARAMETER AccessMode is not valid. 76 @retval EFI_INVALID_PARAMETER CardAction is not valid. 77 @retval EFI_INVALID_PARAMETER Invalid combination of AccessMode/CardAction/ 78 PreferredProtocols. 79 @retval EFI_NOT_READY A smart card is inserted but failed to return an ATR. 80 @retval EFI_UNSUPPORTED PreferredProtocols does not contain an available 81 protocol to use. 82 @retval EFI_NO_MEDIA AccessMode is set to SCARD_AM_CARD but there is 83 no smart card inserted. 84 @retval EFI_ACCESS_DENIED Access is already locked by a previous SCardConnectcall. 85 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. 86 87 **/ 88 typedef 89 EFI_STATUS 90 (EFIAPI *EFI_SMART_CARD_READER_CONNECT)( 91 IN EFI_SMART_CARD_READER_PROTOCOL *This, 92 IN UINT32 AccessMode, 93 IN UINT32 CardAction, 94 IN UINT32 PreferredProtocols, 95 OUT UINT32 *ActiveProtocol 96 ); 97 98 /** 99 This function releases a connection previously taken by SCardConnect. 100 101 The SCardDisconnect function releases the lock previously taken by SCardConnect. 102 In case the smart card has been removed before this call, thisfunction 103 returns EFI_SUCCESS. If there is no previous call to SCardConnect, this 104 function returns EFI_SUCCESS. 105 106 @param[in] This Indicates a pointer to the calling context. 107 @param[in] CardAction Codes for card action. 108 109 @retval EFI_SUCCESS The requested command completed successfully. 110 @retval EFI_INVALID_PARAMETER This is NULL 111 @retval EFI_INVALID_PARAMETER CardAction value is unknown. 112 @retval EFI_UNSUPPORTED Reader does not support Eject card feature 113 (disconnect was not performed). 114 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. 115 116 **/ 117 typedef 118 EFI_STATUS 119 (EFIAPI *EFI_SMART_CARD_READER_DISCONNECT)( 120 IN EFI_SMART_CARD_READER_PROTOCOL *This, 121 IN UINT32 CardAction 122 ); 123 124 /** 125 This function retrieves some basic information about the smart card and reader. 126 127 The SCardStatusfunction retrieves basic reader and card information. 128 129 If ReaderName, State, CardProtocolor Atris NULL, the function does not fail but 130 does not fill in such variables. 131 132 If EFI_SUCCESS is not returned, ReaderName and Atr contents shall not be considered 133 as valid. 134 135 @param[in] This Indicates a pointer to the calling context. 136 @param[out] ReaderName A pointer to a NULL terminated string that will 137 contain the reader name. 138 @param[in, out] ReaderNameLength On input, a pointer to the variablethat holds the 139 maximal size, in bytes,of ReaderName. 140 On output, the required size, in bytes, for ReaderName. 141 @param[out] State Current state of the smart card reader. 142 @param[out] CardProtocol Current protocol used to communicate with the smart card. 143 @param[out] Atr A pointer to retrieve the ATR of the smart card. 144 @param[in, out] AtrLength On input, a pointer to hold the maximum size, in bytes, 145 of Atr(usually 33). 146 On output, the required size, inbytes, for the smart 147 card ATR. 148 149 @retval EFI_SUCCESS The requested command completed successfully. 150 @retval EFI_INVALID_PARAMETER This is NULL 151 @retval EFI_INVALID_PARAMETER ReaderName is not NULL but ReaderNameLength is NULL 152 @retval EFI_INVALID_PARAMETER Atr is not NULL but AtrLength is NULL 153 @retval EFI_BUFFER_TOO_SMALL ReaderNameLength is not big enough to hold the reader name. 154 ReaderNameLength has been updated to the required value. 155 @retval EFI_BUFFER_TOO_SMALL AtrLength is not big enough to hold the ATR. 156 AtrLength has been updated to the required value. 157 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. 158 159 **/ 160 typedef 161 EFI_STATUS 162 (EFIAPI *EFI_SMART_CARD_READER_STATUS)( 163 IN EFI_SMART_CARD_READER_PROTOCOL *This, 164 OUT CHAR16 *ReaderName OPTIONAL, 165 IN OUT UINTN *ReaderNameLength OPTIONAL, 166 OUT UINT32 *State OPTIONAL, 167 OUT UINT32 *CardProtocol OPTIONAL, 168 OUT UINT8 *Atr OPTIONAL, 169 IN OUT UINTN *AtrLength OPTIONAL 170 ); 171 172 /** 173 This function sends a command to the card or reader and returns its response. 174 175 The protocol to use to communicate with the smart card has been selected through 176 SCardConnectcall. 177 178 In case RAPDULength indicates a buffer too small to holdthe response APDU, the 179 function fails with EFI_BUFFER_TOO_SMALL. 180 181 @param[in] This A pointer to the EFI_USBFN_IO_PROTOCOLinstance. 182 @param[in] CAPDU A pointer to a byte array thatcontains the Command 183 APDU to send to the smart card or reader. 184 @param[in] CAPDULength Command APDU size, in bytes. 185 @param[out] RAPDU A pointer to a byte array that will contain the 186 Response APDU. 187 @param[in, out] RAPDULength On input, the maximum size, inbytes, of the Response 188 APDU. 189 On output, the size, in bytes, of the Response APDU. 190 191 @retval EFI_SUCCESS The requested command completed successfully. 192 @retval EFI_INVALID_PARAMETER This is NULL. 193 @retval EFI_INVALID_PARAMETER CAPDU is NULL or CAPDULength is 0. 194 @retval EFI_BUFFER_TOO_SMALL RAPDULength is not big enough to hold the response APDU. 195 RAPDULength has been updated to the required value. 196 @retval EFI_NO_MEDIA There is no card in the reader. 197 @retval EFI_NOT_READY Card is not powered. 198 @retval EFI_PROTOCOL_ERROR A protocol error has occurred. 199 @retval EFI_TIMEOUT The reader did not respond. 200 @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. 201 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. 202 203 **/ 204 typedef 205 EFI_STATUS 206 (EFIAPI *EFI_SMART_CARD_READER_TRANSMIT)( 207 IN EFI_SMART_CARD_READER_PROTOCOL *This, 208 IN UINT8 *CAPDU, 209 IN UINTN CAPDULength, 210 OUT UINT8 *RAPDU, 211 IN OUT UINTN *RAPDULength 212 ); 213 214 /** 215 This function provides direct access to the reader. 216 217 This function gives direct control to send commands to the driver or the reader. 218 The ControlCode to use is vendor dependant; the only standard code defined is 219 the one to get PC/SC part 10 features. 220 221 InBuffer and Outbuffer may be NULL when ControlCode operation does not require 222 them. 223 224 @param[in] This Indicates a pointer to the calling context. 225 @param[in] ControlCode The control code for the operation to perform. 226 @param[in] InBuffer A pointer to the input parameters. 227 @param[in] InBufferLength Size, in bytes, of input parameters. 228 @param[out] OutBuffer A pointer to the output parameters. 229 @param[in, out] OutBufferLength On input, maximal size, in bytes, to store output 230 parameters. 231 On output, the size, in bytes, of output parameters. 232 233 @retval EFI_SUCCESS The requested command completed successfully. 234 @retval EFI_INVALID_PARAMETER This is NULL. 235 @retval EFI_INVALID_PARAMETER ControlCode requires input parameters but: 236 InBuffer is NULL or InBufferLenth is NULL or 237 InBuffer is not NULL but InBufferLenth is less than 238 expected. 239 @retval EFI_INVALID_PARAMETER OutBuffer is not NULL but OutBufferLength is NULL. 240 @retval EFI_UNSUPPORTED ControlCode is not supported. 241 @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output 242 parameters. 243 OutBufferLength has been updated to the required value. 244 @retval EFI_NO_MEDIA There is no card in the reader and the control code 245 specified requires one. 246 @retval EFI_NOT_READY ControlCode requires a powered card to operate. 247 @retval EFI_PROTOCOL_ERROR A protocol error has occurred. 248 @retval EFI_TIMEOUT The reader did not respond. 249 @retval EFI_ACCESS_DENIED A communication with the reader/card is already pending. 250 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. 251 252 **/ 253 typedef 254 EFI_STATUS 255 (EFIAPI *EFI_SMART_CARD_READER_CONTROL)( 256 IN EFI_SMART_CARD_READER_PROTOCOL *This, 257 IN UINT32 ControlCode, 258 IN UINT8 *InBuffer OPTIONAL, 259 IN UINTN InBufferLength OPTIONAL, 260 OUT UINT8 *OutBuffer OPTIONAL, 261 IN OUT UINTN *OutBufferLength OPTIONAL 262 ); 263 264 /** 265 This function retrieves a reader or smart card attribute. 266 267 Possibly supported attrib values are listed in "PC/SC specification, Part 3: 268 Requirements for PC-Connected Interface Devices". 269 270 @param[in] This Indicates a pointer to the calling context. 271 @param[in] Attrib Identifier for the attribute to retrieve. 272 @param[out] OutBuffer A pointer to a buffer that will contain 273 attribute data. 274 @param[in, out] OutBufferLength On input, maximal size, in bytes, to store 275 attribute data. 276 On output, the size, in bytes, of attribute 277 data. 278 279 @retval EFI_SUCCESS The requested command completed successfully. 280 @retval EFI_INVALID_PARAMETER This is NULL. 281 @retval EFI_INVALID_PARAMETER OutBuffer is NULL or OutBufferLength is 0. 282 @retval EFI_BUFFER_TOO_SMALL OutBufferLength is not big enough to hold the output 283 parameters. 284 OutBufferLength has been updated to the required value. 285 @retval EFI_UNSUPPORTED Attribis not supported 286 @retval EFI_NO_MEDIA There is no card in the reader and Attrib value 287 requires one. 288 @retval EFI_NOT_READY Attrib requires a powered card to operate. 289 @retval EFI_PROTOCOL_ERROR A protocol error has occurred. 290 @retval EFI_TIMEOUT The reader did not respond. 291 @retval EFI_DEVICE_ERROR Any other error condition, typically a reader removal. 292 293 **/ 294 typedef 295 EFI_STATUS 296 (EFIAPI *EFI_SMART_CARD_READER_GET_ATTRIB)( 297 IN EFI_SMART_CARD_READER_PROTOCOL *This, 298 IN UINT32 Attrib, 299 OUT UINT8 *OutBuffer, 300 IN OUT UINTN *OutBufferLength 301 ); 302 303 /// 304 /// Smart card aware application invokes this protocol to get access to an inserted 305 /// smart card in the reader or to the reader itself. 306 /// 307 struct _EFI_SMART_CARD_READER_PROTOCOL { 308 EFI_SMART_CARD_READER_CONNECT SCardConnect; 309 EFI_SMART_CARD_READER_DISCONNECT SCardDisconnect; 310 EFI_SMART_CARD_READER_STATUS SCardStatus; 311 EFI_SMART_CARD_READER_TRANSMIT SCardTransmit; 312 EFI_SMART_CARD_READER_CONTROL SCardControl; 313 EFI_SMART_CARD_READER_GET_ATTRIB SCardGetAttrib; 314 }; 315 316 extern EFI_GUID gEfiSmartCardReaderProtocolGuid; 317 318 #endif 319