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