MdePkg/Include/Protocol/SmartCardReader.h

   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